doc-gen
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.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 931
- Forks
- 84
01 前言 Front Matter
- 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.
- auto-trigger
- false
- last-updated
- 1773964800000
- user-invocable
- true
- trigger_keywords
- [ "document", "docs", "docstring", "jsdoc", "readme", "api docs" ]
02 资源文件 2
- 参考文档__benchmarks__/generate-readme.md783 B
- 参考文档__benchmarks__/no-source-files.md802 B
03 SKILL.md 正文
/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
- Read AGENTS.md (then CLAUDE.md if present) for doc conventions
- Search for existing doc comments in the target area — note density, tone, tags used, and line length
- 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:
- Read the full body, not just the signature
- 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
@examplewhen usage is non-obvious
- 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
- Read all files in the directory (one level deep)
- Identify: problem space, key exports, internal files, external dependencies, and what imports this module
- README schema:
# {Module Name}| one-paragraph description |## Key Exportstable (name, description) |## Architecture(only if non-obvious internal structure) |## Usage(real import paths) |## Dependencies(non-obvious only) - 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
- Apply detected style consistently
- Function-level: insert doc comments above each function
- Module-level: write or update README.md in the target directory
- API reference: write to
docs/api/or adjacent to route files - 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 namefiller; 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
---
04 同仓库更多 Skills
workspace
Multi-repo campaign coordinator. Same lifecycle as fleet -- scope claims, discovery relay, wave-based execution -- but the unit of work is a repo, not a file. Coordinates campaigns across repositories with shared context.
wiki
Markdown-first knowledge base where the LLM acts as librarian. Ingests raw sources, compiles and interlinks topic files, self-maintains an index. No vector DB or embeddings required -- uses LLM-native navigation over structured markdown up to ~400K words.
watch
File sentinel that monitors the working directory for changes and marker comments, then auto-triggers appropriate skills. Poll-based via git diff against the last scan commit. Writes intake items for batch processing and routes marker actions through /do. Use for automatic reactions to file changes; do NOT use for one-off inspection or tasks needing human judgment per file.
verify
Self-test the Citadel hook pipeline from within a live session. Exercises real tool calls (Write, Edit, Bash, Read) and checks that hooks fired, telemetry accumulated, and no errors occurred. Reports HOOK HEALTH: PASS or HOOK HEALTH: FAIL with a per-hook breakdown.
unharness
Safely leave Citadel using the active adoption receipt. Produces a no-write, reviewable plan, preserves a portable archive, removes only exact owned material, and reports modified or externally registered surfaces as retained or unknown. Legacy installs must be imported before exact leave is claimed.
triage
GitHub issue and PR investigator. Pulls open issues/PRs, classifies them, searches the codebase for root cause or reviews contributed code, proposes fixes with file:line references, and optionally implements fixes. Use for investigating GitHub issues and reviewing PRs; do NOT use for general code review unrelated to GitHub issues.