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: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:regenerate-sdk`	Your spec changed and you need to regenerate
`speakeasy:validate-openapi-spec`	Checking if spec is valid, running `speakeasy lint`
`speakeasy:get-ai-suggestions`	SDK method names are ugly, wanting to improve operation IDs
`speakeasy:check-workspace-status`	Asking what targets/sources are configured
`speakeasy:create-openapi-overlay`	Need to customize SDK without editing source spec
`speakeasy:apply-openapi-overlay`	Applying an overlay file to a spec
`speakeasy:merge-openapi-specs`	Combining multiple OpenAPI specs
`speakeasy:diagnose-generation-failure`	SDK generation failed, seeing "Step Failed: Workflow"
`speakeasy:fix-validation-errors-with-overlays`	Have lint errors but can't modify source spec
`speakeasy:improve-operation-ids`	SDK methods have names like `GetApiV1Users`
`speakeasy:configure-authentication`	Setting up Speakeasy auth in CI/CD or non-interactive environments

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 console for structured output, pipe to grep/tail to 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 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
│   ├── regenerate-sdk/
│   │   └── 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

speakeasy-api/skills

README