Skip to content
Documentation

README Template

FieldValue
TypeSkill Resource
Source~/.copilot/skills/technical-writing/references/templates/readme.md
DescriptionNot specified

Source Content

README Template

The front door of a repo. Gets a newcomer running fast and oriented. Composite form: part how-to (quick start), part reference (structure).

Skeleton

# {{Project name}}


{{One sentence: what it is and who it's for. A one-line scene is welcome:
"Jill cloned this repo on day one and was running it by lunch — this
README is that path."}}


## Quick start


{{Install and run — copy-pasteable, on the stated versions.}}


## What's inside


{{The handful of things a newcomer needs to navigate the repo.}}


{{Mermaid diagram of the high-level architecture if the repo has more
than three moving parts — follow the diagram rules in ../mermaid.md.}}
_{{What to notice in the diagram.}}_


## Common tasks


{{The three to five commands people run most; link the Taskfile if there is one.}}


## Where to learn more


{{Links into docs/ — guides, reference, ADRs.}}


## The useful ending


{{One or two sentences, after everything above: what a newcomer walks away
with, now that this is written down.}}

Rules for this template

  • Quick start must work on a clean machine — test it, don’t assume it.
  • Environment variables and config keys go one per line, each with its purpose.
  • The README links out; it does not absorb the docs. Anything over a screen belongs in docs/.
  • README.md is the one Markdown file that lives at the repo root by convention.
  • Cast: always Jack (the path with friction) and Jill (the path that works) — see ../personas.md.
  • Reminders: story, own line per person · useful ending.
  • Format: short paragraphs · lists and tables · diagram + “what to notice”.