Code-Accurate Docs: Docstrings, JSDoc, OpenAPI Specs
Docstrings, JSDoc/TSDoc, OpenAPI specs, and quickstart guides written from your real code, covering error paths and edge cases.
Before & after
Same prompt, same agent — the only difference is the skill.
API documentation is important, and there are a few formats like OpenAPI and JSDoc that work well. You could write it inline with your code or generate it separately. Tools exist to help validate and maintain docs, but setup varies. What format does your team prefer?
DOCUMENTATION OUTPUT SUITE:
FORMAT 1: OPENAPI SPECIFICATION
→ Auto-generated from code structure (request/response objects, auth, status codes)
→ Includes all endpoints, param types, example payloads
→ YAML or JSON, compatible with Swagger UI
FORMAT 2: JSDOC ANNOTATIONS
→ Inline docstrings auto-inserted above functions
→ Template: @param {type} name - description
→ @returns {type} description + @throws {error} cases
FORMAT 3: MARKDOWN PORTAL
→ Getting started guide (install, auth, first request)
→ Endpoint reference (organized by feature)
→ Error codes + troubleshooting (common gotchas)
→ Code snippets (node.js, Python, curl examples)
VALIDATION CHECKLIST:
☐ All endpoints documented
☐ Every param has a type and description
☐ Response examples included
☐ Error codes mapped to solutions
☐ No outdated endpoints
INTEGRATION:
• Post-commit hook: re-generate docs, flag mismatches
• Preview: Swagger UI deployed to docs.example.com
• Build gate: fails if 10% of endpoints lack examples
TIME SAVED: Auto-generation eliminates 60% of manual doc work. Keep humans only for "why" + examples.About this skill
Your docstrings describe what the function was supposed to do two refactors ago, your OpenAPI spec lists 200 and 400 while the API also returns 401, 409, and 422, and the README quickstart fails on step 3. This skill writes documentation by tracing the actual code: every parameter constraint, every exception that escapes, every status code the middleware and framework add. Where code and old docs disagree, it flags the mismatch instead of quietly picking one.
What it does
- Writes docstrings in your existing convention (Google, NumPy, Sphinx, JSDoc, TSDoc, Go doc comments, rustdoc) covering units, nullability, side effects, and the exceptions callers must handle
- Builds or repairs OpenAPI 3.0/3.1 specs from real route handlers and serializers, including status codes injected by auth middleware, validation layers, and rate limiters
- Annotates JavaScript with JSDoc precise enough for
// @ts-checkand editor inference, and switches to TSDoc conventions in TypeScript projects - Writes quickstarts with pinned prerequisites, copy-pasteable commands, and the expected output after each step
- Ends every deliverable with a gap report: doc-code mismatches, likely bugs spotted while documenting, and anything it could not verify from the code you shared
- Gives you the exact lint or validation command to run (Spectral, Redocly, ruff, tsc) rather than claiming the docs were validated
What you get
Drop-in documentation (docstrings, annotations, spec YAML, or guide markdown) plus a short coverage-and-gaps list telling you what to check before merging.
Best for
Backend and full-stack developers paying down documentation debt, teams publishing an API to partners or customers, and maintainers of libraries or open-source projects whose docs have drifted from the code.
SKILL.md preview
---
name: code-accurate-docs
description: Writes docstrings, JSDoc/TSDoc annotations, OpenAPI specs, and quickstart guides by tracing the actual code (raise paths, middleware, serializers, defaults) and reports any place where code and existing docs disagree. Use when the user says "add docstrings to this module", "generate an OpenAPI spec for these routes", "our Swagger docs are wrong", "add JSDoc so VS Code autocompletes this", "write a getting-started guide", "document this function", "my API docs keep drifting from the code", or "nobody can get our project running from the README".
---
# Code-Accurate Docs: Docstrings, JSDoc, OpenAPI Specs
… (sign up to view the full skill)More development skills
View all Development skills →CodeTour Walkthrough File Builder
Writes a valid CodeTour .tour file for your repo: persona-targeted steps anchored to verified file paths and line numbers.
Markdown to Single-File HTML (Docs, Reviews, Slides)
Turns markdown into one offline-safe HTML file laid out as a document, diff review, or slide deck, with a fidelity report.
Release Changelog from Commits and PRs
Turns a commit range or merged PRs into a release changelog with breaking changes, migration steps, and user-facing wording.
Markdown to HTML Slide Deck Converter
Turns a markdown talk split by --- into one offline HTML deck with clean slide breaks, hidden speaker notes, and a slide overflow check.