readme

name: "readme"
description: "Write or revise a concise repository README covering purpose, setup, and use."
createdAt: "2026-09-11T18:46:00.191381+00:00"
repoUrl: "https://skillz.supply/skills/did:plc:xbtmt2zjwlrfegqvch7fboei/skills.readme/SKILL.md"
# readme

a readme says what the project is, why it is shaped the way it is, how to
install and run it, and where the detail lives. it does not enumerate what
the code does: that drifts with every commit and duplicates the doc comments
on the types. read the host repository's CLAUDE.md/AGENTS.md first; they win.

Use the repository's existing style or a reference supplied by the user. Do not
assume a personal checkout collection is available.

## shape

Use the sections that help a reader get started; scale the structure to the project:

1. `# name` — lowercase, linked to the site if it has one.
2. **one paragraph**: what it is, in one to three sentences, linking what it
   builds on and crediting relevant upstream work. a fork says so in this paragraph.
3. `**live:** [host](url)` when something is deployed. a `> as featured in`
   or `> name credit` blockquote goes here when there is one.
4. `## install` — actual prerequisites and verified installation commands.
5. `## use` or `## what's here` — the smallest example that shows the shape.
   a library with many surfaces uses one `<details>` block per surface with
   a bold summary, a code sample, and one or two sentences of what it covers.
6. `## design` — bullets of `**intent** — why`, one per structural choice.
   this is where the why lives. no defaults, no field-by-field behavior.
7. `## develop` — the commands that build, test, and run, as a fenced block
   with a trailing comment per line.
8. `## docs` — link to the `docs/` directory, with one sentence describing
   its purpose. do not hand-maintain a table or inventory of individual docs:
   the directory listing is the source of truth and avoids drift. move longer
   design, research, and operational detail out of the root into `docs/`.
9. `## used by`, `## stack`, `## benchmarks`, `## api`, `## configuration`
   as the project warrants. benchmarks and stacks cite their source.
10. `## license` — link the actual license; do not assume MIT.
11. Footer links to a devlog or changelog, if those resources exist.

## voice

lowercase, except where uppercase is idiomatic: Proper Nouns, `camelCase`,
`PascalCase`, acronyms. bullets lead with a bold phrase and an em-dash.
sentences state a fact about the project or its reason; none narrate the
writing. numbers appear only as claims with a source (a benchmark link, a
live instance).

## what stays out

- per-option behavior and defaults. those are doc comments on the type; a
  reader who wants them opens the source or docs/.
- changelog content. link the changelog.
- anything that must change when the next commit lands. if a sentence would
  go stale with a field rename, it belongs in docs/ or nowhere.
- narration of what the author found or fixed. that is the devlog's job.

## test before posting

read it as a stranger with the terminal open. every link resolves, every
command runs, the install snippet compiles. if the readme is longer than
two screens, something belongs in docs/.
Readme
