Speakeasy Logo
Skip to Content
DocumentationSpeakeasySkills for Claude Code

Skills for Claude Code

Speakeasy provides a collection of skills that enable Claude Code to help with SDK generation, OpenAPI spec management, Terraform provider creation, and more. These skills give Claude deep knowledge of Speakeasy best practices and workflows.

Installation

Add Speakeasy skills to Claude Code with a single command:

npx skills add speakeasy-api/agent-skills

After installation, Claude Code can assist with all Speakeasy-related tasks using these specialized skills.

Available skills

start-new-sdk-project

Initialize a new SDK project with speakeasy quickstart. Use this skill when starting a brand new SDK project or setting up Speakeasy for the first time.

Triggers: “create SDK”, “generate SDK”, “new SDK”, “quickstart”, “get started with Speakeasy”

Capabilities:

  • Generate SDKs from local OpenAPI files, URLs, or registry sources
  • Support for TypeScript, Python, Go, Java, C#, PHP, Ruby, Kotlin, and Terraform
  • Create workflow configuration files automatically

sdk-tf-generation-best-practices

Comprehensive best-practices reference for generating SDKs and Terraform providers. This skill covers the full lifecycle from OpenAPI spec preparation to testing.

Triggers: “generate SDK”, “regenerate SDK”, “SDK best practices”, “terraform provider”, “SDK customization”

Capabilities:

  • SDK generation workflows and patterns
  • Code-first OpenAPI extraction (FastAPI, Flask, Django, Spring Boot, NestJS, Hono, Rails, Laravel)
  • Language-specific SDK guides
  • Multi-target and multi-repo SDK generation
  • Version management and upgrades

generate-mcp-server

Generate a Model Context Protocol (MCP) server from an OpenAPI spec. The MCP server exposes API operations as tools that AI assistants like Claude can call directly.

Triggers: “generate MCP server”, “MCP server”, “Model Context Protocol”, “AI assistant tools”, “Claude tools”

Capabilities:

  • Create MCP servers from OpenAPI specs
  • Configure scope-based access control for tools
  • Deploy with stdio or SSE transports
  • Integration with Claude Desktop and Claude Code

generate-terraform-provider

Generate a Terraform provider from an OpenAPI specification. This skill covers entity annotations, CRUD mapping, type inference, workflow configuration, and publishing.

Triggers: “terraform provider”, “generate terraform”, “CRUD mapping”, “x-speakeasy-entity”

Capabilities:

  • Annotate OpenAPI specs with Terraform entity metadata
  • Map API operations to Terraform CRUD methods
  • Configure workflow.yaml for Terraform generation
  • Publish providers to the Terraform Registry

customize-sdk-hooks

Implement SDK lifecycle hooks to customize request/response behavior. Hooks allow adding custom headers, telemetry, security signatures, and error handling.

Triggers: “SDK hooks”, “add hooks”, “BeforeRequestHook”, “custom user-agent”, “telemetry hook”

Capabilities:

  • Add custom headers to every SDK request
  • Implement telemetry and observability
  • Add custom authentication logic (HMAC signatures, token refresh)
  • Transform responses or errors before they reach the caller

customize-sdk-runtime

Configure runtime behavior for Speakeasy-generated SDKs including retries, timeouts, pagination, server selection, and error handling.

Triggers: “SDK retries”, “timeout configuration”, “pagination config”, “server selection”, “error handling”

Capabilities:

  • Configure global and per-operation retry logic
  • Set timeouts at the document or operation level
  • Add pagination support to list endpoints
  • Select between multiple server environments

manage-openapi-overlays

Create, apply, and manage overlays to customize SDK generation without modifying the source OpenAPI spec.

Triggers: “create overlay”, “apply overlay”, “customize SDK”, “can’t modify spec”, “fix with overlay”

Capabilities:

  • Create overlay files with JSONPath-targeted changes
  • Apply overlays to OpenAPI specs
  • Fix validation issues without editing source files
  • Add x-speakeasy extensions for grouping, naming, and retries

improve-sdk-naming

Improve SDK method naming using AI-powered suggestions or manual overrides. Transform ugly auto-generated names into clean, grouped methods.

Triggers: “suggest improvements”, “better operation names”, “ugly method names”, “improve operation IDs”

Capabilities:

  • AI-generated suggestions for operation IDs
  • Manual naming with x-speakeasy-group and x-speakeasy-name-override
  • Transform GetApiV1Users into sdk.users.list()
  • Suggest error type definitions

diagnose-generation-failure

Diagnose and fix SDK generation failures. This skill helps identify root causes and determine the appropriate fix strategy.

Triggers: “generation failed”, “speakeasy run failed”, “SDK build error”, “workflow failed”

Capabilities:

  • Run lint to get detailed error information
  • Categorize issues as fixable with overlays or requiring spec fixes
  • Create strategy documents for complex issues
  • Identify blocking issues that require user input

extract-openapi-from-code

Extract an OpenAPI specification from an existing API codebase. Supports eight major frameworks across Python, Java, JavaScript/TypeScript, Ruby, and PHP.

Triggers: “extract OpenAPI”, “code first”, “generate spec from code”, “FastAPI OpenAPI”

Supported frameworks:

  • Python: FastAPI, Flask (flask-smorest), Django REST Framework
  • Java: Spring Boot (springdoc)
  • TypeScript: NestJS, Hono (zod-openapi)
  • Ruby: Rails (rswag)
  • PHP: Laravel (l5-swagger)

setup-sdk-testing

Set up and run tests for Speakeasy-generated SDKs using contract testing, custom Arazzo workflows, or integration tests against live APIs.

Triggers: “SDK testing”, “test SDK”, “contract testing”, “Arazzo tests”, “integration tests”

Capabilities:

  • Enable contract test generation via gen.yaml
  • Write custom multi-step API workflow tests with Arazzo
  • Configure integration tests against live APIs
  • Debug ResponseValidationError and test failures

writing-openapi-specs

Reference guide for OpenAPI specification best practices, naming conventions, and expressing complex REST API patterns.

Triggers: Writing or improving OpenAPI specs, polymorphism, enums, file uploads, server-sent events

Capabilities:

  • Operation ID naming conventions
  • Documentation standards with CommonMark
  • Component reusability patterns
  • Complex patterns (enums, polymorphism, nullable types)

Usage example

After installing the skills, ask Claude Code to help with any Speakeasy task:

Generate a TypeScript SDK from my OpenAPI spec at ./api/openapi.yaml
Add retry configuration to my SDK with exponential backoff
Create an overlay to fix the operation naming in my spec
Set up contract testing for my generated SDK

Claude Code will use the appropriate skill to provide step-by-step guidance and execute the necessary commands.

Last updated on