MCPInstall

sc-readme

by tony363Docs & Writing

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.

Installs
93
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/tony363/superclaude --skill sc-readme
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads sc-readme automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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-only

Behavioral Flow

  1. DISCOVER - Run git diff or git log to find changed files
  2. ANALYZE - Read changed files, categorize by type (API, config, deps, features)
  3. MAP - Match changed files to affected documentation using source-of-truth mapping
  4. VALIDATE - Cross-reference consistency checks across all docs
  5. PLAN - Identify sections needing updates, generate staleness report
  6. GENERATE - Update documentation sections via Edit tool
  7. VERIFY - Review final docs with PAL codereview

Flags

FlagTypeDefaultDescription
--basestringmainBase branch to compare against
--previewboolfalsePreview changes without writing
--consensusboolfalseForce PAL consensus for all updates
--scopestringreadmeTarget: readme, all, or custom doc paths
--commitsint-Analyze N recent commits instead of branch diff
--report-onlyboolfalseGenerate staleness report without changes
--cross-refbooltrueEnable 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 -N

Change Categories

CategoryFile PatternsAffected Docs
API*.py, *.ts, *.js with new exportsREADME, API docs
Dependenciespackage.json, requirements.txt, pyproject.tomlREADME, Installation
Config.env*, *.config.*, settings.*README, Config docs
FeaturesNew modules, significant additionsREADME, Feature docs
Databasemodels/, migrations/Database docs, README
Frontendsrc/components/, src/pages/Frontend docs, README
Infrastructuredocker-compose*, Dockerfile, CI configsDevOps 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 FilePurpose
README.mdMain project documentation
CLAUDE.mdClaude Code instructions
CONTRIBUTING.mdContribution guidelines
docs/*.mdExtended documentation
frontend/README.mdFrontend-specific docs
api/README.mdAPI documentation

Source-of-Truth Mapping

Map code changes to affected documentation:

Code PatternAffected 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.exampleREADME, 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 UserProfile

Update Order

Process documents in dependency order:

  1. README.md first (primary reference)
  2. CLAUDE.md second (must stay consistent with README)
  3. 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.md

Multi-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 docs

Staleness Report Only

/sc:readme --report-only --scope all
# Generates report without making changes

Preview Mode

/sc:readme --preview
# Same analysis, but output proposed changes instead of writing

Guardrails

  1. Back up docs before modifications
  2. Never remove sections without user confirmation
  3. Require consensus for breaking changes
  4. Preserve custom content not related to code changes
  5. Process in order - README first, then dependent docs
  6. Only modify .md files in the documented scope
  7. 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

FAQ

What does the sc-readme skill do?

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.

How do I install sc-readme?

Run npx skills add https://github.com/tony363/superclaude --skill sc-readme in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/sc-readme/ (personal) or .claude/skills/sc-readme/ (project).

Which AI agents can use sc-readme?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is sc-readme safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains sc-readme?

It is published by tony363 in tony363/superclaude. It has 93 recorded installs.

More from tony363/superclaude

View all →

agent-performance-engineer

tony363/superclaude

Expert performance engineer specializing in system optimization, bottleneck identification, and scalability engineering. Masters performance testing, profiling, and tuning across applications, databases, and infrastructure with focus on achieving optimal response times and resource efficiency.

Code Quality & Workflow555 installs

agent-security-engineer

tony363/superclaude

Expert infrastructure security engineer specializing in DevSecOps, cloud security, and compliance frameworks. Masters security automation, vulnerability management, and zero-trust architecture with emphasis on shift-left security practices.

Security392 installs

sc-estimate

tony363/superclaude

Provide development estimates for tasks, features, or projects with intelligent analysis. Use when planning timelines, assessing complexity, or scoping resources.

Code Quality & Workflow184 installs

agent-fullstack-developer

tony363/superclaude

End-to-end feature owner with expertise across the entire stack. Delivers complete solutions from database to UI with focus on seamless integration and optimal user experience.

Frontend & Design154 installs

sc-design

tony363/superclaude

Design system architecture, APIs, and component interfaces with comprehensive specifications. Use when planning architecture, designing APIs, creating component interfaces, or modeling databases.

Frontend & Design113 installs

agent-technical-writer

tony363/superclaude

Expert technical writer specializing in clear, accurate documentation and content creation. Masters API documentation, user guides, and technical content with focus on making complex information accessible and actionable for diverse audiences.

Docs & Writing108 installs

Popular docs & writing skills

View category →

grill-with-docs

mattpocock/skills

A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.

Docs & Writing1.2M installs

lark-markdown

open.feishu.cn

飞书 Markdown：查看、创建、上传、编辑和比较飞书中的原生 Markdown 文件。当用户要操作飞书 Markdown 文件，或比较其远端版本及本地草稿时使用。纯本地 Markdown 文件操作不触发本 skill。不负责将 Markdown 导入为飞书在线文档，也不负责文件搜索、权限、评论、移动、删除等云空间管理操作。

Docs & Writing778.7K installs

writing-beats

mattpocock/skills

Writing, exploit; assemble raw material into a journey of beats, grounding each term before a beat leans on it.

Docs & Writing490.7K installs

writing-shape

mattpocock/skills

Writing, exploit: shape raw material into an article, paragraph by paragraph.

Docs & Writing490.2K installs

writing-fragments

mattpocock/skills

Writing, explore: mine raw fragments, no structure yet.

Docs & Writing489.6K installs

writing-for-agents

mattpocock/skills

Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.

Docs & Writing479.3K installs