| name | cli-forge-doc |
| metadata | {"author":"clement"} |
| description | Generate and audit comprehensive project documentation from a Git repository. Produces standard documentation (CONTRIBUTING.md, architecture, troubleshooting) in Diataxis structure with zero AI markers by default. Use this skill whenever someone asks to document a project, generate docs, create a README, write API docs, or improve existing documentation. Also trigger when someone mentions "doc", "documentation", "readme", "explain this codebase", "onboard developers", or "make this project understandable". |
| argument-hint | [git-repo-path] |
| context | fork |
| agent | general-purpose |
Optimization: This skill uses on-demand loading. Heavy content lives in references/ and is loaded only when needed.
Language rule: Skill instructions are written in English. When generating user-facing output, detect the project's primary language (from README, comments, docs, commit messages) and produce the documentation in that language. If the project is bilingual, ask the user which language to use before proceeding.
Diacritics rule: When the chosen output language uses diacritics (French, Spanish, Portuguese, etc.), render them correctly — including on capitals (É, À, Ç, Ô…). Never strip accents to ASCII: write "sécurité" not "securite", "Rôle" not "Role". ASCII-flattened French is a defect, not a style.
Writing style: Favor clarity — short sentences, one idea per sentence, plain words. A metaphor only when it clarifies. Keep one consistent register (impersonal/infinitive for operational docs). Separate narrative prose, meant to make the reader understand, from telegraphic content (tables, commands, checklists) which stays terse for action.
Reader calibration (the Singh rule): Before writing, name the expected reader and their situation (operator mid-incident, dev at setup, curious newcomer). Match their level — vulgarization means calibrating to the reader, not adding literary polish. For a general audience (Simon Singh's method): a concrete story motivates each concept, one strong analogy per hard idea, worked examples the reader can redo, hard details moved to an appendix. For practitioners (runbooks, how-tos, dev guides) the right level is the opposite of literary: command or fact first, the why in one short line after, imperative mood, no em-dash asides, no narrative voice, no scene-setting intro. If a sentence would read well in a magazine, it is miscalibrated for a runbook.
No fabricated output: Never invent command output, console captures, API responses, metrics, or logs. When real output is needed, emit a clearly-marked placeholder (🚧 "replace with a real capture"), never plausible-but-fake text presented as real.
Doc Forge — Dual Documentation Generator & Auditor
Generate production-grade documentation for any Git project, optimized for both AI agents and human readers.
Philosophy
Four principles stolen from the best, plus one operational rule:
- OpenBSD doctrine: "Developers making a change to the system are expected to update the man pages along with their change." Docs ship with code. Man pages are authoritative. If it's not documented, it doesn't exist.
- Diátaxis framework: Documentation has four modes — tutorials, how-to guides, reference, explanation. Never mix them.
- One doc, two readers: Good documentation serves both humans and AI agents. Standard files (architecture.md, CONTRIBUTING.md, TROUBLESHOOTING.md) are naturally consumable by both — no special AI format needed.
- Single source of truth (the spliceosome principle): each fact has exactly one canonical home. Other documents that need to mention the fact must link to it, transclude from it, or be generated from it — never duplicate it by hand. A eukaryotic gene is transcribed once and the spliceosome cuts the relevant exons for each context; documentation should work the same way. One source, many splicings (README, CONTRIBUTING, --help, slide deck), zero hand-maintained copies. Duplicated Truth is the #1 cause of doc rot — every parallel copy drifts.
- Gotchas — read
../gotchas.md before producing output to avoid known mistakes
Input
$ARGUMENTS is the path to the Git repository (or current directory if empty).
If no argument: look for a Git repo in the current working directory.
Step 0: Reconnaissance
Before writing a single line of doc, read the project. This is non-negotiable.
1. List the root directory
2. Read: README.md, CONTRIBUTING.md, Cargo.toml, package.json, pyproject.toml, go.mod, Makefile, Dockerfile, docker-compose.yml, .gitlab-ci.yml, .github/workflows/*, justfile
3. Identify: primary language(s), build system, CI/CD, test framework, deployment method
4. Sample 10-15 key source files (entry points, public API, core modules)
5. Read: docs/ directory if it exists
6. Check: git log --oneline -20 for recent activity focus
7. Check: git remote -v for repo URL
Build a mental model of:
- What the project does (purpose, problem it solves)
- How it's structured (architecture, key abstractions)
- Who uses it (library consumers, CLI users, operators, contributors)
- Where it runs (local, cloud, air-gapped, container)
Step 1: Completeness Scan (The Checklist)
Before generating, score what exists. Use the Documentation Completeness Index (DCI).
DCI Formula
DCI = Σ(wᵢ × sᵢ) / Σ(wᵢ) × 10
Where:
wᵢ = weight of item i (importance)
sᵢ = score of item i (0.0 to 1.0)
Checklist Items (with weights)
| # | Item | Weight | What to check |
|---|
| 1 | Project overview (README or equivalent) | 5 | Exists, has purpose statement, not just boilerplate |
| 2 | Getting started / quickstart | 5 | Can a new dev go from clone to running in <10 min? |
| 3 | Architecture overview | 4 | High-level structure documented somewhere |
| 4 | API reference (public surface) | 5 | Doc comments on public items, generated docs |
| 5 | Configuration reference | 3 | All config options documented with defaults |
| 6 | Error handling guide | 3 | Error types, what they mean, how to fix |
| 7 | Deployment / operations guide | 3 | How to deploy, monitor, troubleshoot |
| 8 | Contributing guide | 2 | How to contribute, code style, PR process |
| 9 | Changelog / release notes | 2 | History of changes |
| 10 | License | 1 | Exists and is clear |
| 11 | CI/CD documentation | 2 | Pipeline stages, environments, secrets needed |
| 12 | Security documentation | 3 | Threat model, auth flows, secrets management |
| 13 | Troubleshooting / gotchas guide | 3 | Known issues, workarounds, common mistakes documented |
| 14 | Examples / tutorials | 4 | Working, tested, progressive complexity |
| 15 | Inline doc coverage (public API) | 4 | % of public items with doc comments |
| 16 | Cross-references & linking | 2 | Types linked, related items connected |
Scoring guide: 0.0 = absent, 0.25 = stub/placeholder, 0.5 = exists but incomplete, 0.75 = good but gaps, 1.0 = excellent.
Output the DCI score table and overall score before proceeding.
Gap Analysis (ISO 13485 pattern)
Beyond raw scoring, run a compliance gap analysis based on project type:
| Project type | Required docs (gap analysis target) |
|---|
| Library | README, CHANGELOG, LICENSE, API_REFERENCE, CONTRIBUTING, SECURITY |
| CLI tool | README, --help, man page or equivalent, CHANGELOG, LICENSE, examples |
| Service | README, ARCHITECTURE, DEPLOYMENT, OPERATIONS, SECURITY, MONITORING, RUNBOOK |
| Infrastructure | README, ARCHITECTURE, NORMS_DEVIATIONS, OPERATIONS, TROUBLESHOOTING, CIS_AUDIT (if applicable) |
Output:
Gap Analysis — {project-type}
Compliance: 7/10 required docs present (70%)
Missing (prioritized by impact):
1. SECURITY.md (high — required for production)
2. RUNBOOK.md (medium — required for on-call)
3. CHANGELOG.md (low — semantic-release may auto-generate)
Step 2: Generate Project Documentation (Machine + Human Layer)
All project knowledge is distributed into standard documentation files. No AI-specific markers are generated by default.
OPSEC rationale: Files named AGENTS.md, CLAUDE.md, or llms.txt score DREAD 8.8/10 — they expose full architecture, credential patterns, and gotchas in files explicitly labeled for AI consumption. During a security audit (CIS, SOC 2, PCI-DSS, ISO 27001, defense contracts), these files signal AI involvement in development, raising accountability and supply chain concerns. Standard documentation files carry the same content with zero signal.
Self-contained operations pack mode
When the requested documentation is an operations/exploitation pack (signals:
exploitation, operations, runbook, N1/N2/N3, support tiers,
PDF, DOCX, export, livrable documentaire), generate a
self-contained dossier rather than a link-only index.
Rules for this mode:
- The directory itself must be usable offline by an operator and suitable as
input to an external PDF/DOCX export tool. Do not add repository export
scripts, Make targets, Pandoc wrappers, or generated PDF/DOCX artifacts unless
the user explicitly asks for export automation.
- External project docs may remain engineering sources of truth, but the
operations dossier must contain the minimum operational facts needed to act:
scope, roles, severity, triage, commands, escalation, rollback, closure,
request/change flow, known errors, and continual improvement.
- Prefer bounded operational duplication over link-only pages. If a fact is
needed for N1/N2/N3 to act, include the usable version directly in the pack.
Do not put external source/provenance paths in operator-facing pages by
default; they make the pack look dependent on files outside the dossier.
- Every page must start with
Role:, Quand utiliser cette page:, and Sortie attendue: (or project-language equivalents). Role: must describe the
page's operational function in the dossier, such as INDEX N1, PROCEDURE N2 ROLLBACK, KEDB N2, or RACI EXPLOITATION; do not use abstract
doc-maintenance roles like CANON, MAP, or NEW for operations packs.
Sortie attendue: must be an actionable operational output, not "open the
canonical source".
- Do not create link-only pages. Each file in the directory must contain enough
operational content to be usable on its own within its support level. Keep
maintenance provenance outside operator-facing pages unless explicitly asked.
- Avoid unexplained engineering shorthand in operator-facing pages. Replace test
tier codes like
T0/T2/T3/T4 with plain operational labels such as local quick test, integration test, target/VM test, or release gate unless
the pack defines the shorthand locally.
- Do not impose a repository-local incident storage convention (for example
.artifacts/incident-*, status.txt, logs.txt) when writing N1/N2/N3
procedures. Operators usually already have ITSM, monitoring, on-call, or
evidence tools. Specify the required information to capture and transmit,
not the storage tool or file layout, unless the user explicitly asks for a
project-local evidence convention.
- Do not create a monolithic
LIVRET.md by default. The directory is the
deliverable: README.md is the entry point, and each module/procedure file is
part of the self-contained pack. Create a linear printable synthesis only if
the user explicitly asks for one. Keep export mechanics outside the project
unless explicitly requested.
Content redistribution map
All project context is placed in standard files. An AI agent reads these files naturally — no special format needed.
| Content | Standard destination |
|---|
| Stack, Architecture | docs/explanation/architecture.md |
| Domain Concepts | docs/explanation/glossary.md or docs/reference/glossary.md |
| Key Patterns, Conventions | docs/explanation/architecture.md (section "Conventions") |
| Commands | README.md (section "Usage" or "Commands") |
| Gotchas, known issues | docs/TROUBLESHOOTING.md |
| Commit rules, git workflow | CONTRIBUTING.md |
| CI/CD validation | docs/reference/ci-cd.md |
Rules:
- Describe capabilities, not file paths (paths change, capabilities don't)
- Domain concepts are stable — document them. File structure is volatile — don't
- Include package manager explicitly if non-default
- Never dump style guides — let the linter do the linter's job
- Use progressive disclosure: point to
docs/ for details, don't inline everything
- Each fact has exactly one home (SSOT, the spliceosome rule): if two generated files would describe the same configuration option, port number, version, install command, or architectural component, one must link to the other instead of restating it. When in doubt, the canonical home is the file most likely to be read first by the relevant audience (README for users, CONTRIBUTING for contributors, ARCHITECTURE for designers). Never generate Duplicated Truth — every parallel copy is a future drift.
Cleanup of existing AI markers
If any AI-specific files exist in the project, absorb their content and delete them:
| File | Tool | Absorb into |
|---|
CLAUDE.md | Claude Code | CONTRIBUTING.md |
GEMINI.md | Gemini CLI | CONTRIBUTING.md |
AGENTS.md | Codex/multi-tool | docs/explanation/architecture.md |
llms.txt, llms-full.txt | Generic | docs/index.md |
.cursorrules, .cursor/rules/*.mdc | Cursor | CONTRIBUTING.md (coding conventions) |
.windsurfrules, .windsurf/rules/*.md | Windsurf | CONTRIBUTING.md |
.github/copilot-instructions.md | Copilot | CONTRIBUTING.md |
.aider.conf.yml | Aider | Discard (tool config, not project knowledge) |
After absorption:
- Delete all AI marker files listed above
- Add AI tool config dirs to
.gitignore (.cursor/, .windsurf/, .aider*, .claude/, .continue/, .junie/)
- Warn the user about AI trailers in git history — delegate to
cli-git-conventional --audit-markers for cleanup options
Opt-in: AI marker files (--ai-markers flag)
When explicitly requested with --ai-markers, additionally generate:
AGENTS.md — flat LLM context file (< 300 lines) with Stack, Architecture, Domain Concepts, Key Patterns, Commands, Gotchasllms.txt — documentation index following llmstxt.org standardllms-full.txt — (optional, small projects) single concatenated file with all doc content inline
These files duplicate content already in the standard docs. They exist only for convenience when OPSEC is not a concern.
Step 3: Generate Human Documentation (Diátaxis Layer)
This layer serves humans — from newcomers to experts. Follow the Diátaxis framework strictly: tutorials, how-to guides, reference, explanation. Never mix modes.
Read references/diataxis.md for the full directory structure, writing rules per quadrant, design doc template, and progressive complexity funnel.
Step 4: Audit (Score the Result)
After generation, run the doc-audit framework on the result. See reference.md for the full audit methodology.
Quick Audit Checklist
This checklist + the Doc Debt threshold form this skill's post-verification gate before publishing; the 3-phase definition-of-done structure (pre → during → post) is canonical in ../shared/done-gate.md.
For each generated file, verify:
- Accuracy: Does the doc match the actual code? (Read the implementation.)
- Completeness: Are all public items covered?
- Freshness: Does it reference current APIs, not stale ones?
- Examples: Do examples compile/run? Do they use
? not unwrap()?
- Cross-refs: Are types and functions linked, not just named?
- Progressive: Can a newcomer navigate from zero to competent?
Documentation Debt Score
Doc Debt = (Public Items − Documented Items) / Public Items × 100
Thresholds:
0-10% → Green (healthy)
10-25% → Yellow (needs attention)
25-50% → Orange (significant debt)
50%+ → Red (documentation emergency)
Step 5: Output
Files to Generate
At minimum, produce:
CONTRIBUTING.md — Commit rules, git workflow, PR processdocs/explanation/architecture.md — Full architecture, domain concepts, conventionsdocs/TROUBLESHOOTING.md — Gotchas, known issues, workaroundsdocs/index.md — Human landing pagedocs/tutorials/getting-started.md — First-contact tutorialdocs/reviews/DCI-REPORT.md — Documentation completeness index with scores and recommendations
If the project warrants it (public API, library, complex system), also produce:
- Full Diátaxis docs/ tree
- Updated inline doc comments (as a diff or suggestions)
docs/design/000-template.md — Design doc template for the team to reuse- Design docs for major existing architectural decisions (if none exist yet)
Presentation
Present the DCI score first, then the generated files. Summarize:
- Current state (DCI score)
- What was generated
- Top 3 highest-impact improvements still needed
- Recommended next steps (ordered by effort vs impact)
Dynamic Handoffs
| Condition detected | Recommend | Why |
|---|
| Project has shell scripts undocumented | /cli-audit-shell | Assess script quality for doc accuracy |
| Architecture section reveals coupling concerns | /cli-audit-tangle | Topology audit |
| README needs rewrite | /cli-forge-readme | Focused README generation |
Rule: Recommend, don't auto-execute.
Adaptation Rules
- Scale to project size: A 200-line CLI script needs a good README, not a docs site. A platform with 50K LOC needs the full Diátaxis treatment.
- Match the language: Follow the language's idiomatic doc conventions (see
reference.md).
- Respect existing docs: Don't overwrite good existing docs. Augment and cross-reference.
- Monorepo support: If the project has multiple packages/services, generate per-package docs + a root-level overview.
- Air-gapped aware: If the project targets air-gapped environments, emphasize offline-complete documentation. No external links that won't resolve.
- Confidence markers: If you're unsure about something (inferred from code but not confirmed), mark it with
<!-- NEEDS-REVIEW: [reason] --> rather than guessing.
