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

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.

README Generator — Production First

Generate professional README.md files where results come first, plumbing comes second.

Gotchas — read ../gotchas.md before producing output to avoid known mistakes.

Philosophy

A README is a landing page, not a technical manual.

• 90% of visitors want to know: what, why, how to start
• 10% want to contribute or understand internals
• Structure for the 90%, don't punish them with the 10%

Tone rule: Friendly on the surface, technical in depth.

• Tier 1–2: plain language, no jargon, a junior dev or a PM can understand
• Tier 3: full technical depth, assume the reader codes

Workflow

Step 1 — Detect project context

Build the shared reconnaissance brief first — read ../shared/recon.md (what / who / problem / headline / differentiator / golden-path). The same brief feeds prez and demo, so the README, slides, and live demo tell one story.

Then read the project root to auto-detect the type:

If nothing detected → ask user with QCM (project type, language, deployment status).

Step 2 — Gather content

1. Read existing files: README.md, CHANGELOG, LICENSE, CI configs, manifest
2. Only ask for what's missing
3. Find the hero moment: the ONE thing that makes someone go "I need this"

Step 3 — Write using the 3-Tier Pyramid

Read references/pyramid.md for the detailed tier structure, rules, and badge templates.

Then apply project-type-specific adaptations. Read references/project-types.md for per-type customization.

Formatting Standards

1. # = project name only. ## = sections. ### = subsections. Never deeper than ####
2. Code blocks: always specify language (bash, rust, yaml...)
3. Tables: for structured data only (env vars, flags, endpoints). Never for prose
4. Links: relative for in-repo, absolute for external
5. Target length: Tier 1+2 fit in ~3 screen heights. Tier 3 can expand
6. No empty sections: if nothing to say, omit entirely. No TODOs in shipped READMEs

Quality Scoring — README Completeness Index (RCI)

RCI = Σ(wᵢ × sᵢ) / Σ(wᵢ) × 10

Scoring: 0.0=absent, 0.25=stub, 0.5=exists but weak, 0.75=good, 1.0=excellent

Thresholds: 8+ excellent, 6-8 good, 4-6 needs work, <4 incomplete

Output

• Write to project root as README.md
• Show a brief summary: which tier sections were generated, what's missing/skipped
• Output the RCI table at the end of the review

Dynamic Handoffs

Rule: Recommend, don't auto-execute.

Integration with other cli-* skills