writing-project-readmelisted

# Writing a Project README ## Overview A great README answers four questions for **two audiences at once**: 1. _What is this?_ — non-engineers must understand in 30 seconds 2. _How do I use/install it?_ — engineers must get unblocked 3. _How does it fit together?_ — anyone evaluating must see architecture 4. _Where do I go next?_ — links to deeper docs, never duplicate them This skill is **for full rewrites**, not for small edits. Activate only when the user explicitly asks for a comprehensive README. ## Invocation This skill runs **only when the user explicitly invokes it** — e.g. `/writing-project-readme` or a clear request like "redo README.md based on the whole project". Do NOT auto-apply when: - Editing a single section, fixing a link, or tweaking badges → use `Edit` directly - Generating CHANGELOG, API reference, or ADRs → wrong artifact - The existing README already covers the four audience questions → propose a tweak, not a rewrite If you are reading this skill without an explicit invocation, stop and ask the user whether a full rewrite is intended. ## Core Principle > **Top third is for non-engineers. Bottom two-thirds is for engineers. Setup details live in a separate file (`DEVELOPMENT.md`, `CONTRIBUTING.md`, etc.) — the README links to them, never copies them.** If a non-engineer cannot read the first three sections and explain what the product does, the README has failed regardless of how complete the technical sections are. ## Workflow ```dot digrap