| name | check-skill-counts |
| description | Verify that README skill counts match the actual number of SKILL.md files in the filesystem. Use when (1) before creating a pull request or release to ensure documentation accuracy, (2) after adding or removing skills from any plugin, (3) repository health verification or documentation consistency checks are requested, (4) during README updates to confirm new numbers are correct, (5) as part of comprehensive validation alongside check-versions and check-changelogs, (6) when marketplace listing seems inconsistent with actual plugin contents. |
Check Skill Counts
Verify that skill counts documented in README files match the actual number of skills present in each plugin's directory structure, ensuring documentation accuracy as the codebase evolves and maintaining trust that README numbers reflect filesystem reality.
Instructions
1. Understand the validation target. README files make claims about how many skills each plugin contains, while the filesystem holds the ground truth through the actual SKILL.md files present in each plugin's skills/ directory—alignment between documentation claim and filesystem reality signals maintenance quality and gives users accurate expectations of plugin capabilities.
2. Establish filesystem ground truth. Execute the count-skills script to enumerate every SKILL.md file in each plugin's directory structure, producing authoritative counts that represent what the codebase actually delivers rather than what documentation claims it contains.
3. Extract documentation claims. Read each plugin's README.md to find skill count assertions, searching for patterns like "X skills across Y categories" in introductory paragraphs, feature lists, or capability descriptions—documentation authors express counts in varied formats, so this detective work reveals what promises were made to users that can now be tested against filesystem reality.
4. Surface discrepancies with clarity. When documentation claims diverge from filesystem counts, present both numbers side by side so the gap becomes immediately visible—this juxtaposition transforms abstract mismatch into concrete correction target, showing exactly what needs to change rather than requiring investigation to understand the problem.
5. Provide precise update guidance. Locate the exact README lines containing outdated counts and propose replacement text with filesystem-verified numbers—precision in identifying where to edit and what to change turns validation results into actionable corrections, including category-level subcounts when README structure breaks skills into taxonomic groupings.
Script Usage
.claude/scripts/count-skills.sh --plugin thinkies
.claude/scripts/count-skills.sh --all
.claude/scripts/count-skills.sh --all --json
The script returns the number of SKILL.md files found in each plugin's skills directory.
Examples
Example 1: Checking a specific plugin
$ .claude/scripts/count-skills.sh --plugin thinkies
51
Read the thinkies README to verify it claims 51 skills. If the README says "51 cognitive reasoning skills", it's correct. If it says "47 skills", report the mismatch and suggest updating the README.
Example 2: Checking all plugins
$ .claude/scripts/count-skills.sh --all
thinkies: 51 skills
software: 18 skills
expression: 5 skills
---
Total: 74 skills
Check each plugin's README:
- If thinkies README claims 51 skills: ✅ correct
- If software README claims 17 skills: ❌ needs update to 18
- If expression README is missing skill count: ❌ needs count added
Example 3: Using JSON output for validation
$ .claude/scripts/count-skills.sh --all --json
{
"thinkies": 51,
"software": 18,
"expression": 5
}
This format is useful for programmatically comparing counts against README content or integrating with other validation scripts.
Example 4: Comprehensive README verification
When the software plugin README claims "17 code-specific reasoning skills" but the filesystem has 18:
1. Report the discrepancy:
- README claim: 17 skills
- Actual count: 18 skills
- Difference: +1 skill
2. Identify recently added skills by checking git history:
git log --oneline --name-only plugins/software/skills/ | head -20
3. Determine which skill was added but not documented in the README.
4. Suggest the README update:
- Change "17 code-specific reasoning skills" to "18 code-specific reasoning skills"
- If the README breaks down skills by category, verify those subcounts also need updating
