README create/update
Replaces the former doc-readme-create / doc-readme-create-sub / doc-readme-update trio: $mode picks the verb, $target picks the directory (project root when empty). If $mode is empty, infer it from a three-way state check, not a create/update binary:
- (a) No README at the target →
create.
- (b) Placeholder/auto-generated README → treated as
create, free to fully regenerate against the template. Detected by: a <!-- doc-readme: generated ... --> marker (see Mode: create below — this skill leaves one on everything it writes from now on), OR a recognisable scaffold-tool stub (a framework's default "Welcome to Create React App" / npm init boilerplate / near-empty single-paragraph file with no real project detail).
- (c) Hand-authored README, no marker, doesn't match a placeholder shape →
update, the cautious path.
Say which state you detected and why (marker found, boilerplate pattern matched, or genuinely hand-authored) before proceeding.
Mode: create
- Confirm the target directory exists; stop and report if not.
- Analyse it: purpose, contents, structure, key modules, build system, existing docs. For a sub-directory, read the surrounding context too (parent README, siblings, project docs) to place it in the codebase.
- Fill the matching skeleton:
~/.claude/library/templates/readme-root.md for the project root, readme-sub.md for a sub-directory. Each {{ slot }} describes its content; drop sections that do not apply, never invent content to fill one.
- Include actual paths and commands, not placeholders. Match the style of existing project READMEs. Keep it proportional: a README is an overview, not full docs.
- Badge row, only for what's real. Detect what's actually present — a real
.github/workflows/*.yml → CI badge; a real published version (package manifest, svu current) → version badge; a real LICENSE/LICENSE.md → license badge — and emit a shields.io row from those only. Never a badge for something that isn't in the repo; a badge for CI that doesn't run is a lie the honesty rule in artefact-conventions.md exists to prevent, and that value applies here too even though this is Markdown, not HTML.
- Collapsibility for secondary sections. Past roughly 4-5 major sections, wrap the less-critical ones (Contributing, full config reference, detailed dev setup) in GFM's native
<details><summary> — no custom styling needed, GitHub renders the disclosure triangle itself. Keep What-it-is, Quickstart/Install, and core usage always visible.
- Provenance footer. A short, visible closing line:
Generated by doc-readme against \{commit-sha}` on {date}.` Terse, at the very bottom, doesn't compete with the real content.
- Marker comment, placed as the very first line of the file:
<!-- doc-readme: generated {date}. Delete this line once you hand-edit this file. --> — this is what lets a future run detect state (b) instead of treating a since-regenerated README as hand-authored.
- Show the draft and stop for approval before writing. Git is the backup; never leave
.bak files in the tree.
Mode: update
Reached only for state (c) — a genuinely hand-authored README with no marker and no placeholder shape. Stay conservative here; this is the one path that must never treat someone's real prose as raw material to restructure.
Resolve the README ($target/README.md, default ./README.md). If it does not exist, say so and offer create mode instead.
Read it for structure and style, then gather what changed in one command:
"$HOME"/.claude/library/scripts/git-doc-history.sh $target/README.md $target
It prints the commits, file changes and diff stat since the README was last touched; analyse that dump rather than running exploratory git calls.
Identify what needs updating: outdated descriptions, undocumented additions, removed content to clean up, structural changes.
Generate targeted updates preserving the existing structure and style; show a diff; apply on approval.
If the changes are minor, say so; don't invent updates for the sake of it. Prefer surgical edits over rewrites; don't remove content unless genuinely obsolete.
1---2name: docs-readme3description: Create or update a README for the project root or any directory4---56# README create/update78Replaces the former doc-readme-create / doc-readme-create-sub / doc-readme-update trio: `$mode` picks the verb, `$target` picks the directory (project root when empty). If `$mode` is empty, infer it from a **three-way state check**, not a create/update binary:910- **(a) No README at the target** → `create`.11- **(b) Placeholder/auto-generated README** → treated as `create`, free to fully regenerate against the template. Detected by: a `<!-- doc-readme: generated ... -->` marker (see Mode: create below — this skill leaves one on everything it writes from now on), OR a recognisable scaffold-tool stub (a framework's default "Welcome to Create React App" / `npm init` boilerplate / near-empty single-paragraph file with no real project detail).12- **(c) Hand-authored README, no marker, doesn't match a placeholder shape** → `update`, the cautious path.1314Say which state you detected and why (marker found, boilerplate pattern matched, or genuinely hand-authored) before proceeding.1516## Mode: create17181. Confirm the target directory exists; stop and report if not.192. Analyse it: purpose, contents, structure, key modules, build system, existing docs. For a sub-directory, read the surrounding context too (parent README, siblings, project docs) to place it in the codebase.203. Fill the matching skeleton: `~/.claude/library/templates/readme-root.md` for the project root, `readme-sub.md` for a sub-directory. Each {{ slot }} describes its content; drop sections that do not apply, never invent content to fill one.214. Include actual paths and commands, not placeholders. Match the style of existing project READMEs. Keep it proportional: a README is an overview, not full docs.225. **Badge row, only for what's real.** Detect what's actually present — a real `.github/workflows/*.yml` → CI badge; a real published version (package manifest, `svu current`) → version badge; a real `LICENSE`/`LICENSE.md` → license badge — and emit a shields.io row from those only. Never a badge for something that isn't in the repo; a badge for CI that doesn't run is a lie the honesty rule in `artefact-conventions.md` exists to prevent, and that value applies here too even though this is Markdown, not HTML.236. **Collapsibility for secondary sections.** Past roughly 4-5 major sections, wrap the less-critical ones (Contributing, full config reference, detailed dev setup) in GFM's native `<details><summary>` — no custom styling needed, GitHub renders the disclosure triangle itself. Keep What-it-is, Quickstart/Install, and core usage always visible.247. **Provenance footer.** A short, visible closing line: `Generated by doc-readme against \`{commit-sha}\` on {date}.` Terse, at the very bottom, doesn't compete with the real content.258. **Marker comment**, placed as the very first line of the file: `<!-- doc-readme: generated {date}. Delete this line once you hand-edit this file. -->` — this is what lets a future run detect state (b) instead of treating a since-regenerated README as hand-authored.269. Show the draft and **stop for approval** before writing. Git is the backup; never leave `.bak` files in the tree.2728## Mode: update2930Reached only for state (c) — a genuinely hand-authored README with no marker and no placeholder shape. Stay conservative here; this is the one path that must never treat someone's real prose as raw material to restructure.31321. Resolve the README (`$target/README.md`, default `./README.md`). If it does not exist, say so and offer create mode instead.332. Read it for structure and style, then gather what changed in one command:3435 ```bash36 "$HOME"/.claude/library/scripts/git-doc-history.sh $target/README.md $target37 ```3839 It prints the commits, file changes and diff stat since the README was last touched; analyse that dump rather than running exploratory git calls.403. Identify what needs updating: outdated descriptions, undocumented additions, removed content to clean up, structural changes.414. Generate targeted updates preserving the existing structure and style; show a diff; apply on approval.425. If the changes are minor, say so; don't invent updates for the sake of it. Prefer surgical edits over rewrites; don't remove content unless genuinely obsolete.
JasonWarrenUK