skills

Speakeasy workflow: run 'agent context' FIRST, do task, run 'agent feedback' LAST. Triggers on speakeasy, SDK, OpenAPI.

Use when generating an MCP server from an OpenAPI spec with Speakeasy. Triggers on "generate MCP server", "MCP server", "Model Context Protocol", "AI assistant tools", "Claude tools", "speakeasy MCP", "mcp-typescript"

Use when CONFIGURING an existing SDK - NOT for initial generation. Covers gen.yaml configuration for all languages: TypeScript, Python, Go, Java, C#, PHP, Ruby. Also covers runtime overrides (retries, timeouts, server selection) in application code. Triggers on "configure SDK", "gen.yaml", "SDK options", "SDK config", "SDK configuration", "runtime override", "SDK client config", "override timeout", "per-call config". For NEW SDK generation, use start-new-sdk-project instead.

Use when creating, applying, or validating overlay files including x-speakeasy extensions. Covers overlay syntax, JSONPath targeting, retries, pagination, naming, grouping, open enums, global headers, custom security. Triggers on "create overlay", "apply overlay", "overlay file", "x-speakeasy", "add extension", "configure retries", "add pagination", "overlay for retries".

Use when generating SDKs for multiple languages from a single OpenAPI spec, or multiple SDK variants from different sources. Covers workflow.yaml multi-target configuration, per-language gen.yaml, monorepo structure. Triggers on "multiple SDKs", "multi-language SDK", "SDK for each language", "multi-target SDK", "SDK monorepo", "generate SDKs for".

Use when extracting or generating an OpenAPI spec from existing API code. Triggers on "extract OpenAPI", "code first", "generate spec from code", "FastAPI OpenAPI", "Spring Boot OpenAPI", "NestJS swagger", "Django OpenAPI", "Flask OpenAPI", "Rails swagger", "Laravel OpenAPI", "existing API code"

Use when generating a Terraform provider from an OpenAPI spec with Speakeasy. Covers entity annotations, CRUD mapping, type inference, workflow configuration, and publishing. Triggers on "terraform provider", "generate terraform", "create terraform provider", "CRUD mapping", "x-speakeasy-entity", "terraform resource", "terraform registry".

Use when setting up SDK testing, configuring contract tests, writing Arazzo test workflows, or running integration tests. Triggers on "SDK testing", "test SDK", "contract testing", "Arazzo tests", "integration tests", "speakeasy test", "mock server", "test generation", "ResponseValidationError"

Use when implementing SDK code hooks for custom logic (not spec configuration or runtime overrides). Covers SDK lifecycle hooks: BeforeRequest, AfterSuccess, AfterError for custom headers, telemetry, HMAC signing, and request/response transformation. Triggers on "SDK hooks", "add hooks", "BeforeRequestHook", "custom logic in SDK", "telemetry hook", "SDK middleware", "intercept requests", "HMAC signing hook", "custom code in hooks directory".

Use when you want AI-powered suggestions for SDK naming improvements via the `speakeasy suggest` command (not manual overlay creation). Triggers on "suggest improvements", "speakeasy suggest", "AI suggestions", "suggest operation-ids", "suggest error-types", "auto-improve naming", "get AI recommendations".

Use when generating a new SDK from an OpenAPI spec. This is the PRIMARY skill for SDK generation. Triggers on "create SDK", "generate SDK", "new SDK", "quickstart", "TypeScript SDK", "Python SDK", "Go SDK", "Java SDK", "generate TypeScript", "generate Python", "generate Go", "make SDK", "build SDK", "SDK from OpenAPI", "SDK from spec", "initialize SDK project".

Use when each language SDK lives in a separate repository. Covers cross-repo workflow dispatch, PR status reporting, PR reconciliation on merge/close. Triggers on "multi-repo SDK", "separate SDK repositories", "cross-repo workflows", "SDK PR synchronization", "spec repo triggers SDK repos".

Use when SDK generation failed or seeing errors. Triggers on "generation failed", "speakeasy run failed", "SDK build error", "workflow failed", "Step Failed", "why did generation fail"

Reference guide for OpenAPI specification best practices, naming conventions, and expressing complex REST API patterns like polymorphism, enums, file uploads, and server-sent events. Use when writing or improving OpenAPI specs to ensure they follow established conventions and generate quality SDKs.