Skip to main content
skill CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local
Open on GitHub

What 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.ts with /doc-gen.
  • Write a README for src/auth that describes its exports.
  • Create an API reference for src/routes using /doc-gen --api.

How to install doc-gen

1Plugin marketplace

/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local

This installs the whole citadel plugin with all its skills

2Skills CLI (Vercel)

npx skills add SethGammon/Citadel --skill doc-gen -a claude-code

3Manually: put the files in place

~/.claude/skills/doc-gen/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/doc-gen/

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.

doc-gen ruvnet doc-gen generates project documentation, detects drift between docs and code, and schedules recurring updates. Helpful when code changes outpace reference files. CX Codex +1 744installs update-docs NeoLabHQ update-docs updates project documentation based on uncommitted git changes or the latest commit. Keeps README files, docs/, and JSDoc comments synchronized with your codebase. CX Codex +1 1,400installs code-documentation MoizIbnYousaf code-documentation — a skill that gives the agent fixed templates for READMEs, API reference, inline comments and architecture notes. CX Codex +1 571installs documentation-templates davila7 The documentation-templates skill provides outlines and templates for READMEs, API references, code comments, and project records. Use it when starting documentation or bringing existing pages into a clearer structure. CX Codex +1 305installs quill simota quill adds JSDoc/TSDoc to functions and interfaces, updates READMEs, replaces any with precise types. Use it when your code lacks documentation or type safety. CX Codex +1 107installs gsd-doc-writer davepoon gsd-doc-writer — a subagent that writes and updates project documentation. Generates README, guides, API references, and other files, adapting to project structure and fixing errors from verification checks. CX Codex ★ 3,785repo stars doc-forge rohitg00 doc-forge — a Claude Code plugin that generates code documentation, API docs, and maintains README files. The agent invokes it when you work on project documentation. ★ 2,858repo stars

From the same set55

The whole set →
verify verify — a skill to self-test the Citadel hook pipeline during a live session. Exercises real tool calls (Write, Edit, Bash, Read), verifies that hooks fire, telemetry accumulates, and no errors occur. CX Codex +1 ★ 937repo stars unharness unharness is a Claude Code skill that plans Citadel removal from a project and keeps a portable archive. It runs on requests to remove Citadel or clean up the harness. CX Codex +1 ★ 937repo stars grill grill turns a vague plan into a sharp technical spec through one-question-at-a-time interview, each with a default answer you edit. CX Codex +1 ★ 937repo stars autopilot autopilot processes queued tickets from .planning/intake/ through automated research, implementation, and verification. CX Codex +1 ★ 937repo stars policy-enforcer policy-enforcer is a Claude Code subagent that checks proposed actions against Citadel’s rules and returns an allow-or-block verdict. Archon and Fleet spawn it before actions with low reversibility. CX Codex ★ 937repo stars systematic-debugging systematic-debugging stops trial-and-error edits by enforcing a four-phase root cause protocol and freezing code changes until hypotheses are tested. CX Codex +1 ★ 937repo stars decision-map Turn an unresolved idea into a Git-tracked decision map, then pick up the investigation in later sessions. Useful before work is ready to build. CX Codex +1 ★ 937repo stars archon archon — a subagent that carries a big task through phases: splits a direction into steps, hands them to other agents and keeps campaign state between runs. CX Codex ★ 937repo stars

Project sponsors

Companies that keep this analytics open