Loading skill
Install any skill in seconds. Free to start, no credit card required.
Get Started Free →hashgraph-online/claude-md-drift-check
Use when detecting drift between CLAUDE.md (or AGENTS.md, the Codex CLI alias) / _meta narrative and live repository state. Ten checks: absolute-path resolution, 01-projects/ count claims, issue-reference freshness, session-file existence, command-count sync, session-config-parity (mandatory template keys = error, opt-in gaps = warning), vault-dir-parity (CLAUDE.md vs AGENTS.md), generated-rule-staleness (WARN-only), rule-scoping (paths:/globs: frontmatter defects, dangling rule citations, zero-
Passed 18 of 20 test cases with the skill, and 5 of 20 without it.
and 23 more in the full report
15 fixed5 passed either way2 still failing0 broke
Tokens, turns and time describe resource use, not a dollar price.
One of 15 test cases the skill fixed. Same model, same prompt, with and without the skill.
When no --include-path flags are explicitly provided on the CLI, which default relative paths are automatically included for scanning?
| Checked | Without skill | With skill |
|---|---|---|
| Default scope paths include the resolved instruction file. | Missed | Passed |
| Default scope paths include _meta/**/*.md. | Missed | Passed |
The instructions your model reads when the skill loads.
The instruction file is alias-resolved per
skills/_shared/instruction-file-resolution.md:CLAUDE.md(Claude Code / Cursor IDE) wins ties;AGENTS.md(Codex CLI) is picked up as a transparent alias whenCLAUDE.mdis absent. The resolved path and kind are surfaced in the JSON output (resolved_path,resolved_kind).
PHASE 1 IMPLEMENTED (2026-04-19). Session-end opt-in quality gate. Upstream of /close commit preparation, downstream of vault-sync.
CLAUDE.md is narrative SSOT for a repo's Session Config and project context. It decays quickly when surrounding state changes — paths get renamed, project counts shift, issues close, session files get pruned in digests. The drift-cluster closed by agents/vault#57 (3 items in one sweep) was the 4th incidence of the issue-description-drift-stale-filecount learning. Manual curation does not scale; this skill turns drift detection into a repeatable gate.
| # | Check | What it scans | How |
|---|---|---|---|
| 1 | path-resolver | Every absolute path /Users/… in scope files | existsSync(path) |
| 2 | project-count-sync | Hardcoded "N registered" / "N projects" claims next to 01-projects/ | compare to ls -d 01-projects/*/ |
| 3 | issue-reference-freshness | #NN in forward-looking sections (What's Next, Backlog, Open Issues, Offene Themen, Todo, Next Steps) | glab issue view NN --repo <origin> |
| 4 | session-file-existence | 50-sessions/YYYY-MM-DD-*.md references anywhere in scope | existsSync(vault/50-sessions/<file>) |
| 5 | command-count | "N commands" / "N /commands" claims in prose | compare to ls commands/*.md | wc -l; skipped if no commands/ dir |
| 6 | session-config-parity | Top-level keys under ## Session Config in CLAUDE.md / AGENTS.md | diff against docs/session-config-template.md; a missing MANDATORY (minimal-baseline) key is an error, a missing OPT-IN-baseline-only key is a warning |
| 7 | vault-dir-parity | vault-integration.vault-dir in BOTH CLAUDE.md AND AGENTS.md | reuse _parseVaultIntegration; flag when the two files disagree |
| 8 | generated-rule-staleness (WARN only) | .claude/rules/*.md with auto-generated: true frontmatter | extract learning-key; WARN when the key is absent from .orchestrator/metrics/learnings.jsonl or its learning's expires_at is in the past; skipped silently when no auto-generated rules exist |
| 9 | rule-scoping | .claude/rules/*.md frontmatter + ## See Also footers + .claude/rules/<name>.md citations in CLAUDE.md/AGENTS.md | five probes: paths: frontmatter (error), cited-but-missing rule citations (error), zero-match globs: patterns (warn), foreign PascalCase glob tokens (warn), unreadable rule files (warn — surfaced instead of silently skipped); skipped silently when .claude/rules/ is absent |
| 10 | docs-parity | docs/components.md count-claims, Session Config key parity (docs/session-config-template.md vs docs/session-config-reference.md), .claude/metrics/ stale-path references in docs/*.md / docs/examples/*.md | three sub-checks (a/b/c) — see below; skipped silently when docs/components.md is absent |
Check 3 deliberately scopes to forward-looking sections. Mentions inside "Recently Closed", "Decisions", "Archive", etc. describe history and must not be flagged.
Check 5 counts *.md files directly inside commands/ (non-recursive, non-hidden). The commands/ directory is resolved relative to VAULT_DIR by default; use --commands-dir <path> to override.
Check 6 (issue #30; severity split per #785) extracts the YAML block under ## Session Config from both the canonical template (docs/session-config-template.md by default, override with --config-template) and the resolved local instruction file — reading the template TWICE, once per occurrence: { occurrence: 'first' } reaches the "Full minimal baseline" (the 7 schema-mandatory keys), { occurrence: 'last' } reaches the "Full opt-in baseline" (the full key catalog, a strict superset of the minimal block). A template key missing from the local file is a session-config-parity error when it belongs to the minimal-baseline set, and a warning when it is opt-in-baseline-only — a consumer repo that legitimately does not adopt an opt-in feature (e.g. no handover-gate) must not go red; only the true 7-key mandatory contract does. When the template carries a single ## Session Config heading (no separate opt-in block), 'first' and 'last' resolve to the same block and every key is treated as mandatory, preserving prior behaviour for single-block templates. Both fenced YAML (```yaml ... ```) and raw YAML body (up to next ## heading) are accepted. The check skips gracefully when the template file is absent, when no instruction file is detected, or when explicitly disabled via --skip-session-config-parity.
The parity set is template-driven: every column-0 YAML key under ## Session Config in the template (across both occurrences) is checked. As of the gsd Pattern Adoption Quick-Wins bundle (PRD 2026-05-22, issues #517–#521), the template-side keys include four opt-in top-level blocks:
test cases passed, vs 5 / 20 without
More skills from the same source and nearby in the registry, with their headline benchmark lift.