api-docs-generator

The api-docs-generator is a specialized software agent skill designed to bridge the gap between evolving source code and technical documentation. By monitoring code changes, this tool ensures that API specifications remain accurate and accessible without manual intervention. It is built for engineering teams and developers who manage complex backend services and require consistent documentation across various formats including OpenAPI and Markdown. Its primary goal is to minimize the overhead of manual updates, reducing the likelihood of discrepancies between code implementation and documentation.

• Automatically analyzes repository code changes to detect impacts on API endpoints and schemas.

• Generates and maintains structured OpenAPI specifications directly from source code annotations.

• Updates and synchronizes project-level Markdown documentation to reflect architectural shifts.

• Integrates with documentation hosting platforms like GitHub Pages for seamless deployment.

• Provides comprehensive error handling and graceful degradation during parsing or deployment failures.

• Ensures long-term consistency across disparate documentation formats, preventing stale information.

• Ideal for projects with high-frequency updates where keeping docs in sync is a weekly operational challenge.

• Best triggered by git commits or pull requests that involve public-facing API signatures or interface changes.

• Expects clean, annotated source code as input; generates human-readable Markdown and machine-readable JSON/YAML OpenAPI files as output.

• Token budget management is a core priority, optimized for recurring weekly operations within the Claude Code ecosystem.

• Use in conjunction with static analysis tools and code-review subagents for a holistic documentation-as-code workflow.

• Be aware of the skill's complex dependency requirements when parsing custom languages or non-standard API decorators.