doc-writing
Scannednpx machina-cli add skill huangjia2019/claude-code-engineering/doc-writing --openclawDoc Writing Skill
Generate structured API documentation from a route manifest.
Input
You will receive a route manifest (JSON array) from the previous pipeline stage. Each entry contains: method, path, file, line, middleware, type.
Process
Step 1: Read Source Code
For each route in the manifest, read the source file to understand:
- Request parameters (path, query, body)
- Response format
- Error handling
- Business logic summary
Step 2: Generate Documentation
Use the template at templates/endpoint-doc.md for each route group.
Group routes by their source file (e.g., all product routes together).
Step 3: Write Files
Write one markdown file per route group to the docs/ directory:
docs/products-api.mddocs/categories-api.md- etc.
Output
Return a manifest of generated documentation files:
{
"files_generated": ["docs/products-api.md", "docs/categories-api.md"],
"routes_documented": 8,
"routes_skipped": [],
"warnings": []
}
This manifest will be consumed by the next pipeline stage (quality-checking).
Source
git clone https://github.com/huangjia2019/claude-code-engineering/blob/main/04-Skills/projects/08-skill-pipeline/.claude/skills/doc-writing/SKILL.mdView on GitHub Overview
doc-writing generates structured Markdown API documentation from a route manifest. It reads route metadata, groups routes by their source file, and produces per-group docs using templates/endpoint-doc.md in the docs/ directory, ready for publication.
How This Skill Works
For each route in the manifest, it reads the source file to extract request parameters, response formats, error handling, and business logic. It then applies the endpoint docs template to each route group and writes one Markdown file per group under docs/, such as docs/products-api.md or docs/categories-api.md.
When to Use It
- You have a discovered routes manifest from automation and need readable docs fast.
- You want consistent API docs aligned to a single template for publishing.
- You need per-source-file route grouping to simplify navigation (e.g., product or category routes).
- You’re documenting a large set of endpoints with minimal manual writing.
- You want a downstream QA stage to consume a docs manifest of generated files.
Quick Start
- Step 1: Provide a route manifest (JSON array) from the previous pipeline stage.
- Step 2: Run doc-writing to generate docs/ files using templates/endpoint-doc.md.
- Step 3: Review docs/ and commit the new Markdown files (e.g., docs/products-api.md).
Best Practices
- Ensure the route manifest is up-to-date before running doc-writing.
- Validate each route entry has essential fields: method, path, file, line, type.
- Use the templates/endpoint-doc.md as the canonical docs template; customize carefully.
- Review generated docs against the source code to verify parameters and responses.
- Store generated docs under docs/ and commit them alongside API code.
Example Use Cases
- Auto-generated docs for products and categories in an e-commerce app.
- Documentation for user-management and authentication routes in a microservice.
- Inventory and pricing endpoints documented via route manifest.
- Payment gateway routes documented using the endpoint-doc template.
- Internal API reference published for a set of microservices.
