Skill System Auditor

• the user asks for a global consistency audit of a skill repository
• newly added skills may have made README, AGENTS, CLAUDE, lifecycle categories, or role categories stale
• cross-skill routing, pair-with guidance, or memory writeback expectations need alignment
• future-skill references, obsolete TODOs, or implemented-gap mentions need cleanup
• helper paths, templates, frontmatter, or validation scripts need a maintenance pass
• the user wants to decide what skills are missing next

skill-creator

• skill-creator

  when audit findings lead to new or revised skill instructions

• research-project-memory

  when the skill collection's roadmap and decisions should persist

• update-docs

  when documentation drift is broad but not skill-specific

• safe-git-ops

  before committing or recovering from Git state issues

Skill Directory Layout

<installed-skill-dir>/
├── SKILL.md
└── references/
    ├── audit-rubric.md
    ├── doc-sync-map.md
    └── report-template.md

Progressive Loading

• Always read

  references/audit-rubric.md

  and

  references/doc-sync-map.md

  .
• Read

  references/report-template.md

  before writing an audit report.
• If the repository has its own validation script or AGENTS instructions, read those before making edits.

Core Principles

• Audit lifecycle behavior, not only file presence.
• A skill collection should have clear phase coverage, role coverage, routing, and handoff points.
• Top-level docs must match the actual inventory.
• "Future skill" references should not name skills that already exist.
• Memory writeback expectations should cover every skill that changes durable project state.
• Keep fixes surgical. Do not rewrite mature skills just to make wording uniform.
• Validate locally before commit, push, or reinstall.

Step 1 - Recover Repository Rules

• AGENTS.md

  ,

  CLAUDE.md

  , README, or equivalent repo guidance
• validation scripts
• skill directory layout
• recent audit reports or roadmap memory, if available

Step 2 - Inventory Skills

skills/*/SKILL.md

• name
• description trigger
• lifecycle phase
• role category
• pair-with routing
• helper references
• memory writeback behavior
• whether it is planned, implemented, deprecated, or duplicated

Step 3 - Audit Lifecycle Coverage

references/audit-rubric.md

• idea validation
• literature and positioning
• algorithm design
• project setup
• experiment design
• baseline choice
• experiment execution
• result diagnosis
• evidence capture
• writing and paper evidence
• reviewer simulation
• citation coverage and correctness
• submission
• rebuttal
• camera-ready
• artifact evaluation
• release and maintenance
• advisor or collaborator communication
• skill-system maintenance

• real-gap

  : useful capability is missing

• covered-by-existing

  : existing skill covers it

• not-in-scope

  : outside repository purpose

• hardening

  : tests, examples, or docs needed rather than a new skill

Step 4 - Audit Cross-Skill Routing

• literature -> baseline -> experiment design
• experiment result -> diagnosis -> paper evidence -> writing
• reviewer simulation -> evidence board -> experiments/writing
• rebuttal -> camera-ready -> artifact/release
• advisor feedback -> decisions/actions/memory
• audit findings -> skill creation/docs update

Step 5 - Audit Memory Writeback

• decisions
• claims
• evidence
• risks
• actions
• paper status
• code/worktree state
• reviewer and rebuttal state
• artifact and release state
• advisor feedback
• skill-system roadmap decisions

Step 6 - Audit Documentation and Stale References

references/doc-sync-map.md

• implemented skills still listed as future
• missing skills in top-level tables
• old lifecycle counts
• stale installation examples
• obsolete helper paths
• broken reference links
• duplicate table entries
• inconsistent skill names

Step 7 - Write the Audit Report

references/report-template.md

docs/audits/global-consistency-audit_YYYY-MM-DD.md

• scope
• inventory count
• lifecycle decision
• findings fixed
• findings left open
• real remaining gaps
• validation result
• recommended next skill or hardening step

Step 8 - Fix, Validate, and Handoff

1. Make the smallest edits that restore consistency.
2. Run the repo validation command.
3. Re-run targeted searches for stale skill names.
4. Summarize changed files and remaining risk.
5. Commit, push, and reinstall only if the user asks or the local workflow requires it.

Final Sanity Check

• actual skill inventory matches top-level docs
• lifecycle and role categories include all implemented skills
• cross-skill routing covers important feedback loops
• memory writeback covers state-changing skills
• future-skill references are accurate
• validation passes
• audit report separates fixed issues from remaining gaps