update-readme — Skillopedia

README Update Workflow When To Use Use this skill whenever the README requires a structural refresh. Run 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. 2. 3. 4. 5. - AI marker detection via scribe 6. Step 1 - Language Audit ( ) - Confirm , , 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…

| wc -l\n# or for preview\nrg --files -g '*.rs' | head -10\n\n# Python\ngit ls-files | rg '\\.py

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

| wc -l\nrg --files -g '*.py' | head -10\n\n# Go\ngit ls-files | rg '\\.go

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

| wc -l\nrg --files -g '*.go' | head -10\n\n# TypeScript/JavaScript\ngit ls-files | rg '\\.(ts|tsx|js|jsx)

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

| wc -l\nrg --files -g '*.ts' -g '*.tsx' | head -10\n\n# Java\ngit ls-files | rg '\\.java

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

| wc -l\nrg --files -g '*.java' | head -10\n```\n\n## Language Priority Heuristics\n\nDetermine primary language using these priority rules:\n\n1. **Manifest presence**: If a language-specific manifest exists, it's a strong signal\n2. **File count dominance**: Language with >60% of source files is primary\n3. **Directory structure**: Check for language-specific directories (src/, lib/, pkg/)\n4. **Build configuration**: Presence of Makefile, CMakeLists.txt, or build scripts\n\n## Secondary Language Handling\n\nDocument secondary languages when they:\n\n- Represent >20% of codebase\n- Serve distinct architectural roles (e.g., Rust backend + TypeScript frontend)\n- Have their own build/test infrastructure\n- Require separate installation or runtime considerations\n\n### Example Multi-Language Documentation Strategy\n\n```markdown\n## Installation\n\n### Backend (Rust)\n[Rust-specific instructions]\n\n### Frontend (TypeScript)\n[Node/npm-specific instructions]\n```\n\n## Recording Findings\n\nCapture the audit results in a structured format:\n\n```\nLanguage Audit Results:\n- Primary: [Language] ([count] files, [manifest])\n- Secondary: [Language] ([count] files, [manifest])\n- Method: [manifest detection | file count | directory structure]\n- Documentation implications: [single-language | multi-language sections needed]\n```\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":2375,"content_sha256":"b5d54b11a8d1be67a6e7d191e8b76dc33610544fcdd5fb8f72620b2736cb6458"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"README Update Workflow","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"When To Use","type":"text"}]},{"type":"paragraph","content":[{"text":"Use this skill whenever the README requires a structural refresh. Run ","type":"text"},{"text":"Skill(sanctum:git-workspace-review)","type":"text","marks":[{"type":"code_inline"}]},{"text":" first to capture repo context and diffs.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"When NOT To Use","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Updating inline docs: use doc-updates","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Consolidating ephemeral reports: use doc-consolidation","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Required TodoWrite Items","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"update-readme:language-audit","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"update-readme:exemplar-research","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"update-readme:outline-aligned","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"update-readme:edits-applied","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"update-readme:slop-scanned","type":"text","marks":[{"type":"code_inline"}]},{"text":" - AI marker detection via scribe","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"update-readme:verification-reporting","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Step 1 - Language Audit (","type":"text"},{"text":"update-readme:language-audit","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Confirm ","type":"text"},{"text":"pwd","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"git status -sb","type":"text","marks":[{"type":"code_inline"}]},{"text":", and the baseline branch for reference.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Detect dominant languages using repository heuristics (manifest files, file counts).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Note secondary languages that influence documentation (e.g., a TypeScript frontend and a Rust backend) so the README can surface both.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Record the method and findings.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"modules/language-audit.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for detailed detection patterns and commands.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Step 2 - Exemplar Research (","type":"text"},{"text":"update-readme:exemplar-research","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For each primary and secondary language, use web search to locate high-quality READMEs (star count, recency, maintainer activity).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Capture 2-3 exemplar repositories per language and summarize why each is relevant (section order, visuals, quickstart clarity, governance messaging, math exposition, etc.).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Store citations for every exemplar so the final summary references them explicitly.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"modules/exemplar-research.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for search query patterns and evaluation criteria.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Step 3 - Outline Alignment (","type":"text"},{"text":"update-readme:outline-aligned","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Compare current README headings (","type":"text"},{"text":"rg -n '^#' README.md","type":"text","marks":[{"type":"code_inline"}]},{"text":") against patterns observed in exemplars.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Draft a target outline covering: value proposition, installation, quickstart, deeper usage/configuration, architecture/feature highlights, performance or math guarantees, documentation links, contribution/governance, roadmap/status, and licensing/security notes.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"validate internal documents (docs/, specs/, wiki, commands/) are mapped to the relevant sections so the README anchors them with context-sensitive links.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Step 4 - Apply Edits (","type":"text"},{"text":"update-readme:edits-applied","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Implement the new structure directly in ","type":"text"},{"text":"README.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" (or the specified file).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Follow ","type":"text"},{"text":"Skill(leyline:markdown-formatting)","type":"text","marks":[{"type":"code_inline"}]},{"text":" 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.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Maintain concise, evidence-based prose; avoid marketing fluff.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Add comparison tables, feature lists, or diagrams only if they originate from current repository assets (no speculative content).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"When referencing algorithms or performance claims, point to benchmarks or tests within the repository or documented math reviews.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Step 4.5 - AI Slop Detection (","type":"text"},{"text":"update-readme:slop-scanned","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]},{"type":"paragraph","content":[{"text":"Run ","type":"text"},{"text":"Skill(scribe:slop-detector)","type":"text","marks":[{"type":"code_inline"}]},{"text":" on the updated README to detect AI-generated content markers.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Scribe Integration","type":"text"}]},{"type":"paragraph","content":[{"text":"The scribe plugin provides AI slop detection:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"Skill(scribe:slop-detector) --target README.md","type":"text"}]},{"type":"paragraph","content":[{"text":"This detects:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Tier 1 words","type":"text","marks":[{"type":"strong"}]},{"text":": delve, tapestry, comprehensive, leveraging, etc.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Phrase patterns","type":"text","marks":[{"type":"strong"}]},{"text":": \"In today's fast-paced world\", \"cannot be overstated\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Structural markers","type":"text","marks":[{"type":"strong"}]},{"text":": Excessive em dashes, bullet overuse, sentence uniformity","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Marketing language","type":"text","marks":[{"type":"strong"}]},{"text":": \"enterprise-ready\", \"cutting-edge\", \"seamless\"","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Remediation","type":"text"}]},{"type":"paragraph","content":[{"text":"If slop score exceeds 2.0 (moderate), apply ","type":"text"},{"text":"Skill(scribe:doc-generator)","type":"text","marks":[{"type":"code_inline"}]},{"text":" principles:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Ground every claim with specifics","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Remove formulaic openers/closers","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use numbers, commands, filenames over adjectives","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Balance bullets with narrative prose","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Show authorial perspective (trade-offs, reasoning)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"For significant cleanup needs, use:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"Agent(scribe:doc-editor) --target README.md","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Step 5 - Verification & Reporting (","type":"text"},{"text":"update-readme:verification-reporting","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Re-read the updated README for clarity, accessibility (section lengths, bullet balance), and accurate links.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Run ","type":"text"},{"text":"git diff README.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" (or the edited file) and capture snippets for the final report.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Summarize detected languages, exemplar sources (with citations), key structural decisions, and follow-up TODOs (e.g., add badges, upload diagrams).","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Exit Criteria","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"All ","type":"text"},{"text":"TodoWrite","type":"text","marks":[{"type":"code_inline"}]},{"text":" items are complete.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The README reflects a modern, language-aware structure, referencing both internal docs and external inspiration with citations.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Research notes and command references are captured so future reviewers can reproduce the process.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Troubleshooting","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Common Issues","type":"text"}]},{"type":"paragraph","content":[{"text":"Documentation out of sync","type":"text","marks":[{"type":"strong"}]},{"text":" Run ","type":"text"},{"text":"make docs-update","type":"text","marks":[{"type":"code_inline"}]},{"text":" to regenerate from code","type":"text"}]},{"type":"paragraph","content":[{"text":"Build failures","type":"text","marks":[{"type":"strong"}]},{"text":" Check that all required dependencies are installed","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Links broken","type":"text","marks":[{"type":"strong"}]},{"text":" Verify relative paths in documentation files","type":"text"}]}]},"metadata":{"date":"2026-06-05","name":"update-readme","tags":["readme","documentation","exemplars","research","structure"],"tools":[],"author":"@skillopedia","source":{"stars":298,"repo_name":"claude-night-market","origin_url":"https://github.com/athola/claude-night-market/blob/HEAD/plugins/sanctum/skills/update-readme/SKILL.md","repo_owner":"athola","body_sha256":"ddf31bc2b50e5da3cf23f7f619d9389684652819690e05317785531b11ed826a","cluster_key":"31a6e7c976270f174ba999fd8db24a29984f0be1ced4ad766df89ca0fe710adb","clean_bundle":{"format":"clean-skill-bundle-v1","source":"athola/claude-night-market/plugins/sanctum/skills/update-readme/SKILL.md","attachments":[{"id":"1404e067-6284-518a-8fd1-b5bfd2d9b799","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/1404e067-6284-518a-8fd1-b5bfd2d9b799/attachment.md","path":"modules/exemplar-research.md","size":4022,"sha256":"94e3b0b13dc527283a86b1e7f8f37a139e98ae283611d308ee3befac1b3de47c","contentType":"text/markdown; charset=utf-8"},{"id":"48274c29-fba2-5cf0-b15b-7560bcd6733b","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/48274c29-fba2-5cf0-b15b-7560bcd6733b/attachment.md","path":"modules/language-audit.md","size":2375,"sha256":"b5d54b11a8d1be67a6e7d191e8b76dc33610544fcdd5fb8f72620b2736cb6458","contentType":"text/markdown; charset=utf-8"}],"bundle_sha256":"61647ea5bf6c63ff4d2174fce1ed5f8306d242f2e65394ad5475324f9565f2f3","attachment_count":2,"text_attachments":2,"attachment_storage":"skillopedia-attachments-v1","binary_attachments":0,"excluded_attachments":[]},"cluster_size":1,"skill_md_path":"plugins/sanctum/skills/update-readme/SKILL.md","import_metadata":{"date":"2026-06-05","author":"@skillopedia","version":"v1","category":"documents-office","category_label":"Documents"},"exact_dupes_collapsed_into_this":0},"modules":["modules/language-audit.md","modules/exemplar-research.md"],"version":"v1","category":"documents-office","complexity":"high","import_tag":"clean-skills-v1","model_hint":"deep","alwaysApply":false,"description":"Refreshes README structure and content using repo context and exemplar research. Use when README needs a structural update after significant project changes.","dependencies":["sanctum:shared","sanctum:git-workspace-review","imbue:proof-of-work","scribe:slop-detector","scribe:doc-generator"],"estimated_tokens":1200,"progressive_loading":true}},"renderedAt":1782980303324}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.