README Update Workflow
When To Use
Use this skill whenever the README requires a structural refresh.
Run Skill(sanctum:git-workspace-review) first to capture repo context and diffs.
When NOT To Use
- Updating inline docs: use doc-updates
- Consolidating ephemeral reports: use doc-consolidation
Required Progress Items
update-readme:language-audit
update-readme:exemplar-research
update-readme:outline-aligned
update-readme:edits-applied
update-readme:slop-scanned - AI marker detection via scribe
update-readme:verification-reporting
Step 1 - Language Audit (update-readme:language-audit)
- Confirm
pwd, git status -sb, and the baseline branch for reference.
- Detect dominant languages using repository heuristics (manifest files, file counts).
- Note secondary languages that influence documentation (e.g., a TypeScript frontend and a Rust backend) so the README can surface both.
- Record the method and findings.
See modules/language-audit.md for detailed detection patterns and commands.
Step 2 - Exemplar Research (update-readme:exemplar-research)
- For each primary and secondary language, use web search to locate high-quality READMEs (star count, recency, maintainer activity).
- Capture 2-3 exemplar repositories per language and summarize why each is relevant (section order, visuals, quickstart clarity, governance messaging, math exposition, etc.).
- Store citations for every exemplar so the final summary references them explicitly.
See modules/exemplar-research.md for search query patterns and evaluation criteria.
Step 3 - Outline Alignment (update-readme:outline-aligned)
The README is an index, not a manual. Lead with what the
project is, how to install it, and a scannable table of its
units (plugins, commands, packages). Link out for everything
else.
A README is a newcomer document. Its reader has never seen
this project, so the test for every candidate section is whether
that reader needs it before they can install and run one thing.
Rationale, alternatives considered, and internals are expert
material: extract them to docs/<topic>.md or the
book/, linked from the README in one line naming who the page
is for. Never delete them to shorten the README. Tier table and
cut test: scribe:slop-detector module audience-targeting.md.
A README that declares a different tier (an internal tool whose
only readers already run it) says so in its lead.
When this repo's root README was simplified in 2026, it
dropped from 435 to 200 lines (65% fewer words) by deleting
inlined depth and linking to book/ instead. Aim for that
shape, not a section-by-section coverage sweep.
- Compare current README headings (
rg -n '^#' README.md)
against the exemplars from Step 2. Lean marketplace and
CLI-tool READMEs (asdf-vm/asdf-plugins, ohmyzsh/ohmyzsh,
ryoppippi/ccusage) are index-shaped: prose intro under ~500
words, a unit table doing the work, depth behind links.
- Keep only the sections that earn a place in an index: a
one-line value proposition, one install path, a compact
command or unit table, a short "what's inside" summary, a
single Documentation link section, and metadata
(requirements, contributing, license) last. For every other
candidate section ask: does this belong in the README, or
behind a link?
- Default to linking out. Send deep architecture, FAQ,
roadmap, changelog, alternate install methods, and per-unit
detail to their own pages. Per-unit docs live with the unit
(hub-and-spoke), never duplicated in the root.
- Order signals priority: title and tagline first, then
install, then the index table, then a short feature summary,
then Documentation links, with housekeeping (requirements,
contributing, license) last.
- Map internal documents (docs/, book/, specs/, commands/) to
the section that links them, so the README anchors depth
without restating it.
Soft budget: a marketplace or collection root README runs
roughly 150-400 lines of prose plus any index table. A section
that grows over time (roadmap, FAQ, changelog) belongs in a
linked page.
Step 4 - Apply Edits (update-readme:edits-applied)
- Implement the new structure directly in
README.md
(or the specified file).
- Follow
Skill(leyline:markdown-formatting) conventions:
wrap prose at 80 chars (prefer sentence/clause boundaries),
blank lines around headings, ATX headings only, blank line
before lists, reference-style links for long URLs.
- Maintain concise, evidence-based prose and avoid marketing fluff.
- Prefer deletion and linking over inlining. If a section
duplicates a docs page, cut it and link the page; if it
grows over time, move it out of the README entirely.
- Add comparison tables, feature lists, or diagrams only if
they originate from current repository assets (no speculative
content).
- When referencing algorithms or performance claims, point to
benchmarks or tests within the repository or documented math
reviews.
Step 4.5 - AI Slop Detection (update-readme:slop-scanned)
Run Skill(scribe:slop-detector) on the updated README to detect AI-generated content markers.
Scribe Integration
The scribe plugin provides AI slop detection:
Skill(scribe:slop-detector) --target README.md
This detects:
- Tier 1 words: delve, tapestry, comprehensive, leveraging, etc.
- Phrase patterns: "In today's fast-paced world", "cannot be overstated"
- Structural markers: Excessive em dashes, bullet overuse, sentence uniformity
- Marketing language: "enterprise-ready", "cutting-edge", "seamless"
Remediation
If slop score exceeds 2.0 (moderate), apply Skill(scribe:doc-generator) principles:
- Ground every claim with specifics
- Remove formulaic openers/closers
- Use numbers, commands, filenames over adjectives
- Balance bullets with narrative prose
- Show authorial perspective (trade-offs, reasoning)
For significant cleanup needs, use:
Agent(scribe:doc-editor) --target README.md
Step 5 - Verification & Reporting (update-readme:verification-reporting)
- Re-read the updated README for clarity, accessibility (section lengths, bullet balance), and accurate links.
- Run
git diff README.md (or the edited file) and capture snippets for the final report.
- Summarize detected languages, exemplar sources (with citations), key structural decisions, and follow-up TODOs (e.g., add badges, upload diagrams).
Exit Criteria
Troubleshooting
Common Issues
Documentation out of sync
Run make docs-sync-check to verify the capabilities docs still
match the plugin registrations
Build failures
Check that all required dependencies are installed
Links broken
Verify relative paths in documentation files
1---2name: update-readme-23description: Refreshes README structure favoring concision (an index, not a manual). Use when the README needs a structural update after significant project changes.4alwaysApply: false5category: artifact-generation6tags:7- readme8- documentation9- exemplars10- research11- structure12tools: []13complexity: high14estimated_tokens: 120015modules:16- modules/language-audit.md17- modules/exemplar-research.md18progressive_loading: true19dependencies:20- sanctum:git-workspace-review21- imbue:proof-of-work22- scribe:slop-detector23- scribe:doc-generator24metadata:25 source: https://skillmd.com/skills/athola/update-readme-226---2728# README Update Workflow2930## When To Use31Use this skill whenever the README requires a structural refresh.32Run `Skill(sanctum:git-workspace-review)` first to capture repo context and diffs.3334## When NOT To Use3536- Updating inline docs: use doc-updates37- Consolidating ephemeral reports: use doc-consolidation3839## Required Progress Items401. `update-readme:language-audit`412. `update-readme:exemplar-research`423. `update-readme:outline-aligned`434. `update-readme:edits-applied`445. `update-readme:slop-scanned` - AI marker detection via scribe456. `update-readme:verification-reporting`4647## Step 1 - Language Audit (`update-readme:language-audit`)48- Confirm `pwd`, `git status -sb`, and the baseline branch for reference.49- Detect dominant languages using repository heuristics (manifest files, file counts).50- Note secondary languages that influence documentation (e.g., a TypeScript frontend and a Rust backend) so the README can surface both.51- Record the method and findings.5253See `modules/language-audit.md` for detailed detection patterns and commands.5455## Step 2 - Exemplar Research (`update-readme:exemplar-research`)56- For each primary and secondary language, use web search to locate high-quality READMEs (star count, recency, maintainer activity).57- Capture 2-3 exemplar repositories per language and summarize why each is relevant (section order, visuals, quickstart clarity, governance messaging, math exposition, etc.).58- Store citations for every exemplar so the final summary references them explicitly.5960See `modules/exemplar-research.md` for search query patterns and evaluation criteria.6162## Step 3 - Outline Alignment (`update-readme:outline-aligned`)6364**The README is an index, not a manual.** Lead with what the65project is, how to install it, and a scannable table of its66units (plugins, commands, packages). Link out for everything67else.6869**A README is a `newcomer` document.** Its reader has never seen70this project, so the test for every candidate section is whether71that reader needs it before they can install and run one thing.72Rationale, alternatives considered, and internals are `expert`73material: extract them to `docs/<topic>.md` or the74`book/`, linked from the README in one line naming who the page75is for. Never delete them to shorten the README. Tier table and76cut test: `scribe:slop-detector` module `audience-targeting.md`.7778A README that declares a different tier (an internal tool whose79only readers already run it) says so in its lead.8081When this repo's root README was simplified in 2026, it82dropped from 435 to 200 lines (65% fewer words) by deleting83inlined depth and linking to `book/` instead. Aim for that84shape, not a section-by-section coverage sweep.8586- Compare current README headings (`rg -n '^#' README.md`)87 against the exemplars from Step 2. Lean marketplace and88 CLI-tool READMEs (asdf-vm/asdf-plugins, ohmyzsh/ohmyzsh,89 ryoppippi/ccusage) are index-shaped: prose intro under ~50090 words, a unit table doing the work, depth behind links.91- Keep only the sections that earn a place in an index: a92 one-line value proposition, one install path, a compact93 command or unit table, a short "what's inside" summary, a94 single Documentation link section, and metadata95 (requirements, contributing, license) last. For every other96 candidate section ask: **does this belong in the README, or97 behind a link?**98- Default to linking out. Send deep architecture, FAQ,99 roadmap, changelog, alternate install methods, and per-unit100 detail to their own pages. Per-unit docs live with the unit101 (hub-and-spoke), never duplicated in the root.102- Order signals priority: title and tagline first, then103 install, then the index table, then a short feature summary,104 then Documentation links, with housekeeping (requirements,105 contributing, license) last.106- Map internal documents (docs/, book/, specs/, commands/) to107 the section that links them, so the README anchors depth108 without restating it.109110**Soft budget**: a marketplace or collection root README runs111roughly 150-400 lines of prose plus any index table. A section112that grows over time (roadmap, FAQ, changelog) belongs in a113linked page.114115## Step 4 - Apply Edits (`update-readme:edits-applied`)116- Implement the new structure directly in `README.md`117 (or the specified file).118- Follow `Skill(leyline:markdown-formatting)` conventions:119 wrap prose at 80 chars (prefer sentence/clause boundaries),120 blank lines around headings, ATX headings only, blank line121 before lists, reference-style links for long URLs.122- Maintain concise, evidence-based prose and avoid marketing fluff.123- Prefer deletion and linking over inlining. If a section124 duplicates a docs page, cut it and link the page; if it125 grows over time, move it out of the README entirely.126- Add comparison tables, feature lists, or diagrams only if127 they originate from current repository assets (no speculative128 content).129- When referencing algorithms or performance claims, point to130 benchmarks or tests within the repository or documented math131 reviews.132133## Step 4.5 - AI Slop Detection (`update-readme:slop-scanned`)134135Run `Skill(scribe:slop-detector)` on the updated README to detect AI-generated content markers.136137### Scribe Integration138139The scribe plugin provides AI slop detection:140141```142Skill(scribe:slop-detector) --target README.md143```144145This detects:146- **Tier 1 words**: delve, tapestry, comprehensive, leveraging, etc.147- **Phrase patterns**: "In today's fast-paced world", "cannot be overstated"148- **Structural markers**: Excessive em dashes, bullet overuse, sentence uniformity149- **Marketing language**: "enterprise-ready", "cutting-edge", "seamless"150151### Remediation152153If slop score exceeds 2.0 (moderate), apply `Skill(scribe:doc-generator)` principles:1541551. Ground every claim with specifics1562. Remove formulaic openers/closers1573. Use numbers, commands, filenames over adjectives1584. Balance bullets with narrative prose1595. Show authorial perspective (trade-offs, reasoning)160161For significant cleanup needs, use:162163```164Agent(scribe:doc-editor) --target README.md165```166167## Step 5 - Verification & Reporting (`update-readme:verification-reporting`)168- Re-read the updated README for clarity, accessibility (section lengths, bullet balance), and accurate links.169- Run `git diff README.md` (or the edited file) and capture snippets for the final report.170- Summarize detected languages, exemplar sources (with citations), key structural decisions, and follow-up TODOs (e.g., add badges, upload diagrams).171172## Exit Criteria173174- [ ] All progress items are complete.175- [ ] The README is index-shaped: prose intro within the soft176 budget (roughly 150-400 lines plus any unit table), one177 install path, and a scannable unit/command table.178- [ ] No README section duplicates a `book/` or `docs/` page;179 depth is linked, not inlined (`rg -n '^#' README.md` headings180 each map to a section that earns a place in an index).181- [ ] The README serves a `newcomer`, or declares the tier it182 serves instead in its lead.183- [ ] Content cut for tier fit landed in a linked page, not the184 bin (`docs/` or `book/`).185- [ ] The README references internal docs and external186 exemplars with citations.187- [ ] Research notes and command references are captured so188 future reviewers can reproduce the process.189190## Troubleshooting191192### Common Issues193194**Documentation out of sync**195Run `make docs-sync-check` to verify the capabilities docs still196match the plugin registrations197198**Build failures**199Check that all required dependencies are installed200201**Links broken**202Verify relative paths in documentation files