Documentation Generator
Overview
Generate or update the four-doc project documentation set: README.md, README.ko.md, ARCHITECTURE.md, and USAGE.md.
Core principle: README.md is the front door. Keep it short, link to deeper docs, preserve human prose, and write only after the user has seen the diff.
REQUIRED BACKGROUND: Use writing-skills before editing this skill itself. New skill behavior must be tested with baseline failures first.
Document Contract
| File |
Role |
README.md |
English front door: pitch, highlights, primary install path, one quick start, links to deeper docs, license |
README.ko.md |
Faithful Korean mirror of README.md; preserve code, commands, flags, file names, and proper nouns verbatim |
ARCHITECTURE.md |
Components, responsibilities, data flow, directory map, design decisions |
USAGE.md |
Detailed install, command/API reference, configuration, examples, troubleshooting |
Omit sections with no evidence. Do not invent support matrices, flags, environment variables, or architecture claims.
Workflow
- Resolve the target root from arguments or cwd.
- Detect which of the four docs exist and which are missing.
- Confirm the target set with the user.
- Run hybrid analysis:
- Main agent reads manifests, top-level tree, existing docs, LICENSE, CI, and remote URL.
- For larger projects, dispatch parallel Explore subagents for component map, entrypoints and flags, configuration, and examples.
- For small projects, do the same probes inline.
- Build one project model: name, pitch, install, quick start, components, data flow, directory map, command/API reference, configuration, examples, troubleshooting, license.
- Render from templates in
templates/.
- Merge existing files in place.
- Show per-file diffs and wait for confirmation.
- Write only confirmed docs.
Natural Korean Prose
Write newly authored README.ko.md text as plain, concrete Korean prose. Use
direct sentences; avoid translation-like rhythm, vague AI filler, and internal
method vocabulary. Preserve facts, numbers, dates, proper nouns, code
identifiers, commands, quotes, links, and the faithful relationship with
README.md. Never rewrite preserved custom prose merely to change its style.
This selector is self-contained. If the runtime already exposes
human-friendly-writing, it is an optional final pass over only the newly
authored Korean draft before showing the diff. Do not install, fetch, or
require it. If it is absent or unreadable, continue silently with the rules
above and complete the documents. After an optional pass, run the normal
validation and faithful-mirror check again. The pass may change wording only,
never evidence, fixed template structure, or preserved prose.
Update-in-Place Rules
- Parse existing docs by
# and ## headings.
- Replace derivable sections: install, quick start, command reference, configuration, directory structure, version, badges.
- Preserve unknown custom prose verbatim.
- Preserve any section containing
<!-- doc-skill:keep -->, even if it is normally derivable.
- Insert missing canonical sections in template order.
- Never delete a target document.
- Never modify files outside
README.md, README.ko.md, ARCHITECTURE.md, and USAGE.md.
Safety
- Show diffs before writing.
- Get explicit confirmation before writing.
- Never embed secret values found in
.env, credentials, keys, tokens, or local config.
- Mention uncertain findings as uncertain instead of filling gaps with guesses.
- Do not run the target project unless the user asks; static analysis is enough for v1.
Baseline Failures
These are the baseline failures this skill exists to prevent:
| Failure observed without the skill |
Required behavior with this skill |
| README becomes a dumping ground for install, usage, architecture, and troubleshooting |
Keep README as the front door and move depth to USAGE.md / ARCHITECTURE.md |
| Existing hand-written sections are overwritten |
Merge by heading and preserve unknown custom prose |
| Korean README is skipped or drifts from English |
Render README.ko.md as a faithful mirror whenever README.md changes |
| Agent writes files immediately |
Show per-file diff and wait for confirmation |
| Agent writes extra docs or edits unrelated files |
Restrict writes to the four target docs |
Common Mistakes
- Duplicating the same usage reference in README and
USAGE.md.
- Translating commands or flags in
README.ko.md.
- Treating an absent config file as proof there is no configuration surface.
- Claiming every dependency is part of the public architecture.
- Skipping the diff because the generated docs look obvious.
1---2name: gen-docs3description: Use when a software project needs README, README.ko, ARCHITECTURE, or USAGE documentation created, refreshed, reorganized, translated, or kept in sync without clobbering existing prose, including explicit "/gen-docs" or "$gen-docs"4---56# Documentation Generator78## Overview910Generate or update the four-doc project documentation set: `README.md`, `README.ko.md`, `ARCHITECTURE.md`, and `USAGE.md`.1112**Core principle:** `README.md` is the front door. Keep it short, link to deeper docs, preserve human prose, and write only after the user has seen the diff.1314**REQUIRED BACKGROUND: Use writing-skills** before editing this skill itself. New skill behavior must be tested with baseline failures first.1516## Document Contract1718| File | Role |19|---|---|20| `README.md` | English front door: pitch, highlights, primary install path, one quick start, links to deeper docs, license |21| `README.ko.md` | Faithful Korean mirror of `README.md`; preserve code, commands, flags, file names, and proper nouns verbatim |22| `ARCHITECTURE.md` | Components, responsibilities, data flow, directory map, design decisions |23| `USAGE.md` | Detailed install, command/API reference, configuration, examples, troubleshooting |2425Omit sections with no evidence. Do not invent support matrices, flags, environment variables, or architecture claims.2627## Workflow28291. Resolve the target root from arguments or cwd.302. Detect which of the four docs exist and which are missing.313. Confirm the target set with the user.324. Run hybrid analysis:33 - Main agent reads manifests, top-level tree, existing docs, LICENSE, CI, and remote URL.34 - For larger projects, dispatch parallel Explore subagents for component map, entrypoints and flags, configuration, and examples.35 - For small projects, do the same probes inline.365. Build one project model: name, pitch, install, quick start, components, data flow, directory map, command/API reference, configuration, examples, troubleshooting, license.376. Render from templates in `templates/`.387. Merge existing files in place.398. Show per-file diffs and wait for confirmation.409. Write only confirmed docs.4142## Natural Korean Prose4344Write newly authored `README.ko.md` text as plain, concrete Korean prose. Use45direct sentences; avoid translation-like rhythm, vague AI filler, and internal46method vocabulary. Preserve facts, numbers, dates, proper nouns, code47identifiers, commands, quotes, links, and the faithful relationship with48`README.md`. Never rewrite preserved custom prose merely to change its style.4950This selector is self-contained. If the runtime already exposes51`human-friendly-writing`, it is an optional final pass over only the newly52authored Korean draft before showing the diff. Do not install, fetch, or53require it. If it is absent or unreadable, continue silently with the rules54above and complete the documents. After an optional pass, run the normal55validation and faithful-mirror check again. The pass may change wording only,56never evidence, fixed template structure, or preserved prose.5758## Update-in-Place Rules5960- Parse existing docs by `#` and `##` headings.61- Replace derivable sections: install, quick start, command reference, configuration, directory structure, version, badges.62- Preserve unknown custom prose verbatim.63- Preserve any section containing `<!-- doc-skill:keep -->`, even if it is normally derivable.64- Insert missing canonical sections in template order.65- Never delete a target document.66- Never modify files outside `README.md`, `README.ko.md`, `ARCHITECTURE.md`, and `USAGE.md`.6768## Safety6970- Show diffs before writing.71- Get explicit confirmation before writing.72- Never embed secret values found in `.env`, credentials, keys, tokens, or local config.73- Mention uncertain findings as uncertain instead of filling gaps with guesses.74- Do not run the target project unless the user asks; static analysis is enough for v1.7576## Baseline Failures7778These are the baseline failures this skill exists to prevent:7980| Failure observed without the skill | Required behavior with this skill |81|---|---|82| README becomes a dumping ground for install, usage, architecture, and troubleshooting | Keep README as the front door and move depth to `USAGE.md` / `ARCHITECTURE.md` |83| Existing hand-written sections are overwritten | Merge by heading and preserve unknown custom prose |84| Korean README is skipped or drifts from English | Render `README.ko.md` as a faithful mirror whenever `README.md` changes |85| Agent writes files immediately | Show per-file diff and wait for confirmation |86| Agent writes extra docs or edits unrelated files | Restrict writes to the four target docs |8788## Common Mistakes8990- Duplicating the same usage reference in README and `USAGE.md`.91- Translating commands or flags in `README.ko.md`.92- Treating an absent config file as proof there is no configuration surface.93- Claiming every dependency is part of the public architecture.94- Skipping the diff because the generated docs look obvious.
chann