Extracts architecture decisions, API contracts, and usage patterns directly from code to produce accurate documentation that stays in sync with implementation. Documentation-from-code treats code as the source of truth and generates prose from it rather than maintaining documentation as a separate artifact that diverges over time.
Use cases
- Generating API reference documentation from OpenAPI specs or code annotations automatically rather than writing it by hand
- Maintaining README files that accurately describe the codebase after refactors without manual updating
- Creating architecture decision records (ADRs) from code patterns and commit history when the original decision rationale is undocumented
- Onboarding a new engineer and wanting accurate, automated documentation that reflects the current state of the codebase rather than the state from six months ago
- Producing usage guides from code examples embedded in tests or example files
Key features
- Parse function signatures, type annotations, and code comments to extract the public API surface and its documented behavior
- Extract API usage patterns from test files and example code, identifying the most common and recommended ways to use each function
- Generate draft documentation in the target format (Markdown, OpenAPI, README) directly from the parsed code
- Verify generated documentation against the actual code behavior by running the documented examples and confirming they still work
- Set up a CI check that fails when the generated documentation is out of sync with the code, enforcing that documentation cannot fall behind
When to Use This Skill
- When maintaining API documentation that frequently falls out of sync with the implementation
- When a large codebase lacks documentation and you want an accurate baseline to build from
- When producing reference documentation for a public SDK where accuracy is critical and manual maintenance does not scale
Expected Output
Generated documentation derived from code with a CI check that validates the documentation stays in sync with the implementation.
Frequently Asked Questions
- What is the main limitation of documentation-from-code?
- Code documents what it does, not why. Generated documentation accurately reflects implementation but cannot capture design rationale, architectural trade-offs, or historical context. Use documentation-from-code for technical accuracy and write separate ADRs for decision rationale.
- How do I handle poorly documented code that I want to generate documentation from?
- Generate documentation from code structure even when comments are sparse. The documentation will be sparse but accurate. As a separate effort, add targeted comments to the most critical functions and update the documentation to include those insights.
- Can documentation-from-code replace human-written documentation?
- No—it replaces the tedious work of manually documenting what the code already says. Human writing is still needed for tutorials, guides, decision rationale, and conceptual overviews that explain how pieces fit together.
Related
Related
3 Indexed items
Receiving code review
Structures how you respond to code review feedback so the review process stays focused, respectful, and productive. This skill separates substantive feedback from nitpicks, tracks follow-ups without losing them, and produces a record that makes merges faster and post-mortems clearer.
Requesting code review
Frames a pull request so reviewers understand the risk profile, what has been tested, and where to focus their limited attention. This produces faster, more useful reviews because reviewers spend less time reconstructing context and more time evaluating the actual changes.
AI product requirement writing
Writes product requirements documents that AI agents can act on reliably, with explicit constraints, edge cases, and acceptance criteria that minimize the gap between what you mean and what the agent builds. This skill bridges the ambiguity of natural language product specs and the precision that AI agents require to produce consistent results.