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.
Installation
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
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
Read registry.yaml — extract all name: entries into a list
Glob disk — scan ~/site/skills/claude-skills/skills/*/SKILL.md, extract folder names
List symlinks — ls -la ~/.claude/skills/ to get all symlink entries (exclude INDEX.md, learnings.md, non-directory items)
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/:
Check if symlink target exists (not broken)
Check if the skill name appears in registry.yaml
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
