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
+18 -2
View File
@@ -1,9 +1,11 @@
---
description: Walk every CLAUDE.md in the project, prune stale references (removed deps, deleted paths, broken modular links), enforce the 150-line cap by splitting into sub-files, and repair the root ↔ subdirectory chain (markdown links + @path imports).
argument-hint: "[--dry-run | --paths-only | <directory>]"
argument-hint: "[--weekly | --dry-run | --paths-only | <directory>]"
when_to_use: |
Run after refactors, dependency changes, deleted directories, or when any single
CLAUDE.md is near the 150-line cap. Also run before cutting a release so the
CLAUDE.md is near the 150-line cap. Use --weekly for a periodic audit pass that
parallel-invokes the drift-audit, link-check, and dependency-rescan forked skills
before doing the normal sync work. Also run before cutting a release so the
documentation tag-snapshot is truthful.
allowed-tools:
- Read
@@ -47,6 +49,20 @@ This command keeps every CLAUDE.md in the project current, lean, and chained. Ap
---
## Phase 0: Weekly Audit (only when `--weekly` is passed)
When the user invokes `/sync-claude-md --weekly`, run the three audit skills in parallel via the **Skill tool** before touching any file. Each is forked (`context: fork`, `agent: Explore`) so its work happens in an isolated context and only the summary returns:
1. `Skill(claude-md-drift-audit)` — references against last 7 days of git history.
2. `Skill(claude-md-link-check)``@path` imports and markdown links resolve.
3. `Skill(claude-md-dependency-rescan)` — Tech Stack sections vs. manifest files.
Issue all three in a single message so they execute concurrently. Wait for all three to return, then aggregate their findings into one report at the top of this run — `## Weekly Audit Summary` with one subsection per skill. If any audit returns findings, proceed to Phase 1 with those findings in mind so the sync work resolves them. If all three are clean, skip to Phase 4 (chain repair) — no edits required.
When `--weekly` is not passed, skip this phase entirely and start at Phase 1.
---
## Phase 1: Inventory
Discover every CLAUDE.md in the project (skipping vendor directories) and report sizes.