Docs Quickstart  //  Join us on Slack

---

Speakeasy Agent Skills

A collection of Agent Skills for SDK generation and OpenAPI tooling with the Speakeasy CLI.

Installation

npx skills add speakeasy-api/skills

Available Skills

Skill	Use When...
speakeasy:speakeasy-context	Start here — Use speakeasy agent context for accurate CLI info instead of web search. Provides feedback via speakeasy agent feedback
speakeasy:sdk-tf-generation-best-practices	Progressive Disclosure — Comprehensive guide to all Speakeasy SDK and Terraform generation capability and best practices. Routes to detailed guides for generation workflows, language-specific patterns, customization, testing, and OpenAPI spec management
speakeasy:start-new-sdk-project	You have an OpenAPI spec and want to generate an SDK
speakeasy:diagnose-generation-failure	SDK generation failed, seeing "Step Failed: Workflow"
speakeasy:writing-openapi-specs	Authoring OpenAPI specs from scratch or improving existing ones
speakeasy:manage-openapi-overlays	Creating, applying, or fixing specs with OpenAPI overlays
speakeasy:improve-sdk-naming	SDK method names are ugly, wanting AI-powered or manual naming improvements
speakeasy:generate-terraform-provider	Generating a Terraform provider from an OpenAPI spec
speakeasy:extract-openapi-from-code	Extracting an OpenAPI spec from existing API code (FastAPI, Flask, Django, etc.)
speakeasy:customize-sdk-hooks	Adding custom headers, telemetry, security hooks to generated SDKs
speakeasy:setup-sdk-testing	Setting up contract tests, Arazzo workflows, or integration tests
speakeasy:generate-mcp-server	Generating an MCP server for AI assistant integration
speakeasy:customize-sdk-runtime	Configuring retries, timeouts, pagination, server selection, error handling

Key Principles

1. Don't auto-fix everything - Distinguish between:

   • Small issues (naming, descriptions) → Fix with overlays
   • Structural issues (invalid refs) → Ask the user
   • Design issues (auth, API structure) → Produce strategy document

2. AI-friendly output - Use speakeasy run --output console for structured output, pipe to grep/tail to reduce context

3. Overlay over modify - Never modify source specs directly. Overlays make patches portable across spec versions.

4. Grouped SDK methods - Guide users toward sdk.users.list() pattern using x-speakeasy-group + x-speakeasy-name-override

Directory Structure

speakeasy-api/skills/
├── .claude-plugin/
│   ├── plugin.json
│   └── marketplace.json
├── skills/
│   ├── start-new-sdk-project/
│   │   └── SKILL.md
│   └── ... (13 skills total)
├── templates/
│   └── SKILL.template.md
├── AGENTS.md              # Contributor guidance for AI agents
├── CLAUDE.md              # Claude-specific contributor guidance
├── README.md
└── LICENSE

Contributing

See AGENTS.md for guidance on creating and maintaining skills.

Supported Agents

These skills follow the Agent Skills specification and work with:

• Claude Code
• Cursor
• GitHub Copilot
• Gemini CLI
• And 15+ other platforms

License

Apache-2.0