typespec-sdk-generator

TypeSpec SDK Generator Skill

Overview

This skill utilizes Microsoft TypeSpec (formerly Cadl) to design APIs and generate multi-language SDKs following Azure SDK guidelines. TypeSpec provides a concise, type-safe language for API definition.

Capabilities

• Design APIs using TypeSpec language
• Generate multi-language SDKs (TypeScript, Python, Java, C#, Go)
• Emit OpenAPI and other specification formats
• Apply Azure SDK style guidelines automatically
• Implement decorators for rich API semantics
• Support versioning and deprecation patterns
• Generate strongly-typed clients

Target Processes

• SDK Code Generation Pipeline
• API Design Specification
• Multi-Language SDK Strategy

Integration Points

• TypeSpec compiler and emitters
• AutoRest for SDK generation
• Azure SDK code generation pipeline
• OpenAPI emitters
• Custom emitter development

Input Requirements

• TypeSpec model files (.tsp)
• Emitter configurations per target
• Versioning requirements
• Style guide preferences
• Custom decorators (if any)

Output Artifacts

• Generated SDK source code per language
• OpenAPI specifications
• JSON schemas
• API documentation
• Client library packages

Usage Example

skill:
  name: typespec-sdk-generator
  context:
    modelDirectory: ./typespec
    emitters:
      - "@azure-tools/typespec-ts"
      - "@azure-tools/typespec-python"
      - "@typespec/openapi3"
    applyAzureGuidelines: true
    apiVersion: "2024-01-01"

Best Practices

1. Use namespaces to organize API structure
2. Leverage decorators for documentation and behavior
3. Implement proper versioning with @versioned
4. Use templates for reusable patterns
5. Define clear model inheritance hierarchies
6. Apply Azure SDK guidelines for consistency