Agent skill
diagnose-generation-failure
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/diagnose-generation-failure
SKILL.md
diagnose-generation-failure
When SDK generation fails, determine the root cause and fix strategy.
Diagnosis Steps
-
Run lint to get detailed errors:
bashspeakeasy lint openapi -s <spec-path> -
Categorize issues:
- Fixable with overlays: Missing descriptions, poor operation IDs
- Requires spec fix: Invalid schema, missing required fields
- Requires user input: Design decisions, authentication setup
Decision Framework
| 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 |
What NOT to Do
- Do NOT disable lint rules to hide errors
- Do NOT try to fix every issue one-by-one
- Do NOT modify source spec without asking
- Do NOT assume you can fix structural problems
Strategy Document
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]
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?