Generate and maintain project documentation. Creates a lean README as a landing page with detailed docs/ directory split by topic. Use when user says "create docs", "write documentation", "update docs", "generate readme", or "document project".
Generate, maintain, and improve project documentation following a landing-page README + detailed docs/ structure.
docs/. Each file is self-contained — one topic, one page. A user should be able to read a single doc file and get the full picture on that topic.docs/, README links to it — does not repeat it. Exception: installation command can appear in both (users expect it in README).[← Previous Page](prev.md) · [Back to README](../README.md) · [Next Page →](next.md). First page has no prev link; last page has no next link. Every page ends with a "See Also" section linking to 2-3 related pages.docs/workflow.mdworkflow.mdRead .ai-factory/DESCRIPTION.md if it exists to understand:
Explore the codebase:
package.json, composer.json, requirements.txt, go.mod, Cargo.toml, etc.src/ structure to understand architectureScan for scattered markdown files in project root:
Use Glob to find all *.md files in the project root (exclude node_modules/, .ai-factory/, agent dirs):
CHANGELOG.md, CONTRIBUTING.md, ARCHITECTURE.md, DEPLOYMENT.md,
SECURITY.md, API.md, SETUP.md, DEVELOPMENT.md, TESTING.md, etc.
Record each file, its size, and a brief summary of its content. This list is used in Step 1.1.
--web → Generate HTML version of documentation
Check what documentation already exists:
State A: No README.md → Full generation (README + docs/)
State B: README.md exists, no docs/ → Analyze README, propose split into docs/
State C: README.md + docs/ exist → Depends on flags (see below)
State C with --web flag — ask the user:
Documentation already exists (README.md + docs/).
What would you like to do?
- [ ] Generate HTML only — build site from current docs as-is
- [ ] Audit & improve first — check for issues, then generate HTML
- [ ] Audit only — check for issues without generating HTML
State C without --web flag → run Step 2 (State C) as usual.
If scattered .md files were found in the project root (from Step 0), propose consolidating them into the docs/ directory.
Common files that should move to docs/:
| Root file | Target in docs/ | Merge or move? |
|---|---|---|
CONTRIBUTING.md | docs/contributing.md | Move |
ARCHITECTURE.md | docs/architecture.md | Move |
DEPLOYMENT.md | docs/deployment.md | Move |
SETUP.md | docs/getting-started.md | Merge (append to existing) |
DEVELOPMENT.md | docs/getting-started.md or docs/contributing.md | Merge |
API.md | docs/api.md | Move |
TESTING.md | docs/testing.md | Move |
SECURITY.md | docs/security.md | Move |
Files that stay in root (standard convention):
README.md — always staysCHANGELOG.md — standard root-level file, keep as-isLICENSE / LICENSE.md — standard root-level file, keep as-isCODE_OF_CONDUCT.md — standard root-level file, keep as-isIf scattered files found, ask the user:
Found [N] markdown files in the project root:
CONTRIBUTING.md (45 lines) — contribution guidelines
ARCHITECTURE.md (120 lines) — system architecture overview
DEPLOYMENT.md (80 lines) — deployment instructions
SETUP.md (30 lines) — setup guide (overlaps with getting-started)
Suggested actions:
→ Move CONTRIBUTING.md → docs/contributing.md
→ Move ARCHITECTURE.md → docs/architecture.md
→ Move DEPLOYMENT.md → docs/deployment.md
→ Merge SETUP.md into docs/getting-started.md
Would you like to:
- [ ] Apply all suggestions
- [ ] Let me pick which ones
- [ ] Skip — keep files where they are
When moving/merging:
docs/ with prev/next navigation header (following Documentation table order) and "See Also" footerIMPORTANT: Never force-move files. Always show the plan and get user approval first.
When no README.md exists, generate the full documentation set.
Explore the codebase and identify documentation topics:
Always include:
- getting-started.md (installation, setup, quick start)
Include if relevant:
- architecture.md (if project has clear architecture: services, modules, layers)
- api.md (if project exposes API endpoints)
- configuration.md (if project has config files, env vars, feature flags)
- deployment.md (if Dockerfile, CI/CD, deploy scripts exist)
- contributing.md (if open-source or team project)
- security.md (if auth, permissions, or security patterns exist)
- testing.md (if test suite exists)
- cli.md (if project has CLI commands)
Ask the user:
I've analyzed your project and suggest these documentation pages:
1. getting-started.md — Installation, setup, quick start
2. architecture.md — Project structure and patterns
3. api.md — API endpoints reference
4. configuration.md — Environment variables and config
Would you like to:
- [ ] Generate all of these
- [ ] Let me pick which ones
- [ ] Add more topics
Structure (aim for ~80-120 lines):
# Project Name
> One-line tagline describing the project.
Brief 2-3 sentence description of what this project does and why it exists.
## Quick Start
\`\`\`bash
# Installation steps (1-3 commands)
\`\`\`
## Key Features
- **Feature 1** — brief description
- **Feature 2** — brief description
- **Feature 3** — brief description
## Example
\`\`\`
# Show a real usage example — this is where users decide "I want this"
\`\`\`
---
## Documentation
| Guide | Description |
|-------|-------------|
| [Getting Started](docs/getting-started.md) | Installation, setup, first steps |
| [Architecture](docs/architecture.md) | Project structure and patterns |
| [API Reference](docs/api.md) | Endpoints, request/response formats |
| [Configuration](docs/configuration.md) | Environment variables, config files |
## License
MIT (or whatever is in the project)
Key rules for README:
For each approved topic, create a doc file:
[← Previous Topic](previous-topic.md) · [Back to README](../README.md) · [Next Topic →](next-topic.md)
# Topic Title
Content organized by subtopic with headers, code examples, and tables.
Keep each section self-contained.
## See Also
- [Related Topic 1](related-topic.md) — brief description
- [Related Topic 2](other-topic.md) — brief description
Navigation link order follows the Documentation table in README.md (top to bottom). The first doc page omits the "← Previous" link; the last page omits the "Next →" link. Example for 4 pages:
getting-started.md: [Back to README](../README.md) · [Architecture →](architecture.md)
architecture.md: [← Getting Started](getting-started.md) · [Back to README](../README.md) · [API Reference →](api.md)
api.md: [← Architecture](architecture.md) · [Back to README](../README.md) · [Configuration →](configuration.md)
configuration.md: [← API Reference](api.md) · [Back to README](../README.md)
Content guidelines per topic:
getting-started.md:
architecture.md:
api.md:
configuration.md:
deployment.md:
When README.md exists but is long (150+ lines) and there's no docs/ directory.
Read README.md and identify:
Stays in README:
Moves to docs/:
getting-started.mdarchitecture.mdapi.mdconfiguration.mdcontributing.mdYour README.md is [N] lines. I suggest splitting it:
README.md (~100 lines) — keep as landing page:
✓ Title + tagline
✓ Key features
✓ Quick install
✓ Example
✓ Documentation links table
Move to docs/:
→ "Installation" section → docs/getting-started.md
→ "Configuration" section → docs/configuration.md
→ "API Reference" section → docs/api.md
→ "Architecture" section → docs/architecture.md
Proceed?
docs/ directoryWhen both README.md and docs/ exist.
Check for:
Docs may have been generated by an older version of this skill. Compare existing docs against current Core Principles and templates. Common gaps to detect:
| Missing standard | How to detect | Auto-fix |
|---|---|---|
| No prev/next navigation | Header has only [← Back to README] without · links to sibling pages | Add prev/next links following Documentation table order |
| No "See Also" section | File ends without ## See Also | Add section with 2-3 related page links |
| Old "Back to README" format | Link path or text doesn't match current pattern | Update to current format |
| Missing Documentation table in README | README has no table linking to docs/ pages | Add table |
| README too long | README is over 150 lines despite docs/ existing | Propose moving excess content to docs/ |
When gaps are found, include them in the audit report alongside content issues (Step 2.2). Treat them as regular improvements — show the plan and get user approval before applying.
Do NOT ask "was this generated by an older version?" — just silently detect what's missing and fix it. The user doesn't need to know about skill versioning; they just see their docs getting better.
Documentation audit results:
✅ README is lean (105 lines)
⚠️ docs/ pages missing prev/next navigation — will add
⚠️ docs/api.md is missing — project has 12 API endpoints
⚠️ docs/configuration.md references old env var DB_HOST (now DATABASE_URL)
❌ docs/getting-started.md links to docs/setup.md which doesn't exist
Proposed fixes:
1. Add prev/next navigation to all docs/ pages
2. Create docs/api.md with endpoint reference
3. Update DATABASE_URL in docs/configuration.md
4. Fix broken link in docs/getting-started.md
Apply fixes?
When --web flag is passed, generate a static HTML site from the markdown docs.
mkdir -p docs-html
For each markdown file (README.md + docs/*.md), generate an HTML version:
HTML template:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{page_title} — {project_name}</title>
<style>
:root {
--bg: #ffffff;
--text: #1a1a2e;
--text-secondary: #555;
--accent: #0066cc;
--border: #e2e8f0;
--code-bg: #f6f8fa;
--nav-bg: #f8fafc;
}
@media (prefers-color-scheme: dark) {
:root {
--bg: #0d1117;
--text: #e6edf3;
--text-secondary: #8b949e;
--accent: #58a6ff;
--border: #30363d;
--code-bg: #161b22;
--nav-bg: #161b22;
}
}
* { margin: 0; padding: 0; box-sizing: border-box; }
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
line-height: 1.6;
color: var(--text);
background: var(--bg);
max-width: 900px;
margin: 0 auto;
padding: 2rem 1.5rem;
}
nav {
background: var(--nav-bg);
border: 1px solid var(--border);
border-radius: 8px;
padding: 1rem 1.5rem;
margin-bottom: 2rem;
}
nav a {
color: var(--accent);
text-decoration: none;
margin-right: 1.5rem;
}
nav a:hover { text-decoration: underline; }
nav a.active { font-weight: 600; }
h1 { font-size: 2rem; margin: 1.5rem 0 1rem; border-bottom: 2px solid var(--border); padding-bottom: 0.5rem; }
h2 { font-size: 1.5rem; margin: 2rem 0 0.75rem; }
h3 { font-size: 1.2rem; margin: 1.5rem 0 0.5rem; }
p { margin: 0.75rem 0; }
a { color: var(--accent); }
code {
background: var(--code-bg);
padding: 0.15em 0.4em;
border-radius: 4px;
font-size: 0.9em;
}
pre {
background: var(--code-bg);
border: 1px solid var(--border);
border-radius: 8px;
padding: 1rem;
overflow-x: auto;
margin: 1rem 0;
}
pre code { background: none; padding: 0; }
table {
width: 100%;
border-collapse: collapse;
margin: 1rem 0;
}
th, td {
border: 1px solid var(--border);
padding: 0.5rem 0.75rem;
text-align: left;
}
th { background: var(--code-bg); font-weight: 600; }
ul, ol { padding-left: 1.5rem; margin: 0.75rem 0; }
li { margin: 0.25rem 0; }
blockquote {
border-left: 4px solid var(--accent);
padding-left: 1rem;
color: var(--text-secondary);
margin: 1rem 0;
}
hr { border: none; border-top: 1px solid var(--border); margin: 2rem 0; }
img { max-width: 100%; border-radius: 8px; }
</style>
</head>
<body>
<nav>
{nav_links}
</nav>
<main>
{content}
</main>
</body>
</html>
For each doc file:
.md references to .html (e.g., docs/getting-started.md → getting-started.html)docs-html/ directoryFile mapping:
README.md → docs-html/index.html
docs/getting-started.md → docs-html/getting-started.html
docs/api.md → docs-html/api.html
docs/configuration.md → docs-html/configuration.html
✅ HTML documentation generated in docs-html/
docs-html/
├── index.html (from README.md)
├── getting-started.html (from docs/getting-started.md)
├── api.html (from docs/api.md)
└── configuration.html (from docs/configuration.md)
Open in browser:
open docs-html/index.html
MANDATORY after any content change (generation, split, improvement, file consolidation). Do NOT skip this step.
Skip this step only when "Generate HTML only" was chosen — no content was modified, nothing to review.
Read every generated/modified file and evaluate it against both checklists below. Fix any issues found before presenting the result to the user.
Verify structure, links, and completeness:
.md files that should be in docs/Read every page as if you are a developer who has never seen this project before. For each page, verify:
First 10 seconds (above the fold):
"Show, don't tell":
<placeholder> that the user must replace?Scannability:
Jargon and assumptions:
Navigation and flow:
Motivation:
After running both checklists, present a summary:
📋 Documentation Review
Technical:
✅ All links verified (14 internal links, 0 broken)
✅ README is 108 lines
✅ All pages have navigation
⚠️ docs/api.md has a placeholder example — needs real endpoint
Readability:
✅ README explains purpose in first 10 seconds
✅ All code examples are copy-pasteable
⚠️ docs/architecture.md has a 12-line paragraph — should be split
⚠️ "CQRS" used without explanation in docs/architecture.md
Fixes applied:
→ Split long paragraph in docs/architecture.md into 3 shorter ones
→ Added "(Command Query Responsibility Segregation)" after first mention of CQRS
→ Replaced placeholder in docs/api.md with real endpoint example
All checks passed ✅
Only if files were moved/merged from root into docs/ during Step 1.1.
After the review confirms all content is correctly placed in docs/, offer to delete the original root-level files:
The following root files have been incorporated into docs/:
CONTRIBUTING.md → now in docs/contributing.md
ARCHITECTURE.md → now in docs/architecture.md
DEPLOYMENT.md → now in docs/deployment.md
SETUP.md → merged into docs/getting-started.md
These originals are no longer needed. Delete them?
- [ ] Yes, delete all originals
- [ ] Let me pick which ones to delete
- [ ] No, keep them (I'll clean up later)
When deleting:
git status to show what was deleted — user can restore with git checkout if neededDo NOT auto-delete. Always ask. The user may want to keep originals temporarily for reference or diff comparison.
After any documentation changes, update the Documentation section in AGENTS.md (if the file exists).
Read AGENTS.md and find the ## Documentation section. Update it to reflect the current state of all documentation files:
## Documentation
| Document | Path | Description |
|----------|------|-------------|
| README | README.md | Project landing page |
| Getting Started | docs/getting-started.md | Installation, setup, first steps |
| Architecture | docs/architecture.md | Project structure and patterns |
| API Reference | docs/api.md | Endpoints, request/response formats |
| Configuration | docs/configuration.md | Environment variables, config files |
Rules:
AGENTS.md doesn't exist, skip this step silentlyContext is heavy after codebase scanning and documentation generation. All docs are saved — suggest freeing space:
AskUserQuestion: Free up context before continuing?
Options:
1. /clear — Full reset (recommended)
2. /compact — Compress history
3. Continue as is
docs-html/ to .gitignore