home / skills / a5c-ai / babysitter / typespec-sdk-generator

typespec-sdk-generator skill

safe

/plugins/babysitter/skills/babysit/process/specializations/sdk-platform-development/skills/typespec-sdk-generator

This skill generates multi-language SDKs from TypeSpec definitions, applying Azure guidelines and emitting OpenAPI for streamlined API consumption.

npx playbooks add skill a5c-ai/babysitter --skill typespec-sdk-generator

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.9 KB

---
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

Overview

This skill uses Microsoft TypeSpec to design APIs and generate multi-language SDKs that follow Azure SDK guidelines. It produces strongly-typed clients, OpenAPI outputs, and language-specific packages for TypeScript, Python, Java, C#, and Go. The goal is reproducible, style-consistent SDK generation from TypeSpec models.

How this skill works

Provide TypeSpec model files and emitter configurations. The skill runs the TypeSpec compiler with configured emitters to produce OpenAPI, JSON Schema, documentation, and language SDK source code. It can apply Azure SDK style rules, handle versioning/deprecation, and support custom emitters or decorators for richer API semantics.

When to use it

When you have TypeSpec (.tsp) API models and need multi-language SDKs generated consistently.
When you want OpenAPI and JSON schema outputs alongside client libraries.
During CI/CD to produce reproducible SDK artifacts per release or API version.
When adopting Azure SDK guidelines and language idioms across client libraries.
When you need custom emitters or decorators to inject behavior or docs into outputs.

Best practices

Organize models with namespaces and clear inheritance to keep generated code predictable.
Use decorators for documentation, behavior, and to drive emitter-specific features.
Version APIs explicitly (e.g., @versioned) and include apiVersion in emitter configs.
Keep emitter configs per language in source control to ensure reproducible builds.
Start with Azure SDK guidelines enabled to get consistent naming, error handling, and client shapes.

Example use cases

Generate TypeScript and Python SDKs from a single TypeSpec model for a cloud service.
Emit OpenAPI and JSON Schema to feed documentation sites and contract tests.
Integrate into CI to produce language packages automatically for each release.
Prototype API design in TypeSpec and generate client libraries to validate developer experience.
Extend with custom emitters to add company-specific telemetry or validation hooks in generated clients.

FAQ

What inputs does the skill require?

TypeSpec model files (.tsp), emitter configurations, versioning info, and optional custom decorators.

Which languages are supported?

Out of the box: TypeScript, Python, Java, C#, and Go via available emitters; custom emitters can add more.

Can it enforce Azure SDK style guidelines?

Yes. The skill can apply Azure SDK recommendations automatically during generation for consistent APIs.