Show less 19:41 Running the audit. Resolved source: inline text Findings Report No violations detected. The skill conforms to the template: valid frontmatter with a slug name and a trigger-rich description; canonical title; the four required level-2 sections (Purpose, When to Use, Process, Validation) in order with a properly nested SCOPE block; source-grounded Process with explicit not-found handling; inspectable Validation checkboxes with an anti-fabrication check; no placeholder syntax, TODO markers, self-validation in Process, or unjustified hardcoded numbers. Fixed SKILL.md md --- name: api-doc-generator description: Generates reference documentation for an existing API from its source code, route definitions, or schema. Activate when a developer says "document this API", "generate docs for these endpoints", "write OpenAPI descriptions for my routes", or hands over a controller file, router, or schema and wants human-readable reference docs produced before release. --- # API Documentation Generator ## Purpose Developers ship APIs whose endpoints are undocumented or whose docs have drifted from the actual implementation, forcing consumers to read source code or guess at request and response shapes. This skill reads the real API definition and produces accurate reference documentation grounded only in what the source provides, so the docs match the deployed behavior. It produces one deliverable: a structured reference document covering every endpoint with its method, path, parameters, request body, and response shapes. ## When to Use 1. You have a router file, controller, or schema and want reference docs generated from it. 2. Your existing documentation has drifted from the implementation and you want it regenerated from source. 3. You are preparing an API for external consumers and need each endpoint described consistently. 4. You want request and response shapes documented from the actual types rather than from memory. 5. You are standardizing docs across several services and want one consistent format applied. ### SCOPE — This skill does NOT handle: - Designing or proposing new API endpoints that do not yet exist in the source. - Generating client SDKs or runnable code from the documentation. - Writing prose guides, tutorials, or marketing copy about the API. - Inventing example values, latencies, or status codes not present in the source. - Testing the API or validating that documented behavior matches runtime behavior. ## Process 1. **Resolve Source** — Read the supplied file, route definitions, or schema; if nothing is readable, stop and report the missing source rather than generating from assumptions. 2. **Enumerate Endpoints** — List every route found, recording its HTTP method and path exactly as defined in the source. 3. **Extract Shapes** — For each endpoint, pull parameters, request body fields, and response fields from the types or schema, marking any field the source leaves untyped as unspecified. 4. **Document Each Endpoint** — Write a section per endpoint with method, path, parameters, request body, and response shapes, using only information present in the source. 5. **Flag Gaps** — Note any endpoint where the source provides no type or description, rather than filling the gap with invented detail. 6. **Emit Reference Document** — Output the complete documentation as one structured markdown document ordered by resource. ## Validation - [ ] Every endpoint present in the source appears in the output with its method and path. - [ ] No request or response field appears in the documentation that is absent from the source. - [ ] Endpoints with missing type information are marked as unspecified rather than given invented shapes. - [ ] No example contains a fabricated status code, latency figure, or value not derivable from the source. - [ ] The output is a single structured markdown document with no placeholder tokens or TODO markers. Change Summary No changes required — the source conformed on every checked dimension. The only adjustments are cosmetic markdown that the paste flattened: section headers re-marked as level-2 (##), the SCOPE block re-nested under ### , Process step labels re-bolded, and list bullets normalized. None alters content. Verdict: deploy-ready.