Update Claudemd
Reconcile stale CLAUDE.md and scoped `.claude/rules/*.md` topic files with the real codebase and git history.
Overview
update-claudemd is a journey-wide agent skill that refreshes project CLAUDE.md and path-scoped rule files—usable whenever a solo builder needs accurate agent instructions before committing to more work.
Install
npx skills add https://github.com/gupsammy/claudest --skill update-claudemdWhat is this skill?
- Reconciles CLAUDE.md and every `.claude/rules/` topic file against codebase and git since last commit
- Enforces progressive disclosure: root index plus path-scoped topic files with `paths:` frontmatter
- Justification gate—content must change how the agent behaves, not duplicate discoverable code
- Topic files audited as first-class content, not append-only dumps
- Scoped topic files live at `.claude/rules/*.md` with required `paths:` frontmatter
Adoption & trust: 1 installs on skills.sh; 253 GitHub stars; 3/3 security scanners passed (skills.sh audits); trending (+100% hot-view momentum).
What problem does it solve?
Your CLAUDE.md is long, outdated, or duplicates what grep already finds, so every agent session burns tokens on stale guidance.
Who is it for?
Repos with Claude Code where CLAUDE.md or `.claude/rules/` grew organically and now fights the codebase.
Skip if: One-off tweaks when you only need a single sentence added without audit—or when you want to edit user-global `~/.claude/CLAUDE.md` without explicit request.
When should I use this skill?
User says update CLAUDE.md, refresh CLAUDE.md, sync CLAUDE.md with the codebase, reorganize CLAUDE.md, optimize project instructions, or when CLAUDE.md is stale, verbose, or out of sync.
What do I get? / Deliverables
You get a justified, progressively disclosed instruction set aligned to git reality, with topic files scoped by `paths:` frontmatter.
- Reconciled CLAUDE.md index
- Updated `.claude/rules/*.md` topic files with `paths:` scopes
Recommended Skills
Journey fit
Useful at every journey phase - explore requirements and options before committing to a direction.
Where it fits
Trim CLAUDE.md so prototype agents stop assuming removed experiments still exist.
Split backend conventions into a `paths:`-scoped rules file after a monorepo restructure.
Align review checklists in rules with the branch policies you actually enforce in CI.
Update runbook pointers in CLAUDE.md after on-call paths and ownership changed.
Point marketing copy rules to the folder that owns public docs without loading them on every backend edit.
How it compares
Use this structured reconciliation instead of manually pasting architecture essays into CLAUDE.md.
Common Questions / FAQ
Who is update-claudemd for?
Solo and indie developers on Claude Code who maintain project-level CLAUDE.md and `.claude/rules/` and need those files to match how the repo actually works.
When should I use update-claudemd?
Say update or refresh CLAUDE.md after large refactors, when instructions feel stale, before major build or ship pushes, or during operate iteration when conventions changed—any time agent behavior should track repo truth.
Is update-claudemd safe to install?
It can Edit and Write project docs and run limited git and file Bash; review the Security Audits panel on this page and commit before a full reconciliation run.
SKILL.md
READMESKILL.md - Update Claudemd
# Update and Optimize CLAUDE.md Reconcile project CLAUDE.md and its topic files against codebase reality and git history since each file's last commit. Enforce progressive disclosure: CLAUDE.md is a top-level index of project identity, universal invariants, and pointers to topic files at `.claude/rules/*.md`. Files in `.claude/rules/` auto-load at SessionStart unless scoped with `paths:` frontmatter — every topic file this skill writes must carry that frontmatter so it loads only when its subsystem's files are touched, not on every session. Reconciliation scope includes every file in `.claude/rules/`. Topic files are first-class content — they share the same staleness, accuracy, and duplication risks as CLAUDE.md itself and must be audited, reconciled, and (when warranted) edited during every run. They are not appendices. Scope boundary: project CLAUDE.md (L1) and its topic files only. User-global `~/.claude/CLAUDE.md` (L0) is out of scope unless the user explicitly asks. ## Governing Principle Content in CLAUDE.md is justified only if it changes how Claude acts in the next session AND is needed across most tasks — not subsystem-specific. Subsystem-scoped content still matters but belongs in a topic file, loaded on demand. Content in a topic file is justified only if it changes how Claude acts within its subsystem AND is accurate against current codebase reality. Stale topic files are worse than missing ones because Claude trusts them. Phase 3 operationalizes this principle with a seven-action set that lets content flow both downward (demote from CLAUDE.md to a topic file) and upward (promote from a topic file back to CLAUDE.md when a detail becomes universal). The goal is a living progressive-disclosure hierarchy, not a one-way archive. ## Budget CLAUDE.md: soft target ~120 lines, soft ceiling 150 lines. Over-budget files are flagged, not forced — hand-maintained CLAUDE.md is respected. Line counts measured with `wc -l`. Topic files: informational soft ceiling ~300 lines each. Topic files legitimately grow as their subsystem grows; past ~300 lines, flag the overage in Phase 7 and suggest splitting by sub-topic. Never block. The CLAUDE.md budget is the only hard constraint. ## Fan-out Rule Codebase research scales with project size and churn. Compute once in Phase 1, apply in Phase 2. Signals: - `churn` — commits since last CLAUDE.md touch: `git log --since="<date>" --oneline --no-merges | wc -l` - `files` — tracked files: `git ls-files | wc -l` N (codebase-scan shards): | churn | files | N | |------------|---------------|---| | < 20 | < 100 | 1 | | 20 – 59 | 100 – 499 | 2 | | 60 – 149 | 500 – 1999 | 3 | | ≥ 150 | ≥ 2000 | 4 | Compute N for each column independently. Take the max. Cap at 4. When N > 1, partition by top-level directory clusters (e.g. `plugins/` → shard 1; `scripts/ + tests/` → shard 2). ## Phase 1 — Orient and Compute Fan-out Glob for `CLAUDE.md` at the project root. If missing, inform the user that creation is out of scope for this skill and stop. Record current `CLAUDE.md` line count with `wc -l`. List `.claude/rules/*.md` if the directory exists and record each topic file's line count AND last-commit date via `git log -1 --format="%ai" -- <path>`. The per-file dates are required in Phase 2 so Agent B can anchor each file's staleness window independently — using CLAUDE.md's date for every file produces wrong windows when cadences differ. Run cheap git probes in two steps. First, resolve the last CLAUDE.md commit date