afd-contracts

Generate OpenAPI, TypeScript, and Python Pydantic models from TypeSpec definitions.

4|1|Updated Dec 30, 2025
One-click install
npx skills add https://github.com/lushly-dev/afd --skill afd-contracts
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: afd-contracts
Source: https://github.com/lushly-dev/afd/tree/main/.claude/skills/afd-contracts
Command: npx skills add https://github.com/lushly-dev/afd --skill afd-contracts

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @typespec/compiler, @typespec/openapi3, @typespec/http, @typespec/rest, openapi-typescript, datamodel-code-generator, and includes scripts (resource) and references (resource) components.

What problem does it solve?

This Skill prevents inconsistencies and runtime errors caused by schema drift between different codebases (e.g., frontend, backend, database) by using a single source of truth for type definitions.

Core Features & Use Cases

  • Single Source of Truth: Define your data models once using TypeSpec.
  • Automated Code Generation: Automatically generate OpenAPI specs, TypeScript types, and Python Pydantic models from your TypeSpec definitions.
  • Cross-Layer Type Safety: Ensures that your API contracts remain consistent across all layers of your application, preventing "schema drift bugs."
  • Use Case: When your Python backend and TypeScript frontend start throwing errors because the loraId field is expected as a string in one place and can be null in another, this skill enforces a unified definition.

Quick Start

Run the command to generate all contract types from your TypeSpec files.

Frequently Asked Questions about afd-contracts

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I prevent schema drift between my Python backend and TypeScript frontend?

To prevent schema drift, you can define your data models once using TypeSpec and automatically generate OpenAPI specs, TypeScript types, and Python Pydantic models. This enforces a single source of truth for cross-layer type safety.

Can I generate Pydantic models and TypeScript types from a single TypeSpec definition?

Yes, you can generate Pydantic models and TypeScript types from TypeSpec. The Skill uses datamodel-code-generator and openapi-typescript to automatically produce Python and TypeScript contracts from your TypeSpec source.

What is TypeSpec used for in API contract management?

TypeSpec acts as the single source of truth for API contract management. It allows you to define data models once and generate OpenAPI, TypeScript, and Python Pydantic schemas to ensure cross-layer consistency.

How do I generate OpenAPI specs from TypeSpec for multiple codebases?

You can generate OpenAPI specs from TypeSpec by running the provided generation command. The Skill uses the TypeSpec compiler and OpenAPI3 dependencies to produce deterministic contract definitions for your codebases.

Do I need the TypeSpec compiler to sync schemas across codebases?

Yes, the TypeSpec compiler is required to sync schemas across codebases. You also need openapi-typescript and datamodel-code-generator to generate the TypeScript and Python Pydantic models from your definitions.

What are the limitations of using TypeSpec for schema synchronization?

Using TypeSpec for schema synchronization requires specific dependencies like the TypeSpec compiler, openapi-typescript, and datamodel-code-generator. It is designed for deterministic contract enforcement across TypeScript and Python stacks.