sc-readme
Skill4 starsChanged 8 months agoMITView on GitHub
Auto-update project documentation by analyzing git changes with cross-reference validation and staleness reporting. Supports single-file README updates or multi-document review. Use when synchronizing documentation with code changes.
- Reads credentials
1 other project uses a version of this.
Adopted by
Most recently taken up by
- Tony363/SuperClaudeword for word, first seen Apr 4, 2026
Other versions1 project uses a version of this.
Word for word · 1
- Tony363/SuperClaude★ 19100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository37 other files it gives its agents.
- AGENTS.mdAGENTS.md
- agent-data-engineerSkill
- agent-fullstack-developerSkill
- agent-kubernetes-specialistSkill
- agent-ml-engineerSkill
- agent-performance-engineerSkill
- agent-react-specialistSkill
- agent-security-engineerSkill
- agent-technical-writerSkill
- ask-multiSkill
- askSkill
- learned-skills-indexSkill
- sc-analyzeSkill
- sc-brainstormSkill
- sc-buildSkill
- sc-cicd-setupSkill
- sc-code-reviewSkill
- sc-designSkill
- sc-documentSkill
- sc-e2eSkill
- sc-estimateSkill
- sc-evaluateSkill
- sc-explainSkill
- sc-gitSkill
- sc-implementSkill
- sc-improveSkill
- sc-log-fixSkill
- sc-mcpSkill
- sc-pr-checkSkill
- sc-pr-fixSkill
- sc-principlesSkill
- sc-pushSkill
- sc-researchSkill
- sc-tddSkill
- sc-testSkill
- sc-workflowSkill
- sc-worktreeSkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 6 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 40
DISCOVER: - Run git diff or git log to find changed files
- Distinctive: line 41
ANALYZE: - Read changed files, categorize by type (API, config, deps, features)
- Distinctive: line 45
GENERATE: - Update documentation sections via Edit tool
- Very specific: line 87
When --scope all is used, discover and validate all documentation files in the project.
- Very specific: line 124
When --cross-ref is enabled (default), verify consistency across docs:
- Distinctive: line 187
Edit: - Update documentation sections in-place
- Distinctive: line 228
Back up docs: before modifications
- Distinctive: line 231
Preserve custom content: not related to code changes
- Very specific: line 233
Only modify .md files in the documented scope
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Documentation Auto-Update Skill
Intelligent documentation maintenance based on git changes with cross-reference validation, staleness reporting, and multi-model consensus for critical updates.
Quick Start
# Update README based on current branch changes
/sc:readme
# Multi-document review and update (all project docs)
/sc:readme --scope all
# Target specific documentation
/sc:readme --scope api-docs
# Preview changes without writing
/sc:readme --preview
# Analyze N recent commits instead of branch diff
/sc:readme --commits 20
# Force PAL consensus for all updates
/sc:readme --consensus
# Compare against different base branch
/sc:readme --base develop
# Staleness report only (no changes)
/sc:readme --report-onlyBehavioral Flow
- DISCOVER - Run
git difforgit logto find changed files - ANALYZE - Read changed files, categorize by type (API, config, deps, features)
- MAP - Match changed files to affected documentation using source-of-truth mapping
- VALIDATE - Cross-reference consistency checks across all docs
- PLAN - Identify sections needing updates, generate staleness report
- GENERATE - Update documentation sections via Edit tool
- VERIFY - Review final docs with PAL codereview
Flags
| Flag | Type | Default | Description |
--base | string | main | Base branch to compare against |
--preview | bool | false | Preview changes without writing |
--consensus | bool | false | Force PAL consensus for all updates |
--scope | string | readme | Target: readme, all, or custom doc paths |
--commits | int | - | Analyze N recent commits instead of branch diff |
--report-only | bool | false | Generate staleness report without changes |
--cross-ref | bool | true | Enable cross-reference validation |
Git Commands Used
# Branch diff mode (default)
git diff main...HEAD --name-status
git diff main...HEAD
git log main...HEAD --oneline
# Commit mode (--commits N)
git log --oneline -N --name-only --pretty=format: | sort -u | grep -v '^$'
git log --oneline -NChange Categories
| Category | File Patterns | Affected Docs |
| API | *.py, *.ts, *.js with new exports | README, API docs |
| Dependencies | package.json, requirements.txt, pyproject.toml | README, Installation |
| Config | .env*, *.config.*, settings.* | README, Config docs |
| Features | New modules, significant additions | README, Feature docs |
| Database | models/, migrations/ | Database docs, README |
| Frontend | src/components/, src/pages/ | Frontend docs, README |
| Infrastructure | docker-compose*, Dockerfile, CI configs | DevOps docs, README |
Multi-Document Mode (--scope all)
When --scope all is used, discover and validate all documentation files in the project.
Document Discovery
Auto-detect documentation files:
# Find all markdown docs (excluding node_modules, .venv, etc.)
find . -name "*.md" -not -path "*/node_modules/*" -not -path "*/.venv/*" -not -path "*/dist/*"Common documentation patterns:
| Doc File | Purpose |
README.md | Main project documentation |
CLAUDE.md | Claude Code instructions |
CONTRIBUTING.md | Contribution guidelines |
docs/*.md | Extended documentation |
frontend/README.md | Frontend-specific docs |
api/README.md | API documentation |
Source-of-Truth Mapping
Map code changes to affected documentation:
| Code Pattern | Affected Documentation |
src/api/**, app/routers/** | README, API docs |
src/models/**, app/models/** | README, Database docs |
src/components/**, frontend/src/** | README, Frontend docs |
migrations/** | Database docs |
.env.example | README, all docs with env references |
tests/** | README (test structure section) |
Cross-Reference Validation
When --cross-ref is enabled (default), verify consistency across docs:
- API routes mentioned in README match actual route handlers
- Environment variables match across all docs and
.env.example - File paths referenced in docs actually exist (via Glob)
- Component names are consistent across all documentation
- Documented commands are syntactically valid
Staleness Report
## Documentation Staleness Report
**Commits Analyzed**: 20 | **Docs Scanned**: 6 | **Issues Found**: 3
### README.md
**Status**: STALE
**Affected by**: src/api/users.py, src/models/user.py
- [ ] API Routes table missing new `/users/bulk` endpoint
- [ ] Environment variables section missing `BULK_IMPORT_LIMIT`
### docs/DATABASE.md
**Status**: UP-TO-DATE
No changes needed.
### frontend/README.md
**Status**: STALE
**Affected by**: src/components/UserProfile.tsx
- [ ] Component list missing UserProfileUpdate Order
Process documents in dependency order:
- README.md first (primary reference)
- CLAUDE.md second (must stay consistent with README)
- Other docs after (reference README as source of truth)
MCP Integration
PAL MCP
# Consensus for API/breaking changes
mcp__pal__consensus(
models=[{"model": "gpt-5.2", "stance": "for"}, {"model": "gemini-3-pro", "stance": "against"}],
step="Evaluate: Does this documentation update accurately reflect the code changes?",
relevant_files=["/README.md", "/src/changed_file.py"]
)
# Review final documentation
mcp__pal__codereview(
review_type="quick",
step="Review documentation accuracy and cross-reference consistency",
relevant_files=["/README.md", "/docs/API.md"]
)Tool Coordination
- Bash - Git commands (
git diff,git log) - Read - Documentation files, changed source files
- Edit - Update documentation sections in-place
- Glob - File path validation, doc discovery
- Grep - Cross-reference checks, pattern validation
Examples
Single README Update
/sc:readme
# 1. git diff main...HEAD --name-status
# 2. Read README.md + changed files
# 3. Identify sections needing updates
# 4. PAL consensus if API changes detected
# 5. Update README.mdMulti-Document Review
/sc:readme --scope all --commits 20
# 1. git log --oneline -20 for change context
# 2. Discover all .md documentation files
# 3. Map changes to affected docs
# 4. Cross-reference validation
# 5. Generate staleness report
# 6. Update all affected docsStaleness Report Only
/sc:readme --report-only --scope all
# Generates report without making changesPreview Mode
/sc:readme --preview
# Same analysis, but output proposed changes instead of writingGuardrails
- Back up docs before modifications
- Never remove sections without user confirmation
- Require consensus for breaking changes
- Preserve custom content not related to code changes
- Process in order - README first, then dependent docs
- Only modify
.mdfiles in the documented scope - Git-based rollback always available via
git checkout
Related Skills
/sc:git- Git operations/sc:document- General documentation generation/sc:pr-check- Pre-PR validation
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

