Documentation is one of the first things developers hand off to an AI agent — and one of the first places quality breaks down without a skill. Ask for docs and you get something. Ask again and you get something different. A documentation skill fixes this by defining exactly what to generate, what format to use, and what level of detail to include.
The problem with ad-hoc documentation prompts
Without a skill, "document this function" is ambiguous. The agent decides: how long? which fields? what examples? The output varies by session, by phrasing, by whatever the model weighted most.
The result is documentation that doesn't match across files, lacks consistent fields, and requires cleanup before it's actually useful.
A documentation skill makes the instruction explicit once. The agent follows it every time.
Types of documentation skills
Function and method documentation
The most common use case. A function docs skill specifies exactly which JSDoc / docstring fields to populate:
| Field | When to include |
|---|---|
| Description | Always — one sentence on what the function does |
| Parameters | Always — name, type, description, whether optional |
| Returns | Always — type and description of return value |
| Throws/Raises | When the function can throw — which errors and when |
| Example | When the usage is non-obvious |
| See also | When related functions exist |
A skill can also specify what not to include — no restating the function name, no documenting obvious parameters like id: string.
API endpoint documentation
REST and GraphQL endpoints need a different template: HTTP method, path, request body shape, response shape, authentication requirements, error codes.
A good API docs skill:
- Extracts this information from the route handler
- Uses your team's documentation format (OpenAPI-compatible fields, your wiki format, etc.)
- Generates examples with realistic-looking placeholder data
- Notes which fields are required vs optional
Architecture and module documentation
Higher-level docs that explain what a module does, what it owns, what it depends on, and when to use it. These are harder to keep fresh — a skill that regenerates them from the codebase on demand is more reliable than docs written once and left to drift.
# module-doc-generator
## Purpose
Generate module-level documentation for TypeScript files, describing the
module's responsibilities, exports, and dependencies.
## Instructions
1. Read the file and identify its primary purpose
2. List all exported functions, classes, and constants with one-line descriptions
3. Identify imports and group them: internal (our code) vs external (dependencies)
4. Note any side effects (global state, event listeners, timers)
5. Write a one-paragraph module summary
## Output format
# [module name]
**Purpose**: one sentence
**Exports**:
- `functionName(params)` — what it does
- `ClassName` — what it represents
**Dependencies**:
- Internal: list
- External: list
**Notes**: side effects or unusual behaviour
Changelog generation
A changelog skill reads your git log since the last release and produces a structured changelog entry. Specify: which commit types to include (feat, fix, refactor), how to group them, what to omit (chore, style), and whether to include PR numbers.
README generation
A README skill generates or updates a project README from the codebase — installation steps derived from package.json, usage examples from test files, API summary from route handlers.
Finding documentation skills in the directory
npx mdskill search "documentation"
npx mdskill search "jsdoc generator"
npx mdskill search "api docs"
Or browse the writing category for documentation-focused skills.
npx mdskill add owner/repo/skill-name
Making docs part of every PR
Once a docs skill is installed, you can make documentation a natural part of your code review workflow:
"Document the new functions I added" "Generate docs for this module" "Update the API docs for the changes in this PR"
The agent follows the skill's procedure — consistent fields, consistent format — across every file it touches.
Commit the skill to your repo so every developer on the team generates docs the same way.
What's next?
- Browse writing and documentation skills in the directory
- Pair a docs skill with a code review skill for a complete PR workflow
- Build a custom docs skill matching your team's format