AI & MCP

Agent skills for OpenAPI and SDK generation

Vishal Gowda

February 3, 2026 - 3 min read

AI & MCP

---

AI agents are becoming essential development tools, but they often struggle with specialized domains like OpenAPI and SDK generation. Without the right context, agents default to their training data, which may be outdated or incomplete. They guess at configuration options, miss best practices, and produce specs that need significant manual cleanup.

We’ve released a collection of agent skills that give AI assistants the knowledge they need to work effectively with OpenAPI specifications and the Speakeasy CLI. These skills work with Claude Code, Cursor, Windsurf, GitHub Copilot, Gemini CLI, and the 15+ other tools that support the skills specification.

npx skills add speakeasy-api/skills

What are agent skills?

Agent skills are markdown files that provide targeted instructions for AI coding assistants. When you install a skill, its frontmatter (the metadata at the top of the file) gets loaded into the agent’s context. This frontmatter includes trigger conditions that tell the agent when to read the full skill content.

The approach is lightweight by design. Unlike plugins or extensions that require custom integrations, skills are just markdown files that any agent can read. The skill’s description acts as an activation trigger, so the agent only loads the full content when working on a relevant task.

Available skills

The collection includes 21 skills covering the full lifecycle of API development, from writing specs to generating and customizing SDKs across seven languages.

While these skills include guidance specific to the Speakeasy CLI, much of the content applies to anyone working with OpenAPI. The “Writing OpenAPI specs” skill covers general best practices that improve any API specification. The overlay management skill applies to any OpenAPI toolchain. The extraction skills help regardless of what you plan to do with the resulting spec.

Our approach to skill design

The design of these skills was influenced by Vercel’s research on agent skills . Their key finding: focused, use-case-specific skills outperform broad meta-skills. An agent trying to decide when to activate a skill with a vague trigger like “SDK generation best practices” will often fail to activate it at the right time, or activate it when it’s not needed.

We’ve applied this principle throughout. Rather than a single comprehensive skill for SDK generation, we have separate skills for each language, for starting a new project, for diagnosing failures, and for customizing hooks. Each skill has a specific trigger condition that makes activation clear.

This approach also keeps individual skills small, which matters because skill content competes for context window space. A focused skill that solves one problem well is more valuable than a comprehensive guide that fills up the context before the agent can do useful work.

We also run evals to measure skill efficacy, testing how reliably agents complete tasks with each skill enabled. The same PR that adds evals to measure skill efficacy also provides input to refine skills further. These evals help us continuously improve skill content, trigger conditions, and scope over time.

What’s next

We built these skills because we want better OpenAPI specs everywhere. Better specs lead to better SDKs, better documentation, and better developer experiences. If an AI agent can help developers write cleaner specs and catch common mistakes earlier, that benefits the entire ecosystem.

Skills also reduce the entry barrier for using Speakeasy. Beyond authoring great OpenAPI specs, they help developers discover and apply the right configuration for SDKs without needing to read through all the documentation first.

We’re actively iterating on these skills based on real usage. Try the skills and let us know what works and what doesn’t. The repository is open source and we welcome contributions.

npx skills add speakeasy-api/skills