agentleFS
Tony363Tony363/SuperClaude/.claude/skills/sc-readme/SKILL.md

sc-readme

Skill19 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

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
  1. Distinctive:

    DISCOVER: - Run git diff or git log to find changed files

    line 40
  2. Distinctive:

    ANALYZE: - Read changed files, categorize by type (API, config, deps, features)

    line 41
  3. Distinctive:

    GENERATE: - Update documentation sections via Edit tool

    line 45
  4. Very specific:

    When --scope all is used, discover and validate all documentation files in the project.

    line 87
  5. Very specific:

    When --cross-ref is enabled (default), verify consistency across docs:

    line 124
  6. Distinctive:

    Edit: - Update documentation sections in-place

    line 187
  7. Distinctive:

    Back up docs: before modifications

    line 228
  8. Distinctive:

    Preserve custom content: not related to code changes

    line 231
  9. Very specific:

    Only modify .md files in the documented scope

    line 233

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.