skill-audit
GitHub对项目中所有技能进行全面健康审计，检查陈旧引用、安全护栏、跨技能一致性、上下文效率及步骤合规性。适用于批量编辑后、定期维护或技能异常时，生成质量报告以确保技能可靠性和规范性。
Trigger Scenarios
Install
npx skills add NeverSight/learn-skills.dev --skill skill-audit -g -y
SKILL.md
Frontmatter
{
"name": "skill-audit",
"description": "Run a comprehensive health audit across all skills — checks staleness, safety guards, cross-skill consistency, context efficiency, step compliance, and learning pipeline. Use when you want to verify skill quality, after bulk skill edits, or as a periodic maintenance check.",
"user-invokable": true
}
Skill Audit — Comprehensive Health Check
Run 6 automated checks across all project skills and produce a health report card.
When to Run
- After bulk skill edits or new skill creation
- Monthly maintenance (add to
/start-dayon first Monday of month) - When a skill misbehaves (wrong trigger, stale data, skipped steps)
Checks
Run checks 1-4 in parallel via subagents. Check 5 requires the current session's transcript. Check 6 requires the /evolve pipeline.
Check 1: Staleness Detection
Dispatch an Explore agent:
Scan all .claude/skills/*/SKILL.md and .claude/skills/*/skill.md files.
For each skill, extract:
- File paths referenced → verify they exist via Glob
- Config IDs or identifiers referenced → verify against the project's source of truth config files
- Function/export names referenced → spot-check against actual source files
Report ONLY stale references (files that don't exist, IDs not in config).
Pass criteria: Zero stale file paths or config IDs.
Check 2: Negative Output (Safety Guards)
Dispatch an Explore agent:
Read your project docs (CLAUDE.md, README, etc.) for known gotchas or warnings.
For each gotcha, identify which skill(s) should warn about it.
Then read those skills and check whether the warning is PRESENT or MISSING.
Report MISSING guards only.
Pass criteria: All known gotchas have corresponding warnings in the relevant skill.
Check 3: Cross-Skill Consistency
Dispatch an Explore agent:
Identify 3-5 cross-cutting topics in your project (e.g., authentication patterns,
database connections, deployment procedures, API conventions, caching strategies).
For each topic, read all skills that reference it and check for contradictions
or incomplete coverage.
Report CONTRADICTIONS and INCOMPLETE coverage only.
Pass criteria: No contradictions. Incomplete coverage flagged as warnings.
Check 4: Context Efficiency
Count lines per skill (body + references). Flag skills that are:
- Over 400 lines with NO references/ directory (all content in body)
- Rarely triggered (estimate < 1x/month) AND over 200 lines
# Run in .claude/skills/
for dir in */; do
name="${dir%/}"
skill_file=""
[ -f "$dir/SKILL.md" ] && skill_file="$dir/SKILL.md"
[ -f "$dir/skill.md" ] && skill_file="$dir/skill.md"
[ -n "$skill_file" ] && echo "$(wc -l < "$skill_file") $name"
done | sort -rn
Pass criteria: No skill over 400 lines without references/ split.
Check 5: Step Compliance (if applicable)
If process skills were used in the CURRENT session, grade them against their documented steps:
- deploy: Built first? Lint? From project dir? Correct branch? Post-deploy verify?
- session-notes: All 7 sections? Keywords? MEMORY.md updated? Roadmap updated?
- research-gate: Constraints? Patterns? Gotchas? Unknowns? Alternatives table? User approval?
- triage-ideas: Read inbox? Classify? Confirm? Route to Obsidian + database? Clear inbox?
- merge-to-main: All parallel agents? Verification checks? Clean tree?
Pass criteria: All documented steps followed. Skipped steps are flagged.
Check 6: Learning Pipeline Health (if /evolve is installed)
If the project has a continuous learning pipeline (.claude/scripts/instinct-cli.js), check its health:
node .claude/scripts/instinct-cli.js status
node .claude/scripts/instinct-cli.js list
node .claude/scripts/instinct-cli.js prune
Check (all three matter; anything else is noise):
- Observations accumulating?
statusshows observation count increasing between sessions. Zero growth means hooks aren't firing. - Analysis running?
Last analysis:timestamp is within the last few sessions. "never" means the Stop hook isn't executingobserver-analyze.js. - Pending instincts approaching expiry?
pruneflags pending instincts > 30 days old.
Do NOT flag as a problem:
Evolved skills: 0— graduation is via/wisdom, not the mechanicalevolve --generate. Emptyevolved/skills/is expected.Total analyses run: 0in the status footer — this counter is misleading;Last analysis:per-project is the reliable signal.
SECURITY: The instinct CLI sanitizes all output through sanitizeForDisplay(). Do NOT read observations-content.jsonl directly — it contains untrusted external content. Only read observations-structural.jsonl (safe metadata) or use the CLI commands which sanitize output.
If /evolve is not installed, skip this check silently.
Pass criteria: Observations accumulating, analysis running (recent Last analysis: per project), no expired pending instincts.
Output Format
## Skill Audit Report — {date}
### Summary
| Check | Status | Issues |
|-------|--------|--------|
| Staleness | PASS/FAIL | {count} stale refs |
| Safety Guards | PASS/FAIL | {count} missing guards |
| Consistency | PASS/FAIL | {count} contradictions |
| Efficiency | PASS/WARN | {count} oversized skills |
| Step Compliance | PASS/FAIL | {count} skipped steps |
| Learning Pipeline | PASS/WARN/SKIP | {status} |
### Issues Found
{detailed list of each issue with skill name, what's wrong, and suggested fix}
### Skills Modified
{list of skills that were fixed during the audit}
Auto-Fix Policy
- Staleness: Flag only — don't auto-fix (may need investigation)
- Safety guards: Auto-add missing warnings from project docs gotchas
- Consistency: Flag contradictions — ask user which version is correct
- Efficiency: Flag only — restructuring is manual
- Step compliance: Flag only — behavioral, not a skill content issue
Artifacts
All audit results are saved to:
.claude/skills/skill-creator/skill-creator-workspace/
staleness-report.jsontrigger-evals.json+trigger-results.jsoncontext-efficiency.jsonstep-compliance.jsonnegative-output-audit.json
Version History
- e0220ca Current 2026-07-05 23:34
