feat(skills): three forked task-style audit skills + /sync-claude-md --weekly orchestration

Three new task-style skills, each using Anthropic's context: fork + agent:
Explore so the work happens in an isolated subagent context and only a
short summary returns to the main session.

skill/claude-md-drift-audit/SKILL.md (51 lines):
  Walks the last N days of git history (default 7) and flags CLAUDE.md
  lines that reference deleted paths, renamed paths, or removed
  dependencies from that window. Returns a punch list with file:line.
  Read-only. Standalone invocation: /claude-md-drift-audit [days=7].

skill/claude-md-link-check/SKILL.md (51 lines):
  Verifies every @path chain import and every relative markdown link
  inside every CLAUDE.md resolves to an existing file. Returns broken
  links with file:line. Read-only. Standalone: /claude-md-link-check
  [path-glob].

skill/claude-md-dependency-rescan/SKILL.md (54 lines):
  Re-detects the project's tech stack from package.json /
  requirements.txt / pyproject.toml / go.mod / Cargo.toml and diffs
  against every CLAUDE.md's Tech Stack section. Returns added /
  removed / renamed per file. Read-only. Standalone:
  /claude-md-dependency-rescan [manifest-path].

command/sync-claude-md.md:
  - argument-hint and when_to_use mention --weekly.
  - New Phase 0 (only when --weekly is passed): invoke the three skills
    above in parallel via the Skill tool, aggregate findings into
    ## Weekly Audit Summary, then proceed to existing Phase 1.
  - Without --weekly, Phase 0 is skipped entirely (no behaviour change
    for normal sync runs).

.claude-plugin/plugin.json:
  skills array now lists all five entries (existing two + three new).

Verified (6/6 smoke tests):
  - Plugin manifest is valid JSON; 5 skills registered; all 8
    referenced paths resolve on disk.
  - Each new SKILL.md parses; context=fork, agent=Explore, both
    description and when_to_use present, allowed-tools is a list,
    body ≤ 60 lines.
  - Each body is imperative (numbered steps present, not reference
    material — fork-context requires explicit task instructions).
  - Sync command body contains Phase 0, all three skill references,
    parallel-invocation language, and Skill in allowed-tools.
  - Skill name in frontmatter matches the directory name for every
    new skill (so /claude-md-drift-audit etc. register correctly).
This commit is contained in:
Claude
2026-05-19 01:31:54 +00:00
parent e33fa8326b
commit 45767e8840
6 changed files with 188 additions and 3 deletions
@@ -0,0 +1,54 @@
---
name: claude-md-dependency-rescan
description: Re-detect this project's tech stack from package.json / requirements.txt / pyproject.toml / go.mod / Cargo.toml and diff it against the Tech Stack section of every CLAUDE.md. Read-only — returns added / removed / renamed dependencies, never edits.
when_to_use: |
Use when the user asks "is my Tech Stack section up to date?", "what deps changed?",
"rescan my dependencies", after dependency upgrades, or as part of /sync-claude-md --weekly.
argument-hint: "[manifest-path]"
context: fork
agent: Explore
allowed-tools:
- Read
- Glob
- Grep
- "Bash(find:*)"
- "Bash(cat:*)"
disable-model-invocation: false
---
# CLAUDE.md Dependency Rescan (forked, read-only)
Optional explicit manifest: `$ARGUMENTS` (default: auto-detect all five manifest types).
Run these steps in order. Do not modify any file.
1. **Detect manifests.** Look for `package.json`, `requirements.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml` at the repo root and one level deep (workspaces/monorepos).
2. **Extract declared dependencies** from each:
- `package.json` → keys of `dependencies` and `devDependencies` (skip versions).
- `requirements.txt` → first token of each non-comment line.
- `pyproject.toml``[project.dependencies]` / `[tool.poetry.dependencies]` keys.
- `go.mod` → module paths under `require (...)`.
- `Cargo.toml` → keys under `[dependencies]` / `[dev-dependencies]`.
3. **Inventory documented deps** in every `CLAUDE.md` (and `.claude/rules/*.md`): grep for the Tech Stack / Dependencies sections and the lists under them.
4. **Compute three sets per file:**
- `added`: in manifest but absent from this CLAUDE.md.
- `removed`: documented in this CLAUDE.md but absent from manifest.
- `renamed`: documented and present in manifest but spelled differently (`react-router` vs `react-router-dom`, `pg` vs `psycopg2`).
5. **Return** in this exact shape:
```
## Dependency Rescan
Manifests detected: <list>
Total declared deps: <count>
### Per file
#### <path-to-CLAUDE.md>
- Added (in manifest, not documented): <list or "none">
- Removed (documented, not in manifest): <list or "none">
- Renamed / aliased: <list or "none">
```
6. If every documented set matches its manifest, return exactly `## Dependency Rescan\n\nAll documented deps match manifests. <M> files inspected.`. Do not pad.
**Hard rule**: do not propose specific edits — just surface the diffs. `/sync-claude-md` decides whether to write them.
+51
View File
@@ -0,0 +1,51 @@
---
name: claude-md-drift-audit
description: Audit every CLAUDE.md in this project for drift against the last week of git history. Flags sections that reference deleted files, renamed paths, or removed dependencies. Read-only — returns a punch list, never edits.
when_to_use: |
Use when the user asks "is my CLAUDE.md still accurate?", "audit my docs for staleness",
"what changed in the last week?", or as part of /sync-claude-md --weekly.
argument-hint: "[days=7]"
context: fork
agent: Explore
allowed-tools:
- Read
- Glob
- Grep
- "Bash(git log:*)"
- "Bash(git diff:*)"
- "Bash(git status:*)"
- "Bash(find:*)"
disable-model-invocation: false
---
# CLAUDE.md Drift Audit (forked, read-only)
Days window: `$ARGUMENTS` (default `7` if empty).
Perform these steps in order, then return a single punch-list summary. Do not modify any file.
1. **Inventory** every `CLAUDE.md` and `*.claude/rules/*.md` in the tree using `find . -name "CLAUDE.md" -type f -not -path "*/.git/*" -not -path "*/node_modules/*"`. List paths and line counts.
2. **Collect change signal** for the window:
- `git log --since="$ARGUMENTS days ago" --name-status --no-merges --diff-filter=DR` → deleted and renamed paths.
- `git diff "@{$ARGUMENTS days ago}" --name-status -- package.json requirements.txt pyproject.toml go.mod Cargo.toml 2>/dev/null` → manifest deltas (removed/added deps).
3. **Cross-reference** each CLAUDE.md against those signals using `grep` / `Read`:
- Mark any line that names a deleted or renamed path.
- Mark any line in a Tech Stack / Dependencies section that names a removed dep.
- Mark any `@path/...` chain import or markdown link whose target was deleted.
4. **Return** the punch list in this exact shape (markdown), nothing else:
```
## Drift Audit (window: <N> days)
Total CLAUDE.md inspected: <count>
Signals examined: <deleted_paths>, <renamed_paths>, <removed_deps>
### Findings
- <path>:<line> — <one-sentence reason> — suggested action
- ... (one bullet per drift; omit section if empty)
### Clean
- <path> (lines unchanged, references valid)
```
5. If no drift is found, return exactly `## Drift Audit\n\nNo drift in <N>-day window. <count> files inspected.`. Do not pad the output.
+51
View File
@@ -0,0 +1,51 @@
---
name: claude-md-link-check
description: Verify every @path chain import and every markdown link inside every CLAUDE.md in this project resolves to an existing file. Read-only — returns broken links with file:line refs, never edits.
when_to_use: |
Use when the user asks "check my CLAUDE.md links", "are the @-imports still valid?",
"find broken cross-references", or as part of /sync-claude-md --weekly.
argument-hint: "[path-glob]"
context: fork
agent: Explore
allowed-tools:
- Read
- Glob
- Grep
- "Bash(find:*)"
- "Bash(test:*)"
- "Bash(ls:*)"
disable-model-invocation: false
---
# CLAUDE.md Link Check (forked, read-only)
Optional path-glob: `$ARGUMENTS` (default `.` — entire tree).
Run these steps in order. Do not modify any file.
1. **Inventory.** `find <root> -name "CLAUDE.md" -type f -not -path "*/.git/*" -not -path "*/node_modules/*"`. Also include `.claude/rules/*.md`. Record paths.
2. **Extract candidates** from each file:
- **Chain imports** — lines matching `^@\S+`. The literal after `@` is a relative path.
- **Markdown links** — `[text](target)` where `target` is not an HTTP(S) URL, not `mailto:`, not a bare anchor `#section`.
3. **Resolve each candidate** relative to the file containing it (use `Read` on the parent file to confirm position, then `test -e <resolved-path>` or `Glob`).
- For `@../CLAUDE.md` inside `skill/CLAUDE.md`, resolved path is `CLAUDE.md`.
- For `[Backend](backend/CLAUDE.md)` inside the root, resolved path is `backend/CLAUDE.md`.
4. **Return** the report in this exact shape:
```
## Link Check
Files inspected: <count>
References checked: <chain_imports> @-imports, <md_links> markdown links
### Broken
- <file>:<line> — `<original-target>` → does not resolve (expected `<absolute-path>`)
- ... (omit section if empty)
### Clean
<count> references resolved.
```
5. If everything resolves, return exactly `## Link Check\n\nAll <N> references resolved across <M> files.`. Do not pad.
**Hard rule**: never invent a fix. Report the broken target verbatim. Repair is the user's call (or `/sync-claude-md`'s).