doc-gen · sethgammon — Claude Code skill for generating documentation
doc-gen generates function comments, directory READMEs, and API references while following the project’s existing conventions. Use it when docs should explain code behavior rather than repeat signatures.
MIT ★ 937 updated 2026-10-29
/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-localWhat doc-gen does
The skill has three modes: function-level comments in JSDoc or docstring form, a README for a directory, and an API reference for HTTP routes or library exports. It infers a mode from the target path; --mode lets you choose one explicitly, while --dry-run previews the documentation plan without writing files.
Before drafting, it checks AGENTS.md and, when present, CLAUDE.md, then examines nearby documentation for style. Trivial getters and obvious wrappers are skipped. Each comment must add meaning beyond its signature or it gets removed. The skill runs a typecheck after writing, since malformed JSDoc can cause TypeScript errors.
For a directory, it creates or updates README.md. API references go in docs/api/ or beside route files. The skill reports the files it will modify and describes how to undo changes with git checkout.
What it helps with
- add JSDoc or docstrings to non-trivial functions
- write a module README describing exports and structure
- document HTTP routes, parameters, and responses
- check generated comments against code behavior and project style
Example prompts for the agent
- Add useful documentation to the functions in
src/utils.tswith/doc-gen. - Write a README for
src/auththat describes its exports. - Create an API reference for
src/routesusing/doc-gen --api.
How to install doc-gen
1Plugin marketplace
/plugin marketplace add SethGammon/Citadel/plugin install citadel@citadel-localThis installs the whole citadel plugin with all its skills
2Skills CLI (Vercel)
npx skills add SethGammon/Citadel --skill doc-gen -a claude-code3Manually: put the files in place
~/.claude/skills/doc-gen/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/doc-gen/
1Skills CLI (Vercel)
npx skills add SethGammon/Citadel --skill doc-gen -a codex2Manually: put the files in place
.agents/skills/doc-gen/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add SethGammon/Citadel --skill doc-gen -a cursor2Manually: put the files in place
.cursor/skills/doc-gen/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install SethGammon/Citadel skills/doc-gen2Manually: put the files in place
.github/skills/doc-gen/SKILL.md1Skills CLI (Vercel)
npx skills add SethGammon/Citadel --skill doc-gen -a gemini-cli2Platform CLI
gemini skills install https://github.com/SethGammon/Citadel --path skills/doc-genManually: put the files in place
.devin/skills/doc-gen/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about doc-gen
How do I install doc-gen in Claude Code?
First add the marketplace with /plugin marketplace add SethGammon/Citadel, then install the skill with /plugin install citadel@citadel-local.
What does doc-gen do?
It writes function comments, directory READMEs, and API references. It follows nearby documentation conventions and skips comments that merely repeat a signature.
Can I preview the documentation without changing files?
Yes. Run /doc-gen --dry-run src/utils.ts to see what it would document without writing changes.
Source text
SKILL.md · MIT
---
name: doc-gen
license: MIT
description: >-
Documentation generator with three modes: function-level (JSDoc/docstrings),
module-level (directory READMEs), and API reference (endpoints/exports).
Reads existing project doc style and matches it. Never generates docs that
just restate what the signature already says.
user-invocable: true
auto-trigger: false
trigger_keywords:
- document
- docs
- docstring
- jsdoc
- readme
- api docs
last-updated: 2026-03-20
---
# /doc-gen — Documentation Generator
## When to Use
- Add JSDoc/docstrings to functions in a file or set of files
- Write a README for a module or directory
- Document an HTTP API or exported library surface
Mode auto-detected from target:
- **File path** → function-level mode
- **Directory path** → module-level mode
- **Route file or API directory** → API reference mode
- **Explicit override**: `/doc-gen --mode function|module|api [target]`
## Commands
| Command | Behavior |
|---|---|
| `/doc-gen [file]` | Function-level docs for a file |
| `/doc-gen [directory]` | Module-level README for a directory |
| `/doc-gen --api [target]` | API reference for endpoints or exports |
| `/doc-gen --mode [mode] [target]` | Force a specific mode |
| `/doc-gen --dry-run [target]` | Show what would be documented without writing |
## Protocol
### Phase 1: DETECT STYLE
1. Read AGENTS.md (then CLAUDE.md if present) for doc conventions
2. Search for existing doc comments in the target area — note density, tone, tags used, and line length
3. Default when no existing docs: JSDoc (`@param`, `@returns`, `@throws`, `@example`) for TS/JS; Google-style for Python; idiomatic format for others
Apply detected style consistently across all generated docs.
### Phase 2: ANALYZE TARGET
#### Function-Level Mode
For each function:
1. Read the full body, not just the signature
2. Classify:
- **Trivial**: simple getters/setters, one-line wrappers with obvious names — SKIP
- **Non-trivial**: document purpose, parameter semantics (not types — TS has those), return guarantees, throws/errors, side effects, non-obvious edge cases, and `@example` when usage is non-obvious
3. Write using detected style
**Core rule:** every doc must add information beyond what the signature already says. If you cannot, skip it.
#### Module-Level Mode
1. Read all files in the directory (one level deep)
2. Identify: problem space, key exports, internal files, external dependencies, and what imports this module
3. README schema: `# {Module Name}` | one-paragraph description | `## Key Exports` table (name, description) | `## Architecture` (only if non-obvious internal structure) | `## Usage` (real import paths) | `## Dependencies` (non-obvious only)
4. If a README already exists, update rather than replace — preserve sections not covered by your analysis
#### API Reference Mode
For HTTP endpoints: method + path, description, path/query/body params (with types), response shape and status codes, errors, auth level, and a curl/fetch example for non-trivial endpoints.
For exported libraries: name and kind (function/class/constant/type), description, parameters/properties with semantics, return type with guarantees, import and usage example.
Structure as a single reference document with a table of contents.
### Phase 3: WRITE
1. Apply detected style consistently
2. Function-level: insert doc comments above each function
3. Module-level: write or update README.md in the target directory
4. API reference: write to `docs/api/` or adjacent to route files
5. Run typecheck after writing (malformed JSDoc can cause TS errors)
### Phase 4: VERIFY
Re-read every doc comment. For each: "Does this add information beyond the signature?" If not, delete it. Check accuracy: parameter names, return types, side effects, and that examples would actually compile/run.
## Contextual Gates
**Disclosure:** "Generating documentation for [target]. Source files will be modified."
**Reversibility:** amber — adds JSDoc/docstrings to source files; undo with `git checkout` on modified files.
**Trust gates:**
- Any: additive doc generation on undocumented functions.
- Familiar (5+ sessions): rewriting existing docstrings that may discard prior content.
## Quality Gates
- Every doc comment adds information beyond the signature; if not, delete it
- Docs match actual code behavior — wrong docs are worse than no docs
- Style matches the project's existing convention throughout
- No `@param name - The name` filler; omit parameters when their name is self-explanatory
- Typecheck passes after insertion
- At least some functions skipped as trivial — if every function was documented, you over-documented
## Exit Protocol
```
=== Doc-Gen Report ===
Mode: {function-level | module-level | api-reference}
Target: {path}
Style: {detected style}
Documented: {N functions ({M} skipped as trivial) | README.md ({N} exports) | {N} endpoints}
Skipped: {item}: {reason}
```
```
---HANDOFF---
- Generated {mode} docs for {target}
- Matched existing {style} convention
- {what was skipped and why}
- Reversibility: amber — undo with `git checkout` on modified source files
---
```
© SethGammon · MIT · SethGammon/Citadel
Similar skills
All skills for Writing and docs →doc-gen by other authors comes first.