skills-audit

name	skills-audit
description	Comprehensive health check of Claude Code skill ecosystem — cross-check registry.yaml, disk, symlinks, INDEX.md, and frontmatter validation. Use after skill restructuring or periodically.
version	1.0.0
user-invocable	true
model	sonnet
tools	["Read","Glob","Grep","Bash"]

Skills Audit

Automated health check that cross-references all skill data sources and reports inconsistencies.

Data Sources

Source	Path	Role
Registry	~/site/skills/claude-skills/registry.yaml	Source of truth for skill definitions
Disk	~/site/skills/claude-skills/skills/*/SKILL.md	Actual skill files
Symlinks	~/.claude/skills/	Installed skills (symlinks to disk)
INDEX	~/.claude/skills/INDEX.md	Human-readable skill catalog

Process

Phase 1: Collect Inventory

1. Read registry.yaml — extract all name: entries into a list
2. Glob disk — scan ~/site/skills/claude-skills/skills/*/SKILL.md, extract folder names
3. List symlinks — ls -la ~/.claude/skills/ to get all symlink entries (exclude INDEX.md, learnings.md, non-directory items)
4. Read INDEX.md — extract all skill names listed

Phase 2: Registry vs Disk Consistency

Compare registry names against disk folder names:

• MISSING from registry: folder exists on disk but no matching entry in registry.yaml
• MISSING from disk: entry in registry.yaml but no folder on disk

Phase 3: Symlink Health

For each symlink in ~/.claude/skills/:

1. Check if symlink target exists (not broken)
2. Check if the skill name appears in registry.yaml
3. Reverse check: skills in registry but not installed as symlinks

Report:

• BROKEN: symlink target does not exist
• NOT IN REGISTRY: installed but not in registry.yaml
• NOT INSTALLED: in registry but no symlink

Phase 4: Frontmatter Validation

For each SKILL.md on disk, parse YAML frontmatter and check:

Field	Rule
name	Required. Must be kebab-case. Must match folder name
description	Required. Must be < 1024 chars. No XML angle brackets (<, >). No "claude" or "anthropic" in name field
version	Required. Must exist
user-invocable	Should exist (warn if missing)

Additional checks:

• Chinese in prompt body: Scan content below frontmatter for CJK characters (U+4E00-U+9FFF). Flag if found — skill prompts should be English per rules
• File size: Warn if SKILL.md exceeds 500 lines

Phase 5: INDEX.md Accuracy

Cross-reference INDEX.md entries against installed symlinks:

• Missing from INDEX: skill is installed but not listed in INDEX.md
• Stale in INDEX: skill listed in INDEX but not installed

Phase 6: Generate Report

Output the structured report in this format:

## Skills Audit Report

**Date**: YYYY-MM-DD
**Skills scanned**: N

### Registry Consistency
- OK: X skills consistent
- MISSING from registry: [list or "none"]
- MISSING from disk: [list or "none"]

### Symlink Health
- OK: X symlinks valid
- BROKEN: [list or "none"]
- NOT IN REGISTRY: [list or "none"]
- NOT INSTALLED: [list or "none"]

### Frontmatter Issues
- [skill-name]: [issue description]
- [skill-name]: [issue description]
- (or "All frontmatter valid")

### INDEX.md Gaps
- Missing from INDEX: [list or "none"]
- Stale in INDEX: [list or "none"]

### Summary
Total: X skills on disk, Y in registry, Z installed
Issues found: N

Boundaries

• Read-only: This skill does NOT fix issues, only reports them
• No auto-commit: Does not create or modify any files
• Scope: Only audits ~/site/skills/claude-skills/ and ~/.claude/skills/
• If the user asks to fix issues after seeing the report, suggest running skm sync or manual fixes as appropriate

Quick Reference: Common Fixes

Issue	Fix
Missing from registry	Add entry to registry.yaml, run skm sync
Missing from disk	Remove stale entry from registry.yaml
Broken symlink	skm uninstall <name> && skm install <name>
Not installed	skm install <name>
Missing from INDEX	Run skm sync to regenerate
Chinese in body	Rewrite prompt content in English
Missing frontmatter field	Edit SKILL.md to add the field