🎯

create-openapi-overlay

🎯Skill

from speakeasy-api/agent-skills

What it does

Creates a customizable OpenAPI overlay file to modify SDK generation behavior without directly editing the source OpenAPI specification.

create-openapi-overlay

Installation

Install skill:

npx skills add https://github.com/speakeasy-api/agent-skills --skill create-openapi-overlay

Last UpdatedJan 26, 2026

View on GitHub Back to Skills

Skill Details

SKILL.md

Overview

Docs Quickstart // Join us on Slack

[![LW24 participant](https://img.shields.io/badge/featured-LW24-8957E5.svg?style=flat-square&labelColor=0D1117&logo=data:image/svg%2bxml;base64,PHN2ZyB3aWR0aD0iMzYwIiBoZWlnaHQ9IjM2MCIgdmlld0JveD0iMCAwIDM2MCAzNjAiIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+IDxyZWN0IHdpZHRoPSI2MCIgaGVpZ2h0PSIzMDAiIGZpbGw9IndoaXRlIi8+IDxyZWN0IHg9IjYwIiB5PSIzMDAiIHdpZHRoPSIxMjAiIGhlaWdodD0iNjAiIGZpbGw9IndoaXRlIi8+IDxyZWN0IHg9IjI0MCIgeT0iMzAwIiB3aWR0aD0iNjAiIGhlaWdodD0iNjAiIGZpbGw9IndoaXRlIi8+IDxyZWN0IHg9IjMwMCIgd2lkdGg9IjYwIiBoZWlnaHQ9IjMwMCIgZmlsbD0id2hpdGUiLz4gPHJlY3QgeD0iMTgwIiB3aWR0aD0iNjAiIGhlaWdodD0iMzAwIiBmaWxsPSJ3aGl0ZSIvPiA8L3N2Zz4=)](https://launchweek.dev/lw/2024/mega#participants)

# Speakeasy Agent Skills

A collection of [Agent Skills](https://agentskills.io/) for SDK generation and OpenAPI tooling with the [Speakeasy CLI](https://speakeasy.com/).

Installation

```bash

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

└── LI

More from this repository10

🎯

validate-openapi-spec🎯Skill

Validates an OpenAPI specification by running the `speakeasy lint` command to check for specification correctness and potential issues.

🎯

get-ai-suggestions🎯Skill

Provides AI-powered recommendations for improving SDK method names and operation IDs to enhance code readability and developer experience.

🎯

configure-authentication🎯Skill

Configures authentication settings for SDK generation, helping users set up secure API access credentials and authentication methods.

🎯

apply-openapi-overlay🎯Skill

Applies an OpenAPI overlay file to modify or enhance an existing OpenAPI specification without directly editing the source spec.

🎯

merge-openapi-specs🎯Skill

Merges multiple OpenAPI specification files into a single, consolidated OpenAPI specification document.

🎯

fix-validation-errors-with-overlays🎯Skill

Automatically identifies and resolves OpenAPI specification validation errors by generating and applying targeted overlay files.

🎯

regenerate-sdk🎯Skill

Regenerates an SDK when the underlying OpenAPI specification has been modified, ensuring the client library stays up-to-date with the latest API changes.

🎯

start-new-sdk-project🎯Skill

Guides developers through generating a new SDK from an OpenAPI specification, walking them step-by-step through the initial SDK project setup process.

🎯

improve-operation-ids🎯Skill

Improves and refines operation IDs in an OpenAPI specification to generate more readable and meaningful SDK method names.

🎯

check-workspace-status🎯Skill

Checks and reports the current configuration of SDK generation targets and sources in the Speakeasy workspace.