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
-
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
-
AI-friendly output - Use
speakeasy run --output consolefor structured output, pipe togrep/tailto reduce context -
Overlay over modify - Never modify source specs directly. Overlays make patches portable across spec versions.
-
Grouped SDK methods - Guide users toward
sdk.users.list()pattern usingx-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:
License
Apache-2.0