| name | check-skill-names |
| description | Verify that skill name fields in SKILL.md frontmatter match their directory names (category-skillname format). Use when (1) before creating a pull request or release to ensure naming consistency, (2) after adding new skills to verify the name field was set correctly, (3) after renaming skill directories to update frontmatter accordingly, (4) as part of comprehensive repository validation alongside check-skill-refs and check-skill-counts, (5) when debugging skill discovery issues that might stem from name mismatches. |
Check Skill Names
Validate that each skill's name field in frontmatter matches its directory name, since Claude Code relies on this alignment to discover and invoke skills correctly—when the frontmatter name diverges from the directory structure, the skill becomes invisible to the system even though the file exists.
Instructions
1. Understand the naming convention. Each skill directory follows the pattern category-skillname where the category groups related skills and makes browsing the filesystem semantically meaningful, while the frontmatter name field must exactly match this directory name to maintain the symmetry that skill discovery depends on.
2. Run the validation script. Execute the check-skill-names script to compare frontmatter names against directory names across all plugins, surfacing both perfect alignment and any divergence where the metadata claims one identity while the filesystem location declares another—this comparison reveals inconsistencies that would otherwise remain hidden until a skill mysteriously fails to load.
3. Interpret mismatches. When a mismatch appears, the pattern is almost always a frontmatter name missing its category prefix—the skill lives in analysis-decompose/ but declares itself as just decompose, creating the naming asymmetry that prevents skill discovery from connecting the file to its intended invocation path.
4. Apply fixes when appropriate. The script includes a --fix flag that automatically updates SKILL.md files to match their directory names, preserving all other frontmatter fields while surgically correcting just the name—this precision makes bulk fixes reliable even across dozens of skills at once.
5. Integrate into validation workflow. Include this check alongside other preflight validations before releases, since naming consistency forms the foundation that other validations build upon—when names align correctly, skill reference checking and count verification can proceed with confidence that the filesystem reflects the intended architecture.
Script Usage
.claude/scripts/check-skill-names.sh --all
.claude/scripts/check-skill-names.sh --plugin thinkies
.claude/scripts/check-skill-names.sh --all --fix
.claude/scripts/check-skill-names.sh --all --json
The script returns exit code 0 when all names match, or exit code 1 when mismatches are found.
Examples
Example 1: All names valid
$ .claude/scripts/check-skill-names.sh --all
Checking skill names across all plugins...
expression (15 ok, 0 mismatch, 0 errors)
software (23 ok, 0 mismatch, 0 errors)
thinkies (52 ok, 0 mismatch, 0 errors)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ All skill names match their directories
Example 2: Mismatches found
$ .claude/scripts/check-skill-names.sh --plugin thinkies
Checking skill names across all plugins...
thinkies (50 ok, 2 mismatch, 0 errors)
✗ analysis-decompose: name: decompose should be: analysis-decompose
✗ creativity-scamper: name: scamper should be: creativity-scamper
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✗ Found 2 mismatched skill name(s)
Run with --fix to automatically update SKILL.md files
In this case, run with --fix to update the frontmatter automatically.
Example 3: Fixing mismatches
$ .claude/scripts/check-skill-names.sh --all --fix
Checking skill names across all plugins...
thinkies (50 ok, 2 mismatch, 0 errors)
✗ analysis-decompose: FIXED: name: decompose should be: analysis-decompose
✗ creativity-scamper: FIXED: name: scamper should be: creativity-scamper
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✗ Found 2 mismatched skill name(s)
Verify the fix by running again without --fix - the output should show all skills as "ok".
