What should I do if my Speakeasy SDK generation fails?

Use this skill to run 'speakeasy lint' and categorize the errors into spec fixes or overlays based on the built-in decision framework.

When should I use the strategy document feature?

Use it for complex failures where multiple blocking issues require human input or when you need a clear roadmap of proposed overlay fixes.

Can this skill automatically fix my OpenAPI spec?

It identifies issues and suggests strategies; it can propose overlays for missing metadata but will always ask for user permission before modifying source files.

How does this skill handle circular references in API specs?

It identifies them as structural issues and prompts the user for a design decision, as circular references often require architectural changes rather than simple automated fixes.

What are Speakeasy overlays?

Overlays are sidecar files that allow you to modify or enhance your OpenAPI specification for SDK generation purposes without changing the original source document.

Speakeasy SDK Generation Diagnosis

Name: Speakeasy SDK Generation Diagnosis
Author: speakeasy-api

byspeakeasy-api

•

378

•

API Development

Troubleshoots and resolves SDK generation failures by analyzing OpenAPI specifications and applying optimal fix strategies.

This skill empowers Claude to act as an expert troubleshooter for Speakeasy SDK generation workflows, identifying the root causes of 'Step Failed' or 'speakeasy run' errors. It guides the user through a systematic diagnosis process using Speakeasy's native linting tools, categorizes issues into spec-level fixes or overlay-driven improvements, and produces structured strategy documents for complex architectural decisions. By following a strict decision framework, it ensures that SDK generation blockers like missing operation IDs or circular references are resolved using the most efficient methods available.

Key Features

01Structured strategy documentation for complex API designs

02Detection of structural spec issues requiring human intervention

03Identification of fixable issues via Speakeasy overlays

04378 GitHub stars

05Automated OpenAPI linting and error categorization

06Decision framework for choosing between spec changes and overlays

Use Cases

01Improving OpenAPI specification quality to meet SDK generation requirements

02Automating the creation of overlay files for missing metadata like operation IDs

03Fixing 'Step Failed: Workflow' errors during Speakeasy SDK generation

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add speakeasy-api/speakeasy diagnose-generation-failure

For use in Claude.ai and ChatGPT

Download Skill