AgentSkillsCN

typespec-sdk-generator

基于 Microsoft TypeSpec 的 API 与 SDK 生成

SKILL.md
--- frontmatter
name: typespec-sdk-generator
description: Microsoft TypeSpec-based API and SDK generation
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash

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

yaml
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