Use this skill to investigate failed SDK generation from an OpenAPI spec. It helps classify errors, identify likely root causes, and outline whether an overlay can address them, the spec needs changes, or a human decision is required.
中文简介正在准备中。当前显示英语简介。
Use when SDK generation failed or seeing errors. Triggers on "generation failed", "speakeasy run failed", "SDK build error", "workflow failed", "Step Failed", "why did generation fail"
实测评分 未实测
查看安装方法安装前可以查看交给 AI 代理的指令内容。
When SDK generation fails, diagnose the root cause and determine the fix strategy.
speakeasy run failed with errors| Input | Required | Description |
|---|---|---|
| OpenAPI spec | Yes | Path to spec that failed generation |
| Error output | Helpful | Error messages from failed run |
| Output | Description |
|---|---|
| Diagnosis | Root cause of failure |
| Fix strategy | Overlay vs spec fix vs user decision |
| Action items | Specific steps to resolve |
Run lint to get detailed errors:
speakeasy lint openapi --non-interactive -s <spec-path>
Categorize issues:
| Issue Type | Fix Strategy | Example |
|---|---|---|
| Missing operationId | Overlay | Use speakeasy suggest operation-ids |
| Missing description | Overlay | Add via overlay |
| Invalid $ref | Ask user | Broken reference needs spec fix |
| Circular reference | Ask user | Design decision needed |
| Missing security | Ask user | Auth design needed |
PROBLEM
│
├─ ResponseValidationError at runtime?
│ └─ SDK types don't match server responses
│ ├─ Run contract tests to identify mismatches
│ └─ Fix spec or create overlay to correct types
│
├─ SDK doesn't match live API behavior?
│ ├─ Spec may have drifted from API
│ │ → Run contract tests to detect drift
│ └─ Third-party spec may be inaccurate
│ → Validate with contract testing before trusting
│
├─ Type mismatch errors in generated SDK?
│ ├─ At compile time → Check spec schema definitions
│ └─ At runtime → Server returns unexpected types
│ → Contract testing required
│
└─ Enum value not recognized?
└─ API returned value not in spec enum
├─ Add missing value to spec/overlay
└─ Or use open enums for anti-fragility
Use yq (YAML) or jq (JSON) to inspect specs without loading full content:
# List all paths
yq '.paths | keys' spec.yaml
# Inspect a specific endpoint
yq '.paths["/users/{id}"]' spec.yaml
# List all schema names
yq '.components.schemas | keys' spec.yaml
# List all operationIds
yq '[.paths[][].operationId // empty] | unique' spec.yaml
For complex issues, produce a document:
## OpenAPI Spec Analysis
### Blocking Issues (require user input)
- [List issues that need human decision]
### Fixable Issues (can use overlays)
- [List issues with proposed overlay fixes]
### Recommended Approach
[Your recommendation]
manage-openapi-overlays - Fix issues with overlayssetup-sdk-testing - Contract testing for validationwriting-openapi-specs - Spec design best practices还没有评价。欢迎分享你的使用感受。
无需登录即可发表。欢迎分享使用感受、提问，或说明在哪些环境下无法运行。
还没有评论。来写第一条吧。
Guide API endpoint changes so request DTOs, runtime validation, OpenAPI documentation, and MCP tool metadata stay aligned. It covers discoverability, authentication, uploads, long-running tasks, and response types that MCP tools cannot handle.
中文简介正在准备中。当前显示英语简介。
Review specified files for design system usage, replace legacy @trycompai/ui components and lucide-react icons with available @trycompai/design-system equivalents, and run the app type check to verify the migration.
中文简介正在准备中。当前显示英语简介。
Review specified files for outdated hook and API patterns, then replace them with the prescribed SWR hooks, API clients, or server API calls. The guidance covers data fetching, mutations, cache updates, and response handling, followed by a typecheck command.
中文简介正在准备中。当前显示英语简介。
Review NestJS API endpoints and frontend components for role-based access control and audit log compliance. The skill lists permission, guard, route, and UI gating rules, then directs the agent to fix violations and run type checks.
中文简介正在准备中。当前显示英语简介。
Audit unit tests for components that use permissions. Add missing tests and fix failures, checking that administrators can use mutation controls, auditors cannot, and read-only content remains visible to both.
中文简介正在准备中。当前显示英语简介。
Set up Better Auth for TypeScript applications, including server and client configuration, database adapters, sessions, email and social sign-in, and plugins. The guide also highlights environment variables, schema generation, and security settings to review.
中文简介正在准备中。当前显示英语简介。