alpoxdev @rules/project-discovery.md @rules/section-design.md @rules/validation.md @references/readme-templates.md
README Maker
Read the project carefully, then write the README the project actually deserves.
Default all user-facing deliverables, saved artifacts, reports, plans, generated docs, summaries, handoff notes, commit/message drafts, and validation notes to Korean, even when this canonical skill file is written in English.
Preserve source code identifiers, CLI commands, file paths, schema keys, JSON/YAML field names, API names, package names, proper nouns, and quoted source excerpts in their required or original language.
Use a different language only when the user explicitly requests it, an existing target artifact must stay in another language for consistency, or a machine-readable contract requires exact English tokens. If a localized template or reference exists (for example *.ko.md or *.ko.json), prefer it for user-facing artifacts.
- Generate a project
README.mdgrounded in the real codebase, not boilerplate. - Refactor stale or generic READMEs so install, usage, structure, and examples match current code.
- Adapt section choice and depth to project shape (CLI, library, web app, monorepo, plugin, framework, docs site, service).
- Preserve evidence: every install command, script, badge, and example traces back to a file in the repo.
Use readme-maker when the primary deliverable is a README.md (root or sub-package) for a project, library, CLI, plugin, workspace, framework, docs site, or service.
Route neighboring work elsewhere:
- Use
docs-makerwhen the output is a general doc, runbook, instruction base, or harness rule pack. - Use
prd-makerwhen the output is a product planning package (PRD, diagram, feature spec, user flow, wireframe). - Use
seo-makerwhen the output is an SEO/AEO/GEO audit or marketing-page optimization. - Use
researchwhen the job is pure fact-finding with no README artifact. - Use
version-updatewhen the main job is bumping a version or producing release notes. - Use
git-commitorgit-makerwhen the main job is committing a README change after the README is finalized.
Do not use readme-maker when:
- the user wants only a
CHANGELOG.md,CONTRIBUTING.md,LICENSE, or other non-README file - the user wants source-code edits, refactors, or feature implementation and only mentions README in passing
- the user wants live external research with no README artifact
- the user wants AI-readable instruction docs or harness rule packs (use
docs-maker)
| Field | Contract |
|---|---|
| Intent | Produce or improve a README.md that reflects the real shape, install, usage, and constraints of the target project. |
| Scope | Own the target README.md (root or package) and a short summary; do not edit source code, configuration, license, or unrelated docs unless the user asks. |
| Authority | User instructions and project-local docs (AGENTS.md, CLAUDE.md, root README, package manifests) outrank generic README conventions and external templates. |
| Evidence | Ground every install command, script invocation, file path, badge, and feature claim in a real file under the project. Do not invent commands or APIs. |
| Tools | Use read/edit/write and shell search (find, grep, ls) only inside the project. Do not run install, build, deploy, or release commands as part of authoring. |
| Output | A single written or updated README.md, plus a short summary noting which files were inspected and which sections changed. |
| Verification | Run project-discovery, shape, language, and evidence checks from rules/validation.md before completion. |
| Stop condition | Finish when checks pass and any uncertain claims are flagged with <!-- TODO -->; escalate when project shape is ambiguous, license is unclear, or commands cannot be verified from the repo. |
Positive examples:
- "Read this project carefully and create a README.md."
- "Refactor the README so it matches the current CLI commands."
- "Generate a README for the
packages/colorworkspace in this monorepo." - "Update the install and usage sections of README to reflect the new entry point."
- "프로젝트 README.md 만들어줘." (Korean positive create request; should trigger.)
- "이 저장소를 꼼꼼히 읽고 README를 다시 써줘." (Korean refactor request; should trigger.)
Negative examples:
- "Create a CHANGELOG from the commit log." Use
git-commit/version-updatepaths instead. - "Write API documentation for this library." Use
docs-maker. - "Plan the next release of this project." Use
prd-makerorplan. - "이 코드베이스에 새 기능을 추가해줘." (Korean feature request; not a README task.)
Boundary examples:
- "Document this project."
Use
readme-makeronly when the output is aREADME.md. Usedocs-makerwhen the output is a guide, runbook, or instruction base. - "Refactor this README and commit the change."
Use
readme-makerfor the README itself; route the commit togit-commitorgit-makerafter the README is finalized. - "이 README 리팩터하고 커밋도 같이 해줘." (Korean boundary; README first via
readme-maker, then commit viagit-commit/git-maker.)
| Situation | Mode |
|---|---|
Project has no README.md |
create |
README.md exists but is stale, generic, or contradicts current code |
refactor |
| Specific sections need updating after a feature, rename, or move | update |
| A sub-package or workspace inside a monorepo needs its own README | create |
| README needs Korean-by-default language alignment, or must preserve an explicitly requested/existing documentation language | refactor |
- Root
README.mdof an app, library, CLI, plugin, framework, docs site, or service. - Package-level
README.mdinside a monorepo workspace. - README refactors that re-derive sections from current code.
- README updates that touch install, usage, configuration, scripts, examples, or project structure.
- Korean-by-default language alignment, while preserving another language only when the user requests it or an existing README must stay consistent.
| Phase | Task | Output |
|---|---|---|
| 0 | Confirm the deliverable is a README.md; pick create/refactor/update |
Mode decision |
| 1 | Scan project structure and detect shape (rules/project-discovery.md) |
Project profile |
| 2 | Read existing README, AGENTS.md, CLAUDE.md, license, manifests, and entry points |
Evidence base |
| 3 | Pick sections, order, depth, and Korean-by-default language handling (rules/section-design.md) |
Section plan |
| 4 | Draft or refactor README.md using grounded examples and Korean-default templates from references/readme-templates.md / .ko.md |
Updated README |
| 5 | Run validation checks (rules/validation.md) and write the completion summary |
Final README + summary |
Phase 4 authoring rules
- Read first, write second. Never invent install commands, scripts, environment variables, or APIs.
- Write README prose in Korean by default. Use another language only when the user requests it or an existing target README must preserve its current documentation language.
- Prefer one accurate example over three speculative ones.
- Keep the README scannable: title, description, install, and quickstart belong above the fold.
- Move long deep-dive content out of the README and link to it; the README should orient, not exhaust.
- Do not add badges that cannot be verified (CI status, coverage, npm version) unless the project already publishes them.
create mode
- Start from the project profile and pick the matching template; translate
references/readme-templates.mdinto Korean by default or usereferences/readme-templates.ko.mdwhen available. - Include only sections supported by real evidence in the repo.
- Mark unknowns explicitly with
<!-- TODO: confirm with maintainer -->instead of fabricating.
refactor mode
- Preserve correct existing content; rewrite only sections that drift from the code.
- Re-derive install, usage, scripts, and structure sections from current files.
- Keep links, badges, and prose that still hold; remove dead links and stale commands.
update mode
- Touch only the sections the user named or the diff implies.
- Append a dated entry to a change-history section only if the project README already tracks one.
| Category | Avoid |
|---|---|
| Fabrication | Install commands, scripts, environment variables, or APIs not present in the repo |
| Drift | Stale screenshots, broken links, deprecated commands left in place |
| Overload | Embedding full API references, long tutorials, or design docs inside the README |
| Tone | Marketing fluff, vague superlatives, hype the code does not support |
| Side effects | Editing source code, configs, or licenses while authoring the README |
| Extra files | Creating CHANGELOG.md, CONTRIBUTING.md, or other docs unless the user asks |
| Category | Required |
|---|---|
| Evidence | Every install/usage line maps to a manifest, script, source file, or existing doc in the repo |
| Shape match | Section selection matches the detected project type |
| Language match | README prose is Korean by default, or matches the user-requested/existing target language when preservation is required |
| Discoverability | Title, one-line description, install, and quickstart are above the fold |
| Verification | Validation checklist completed before claiming done |
Default Korean README outline (adapt by project type per references/readme-templates.md / .ko.md):
- Title + one-line description
- Optional badges (only when verifiable)
- Features or highlights (3-7 bullets max)
- Install
- Quickstart / Usage
- Configuration / Environment
- Commands or API surface (CLI, library, plugin)
- Examples
- Development (build, test, dev server, scripts)
- Project structure (only when non-trivial)
- Contributing (only if the project documents a process)
- License
| Check | Rule |
|---|---|
| Evidence | Each command and path in the README exists in the repo |
| Shape | The selected template matches the actual project type |
| Language | README is Korean by default, with non-Korean output only for explicit user request or existing target-language preservation |
| Above the fold | Title, description, install, and quickstart appear within the first screen |
| No fabrication | No invented APIs, scripts, env vars, or external badges |
| Lean body | Long content is linked, not inlined |
| Translation pair | If the skill itself or other markdown was edited, English/Korean files stay aligned |
Must-pass thresholds:
- Project shape detected and recorded in the completion summary
- At least one verified install command and one verified usage example
- Existing README sections that remain accurate are preserved (refactor/update mode)
- Unknowns are marked with
<!-- TODO -->, not fabricated - No dead links or removed scripts left in the new draft