Skip to main content
AI/MLathola

update-readme

Refreshes README structure and content using repo context and exemplar research. Use when README needs a structural update after significant project changes.

Stars
294
Source
athola/claude-night-market
Updated
2026-05-30
Slug
athola--claude-night-market--update-readme
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/athola/claude-night-market/HEAD/plugins/sanctum/skills/update-readme/SKILL.md -o .claude/skills/update-readme.md

Drops the SKILL.md into .claude/skills/update-readme.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

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 TodoWrite Items

  1. update-readme:language-audit
  2. update-readme:exemplar-research
  3. update-readme:outline-aligned
  4. update-readme:edits-applied
  5. update-readme:slop-scanned - AI marker detection via scribe
  6. 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. 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, not the README.

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; 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:

  1. Ground every claim with specifics
  2. Remove formulaic openers/closers
  3. Use numbers, commands, filenames over adjectives
  4. Balance bullets with narrative prose
  5. 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

  • All TodoWrite items are complete.
  • The README is index-shaped: prose intro within the soft budget (roughly 150-400 lines plus any unit table), one install path, and a scannable unit/command table.
  • No README section duplicates a book/ or docs/ page; depth is linked, not inlined (rg -n '^#' README.md headings each map to a section that earns a place in an index).
  • The README references internal docs and external exemplars with citations.
  • Research notes and command references are captured so future reviewers can reproduce the process.

Troubleshooting

Common Issues

Documentation out of sync Run make docs-update to regenerate from code

Build failures Check that all required dependencies are installed

Links broken Verify relative paths in documentation files