readme-maker

@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.

<output_language>

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.

</output_language>

• Generate a project README.md grounded 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.

<routing_rule>

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 by the shape of its output:

• A general doc, runbook, instruction base, or harness rule pack is a documentation artifact, not a README.
• A product planning package (PRD, diagram, feature spec, user flow, wireframe) is a planning artifact.
• An SEO/AEO/GEO audit or marketing-page optimization is a search-optimization artifact.
• Pure fact-finding with no README artifact is a research task.
• A version bump or a release-note set is a release artifact.
• Committing a finished README is a version-control action, not README authoring.

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, which are documentation artifacts

</routing_rule>

<instruction_contract>

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.
Loop	None. One pass per request: discover the project, plan sections, draft, validate, report, then stop. Re-invoke only when the user asks for another README or a follow-up section update.
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.

</instruction_contract>

<activation_examples>

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/color workspace in this monorepo."
• "Update the install and usage sections of README to reflect the new entry point."
• "Make a project README.md." (Korean positive create request; should trigger.)
• "Read this repository carefully and rewrite the README." (Korean refactor request; should trigger.)

Negative examples:

• "Create a CHANGELOG from the commit log." The output is a release artifact, not a README.
• "Write API documentation for this library." The output is a documentation artifact, not a README.
• "Plan the next release of this project." The output is a planning artifact, not a README.
• "Add a new feature to this codebase." (Korean feature request; not a README task.)

Boundary examples:

• "Document this project." Use readme-maker only when the output is a README.md. A guide, runbook, or instruction base is a documentation artifact and stays out of scope.
• "Refactor this README and commit the change." Use readme-maker for the README itself; the commit that follows is a version-control action, not README authoring.
• "Refactor this README and commit it too." (Korean boundary; README authoring first via readme-maker, then the commit as a separate version-control action.)

</activation_examples>

<trigger_conditions>

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

</trigger_conditions>

<supported_targets>

• Root README.md of an app, library, CLI, plugin, framework, docs site, or service.
• Package-level README.md inside 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.

</supported_targets>

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.md into Korean by default or use references/readme-templates.ko.md when 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

<structure_blueprint>

Default Korean README outline (adapt by project type per references/readme-templates.md / .ko.md):

1. Title + one-line description
2. Optional badges (only when verifiable)
3. Features or highlights (3-7 bullets max)
4. Install
5. Quickstart / Usage
6. Configuration / Environment
7. Commands or API surface (CLI, library, plugin)
8. Examples
9. Development (build, test, dev server, scripts)
10. Project structure (only when non-trivial)
11. Contributing (only if the project documents a process)
12. License

</structure_blueprint>

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