skill-health-check
Skill8 starsChanged 5 days agoMITView on GitHub
Structural lint for skill files: validates YAML frontmatter has required fields, checks line count limits, and enforces coordination metadata (group, order, internal) as errors. Reports missing Failure Modes sections as warnings. Does NOT check runtime behavior (use superpowers-doctor for that).
3 other projects use a version of this.
Adopted by
Most recently taken up by
- sd0xdev/sd0x-dev-flowtheir own version, first seen Oct 8, 2026
- sd0xdev/sd0x-harnesstheir own version, first seen Oct 6, 2026
- u9401066/template-is-all-you-needtheir own version, first seen Mar 6, 2026
Other versions3 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 3
- sd0xdev/sd0x-dev-flow★ 192same name
- sd0xdev/sd0x-harness★ 192same name
- u9401066/template-is-all-you-need★ 3same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository134 other files it gives its agents.
- AGENTS.mdAGENTS.md
- guidance/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- guidance/CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- .cursor/rules/cli-tools.mdcCursor rule
- .cursor/rules/invariants.mdcCursor rule
- .cursor/rules/javascript.mdcCursor rule
- .cursor/rules/security.mdcCursor rule
- .cursor/rules/shell.mdcCursor rule
- blast-radius-checkSkill
- brainstormingSkill
- branch-flow-gateSkill
- branch-sync-gateSkill
- codebase-reconSkill
- codeowners-drift-auditSkill
- code-review-batterySkill
- cognitive-complexity-refactoringSkill
- debateSkill
- debug-conductorSkill
- dispatching-parallel-agentsSkill
- domain-buildSkill
- evidence-adjudicatorSkill
- executing-plansSkill
- external-cli-auditSkill
- feature-developmentSkill
- field-rename-verificationSkill
- finishing-a-development-branchSkill
- git-branch-conventionsSkill
- gitlab-cliSkill
- hotfix-charterSkill
- implementation-trackerSkill
- incident-revert-reviewSkill
- infra-config-investigatorSkill
- investigation-stateSkill
- kernel-splitSkill
- llm-behavior-investigatorSkill
- llm-skill-reviewSkill
- merge-authorization-gateSkill
- micro-harsh-reviewSkill
- output-verificationSkill
- pre-commit-gateSkill
- progressive-code-review-gateSkill
- progressive-harsh-reviewSkill
- providing-code-reviewSkill
- pr-triage-gateSkill
- push-authorization-gateSkill
- receiving-code-reviewSkill
- reproduction-experiment-investigatorSkill
- requesting-code-reviewSkill
- requirements-validation-pmSkill
- requirements-validationSkill
- scope-tripwireSkill
- session-handoffSkill
- skills-hierarchy-tuningSkill
- sp-bughuntSkill
- state-consistency-investigatorSkill
- subagent-driven-developmentSkill
- systematic-debuggingSkill
- test-driven-developmentSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 42
After creating or modifying skills
- Distinctive: line 43
After bulk skill changes (marathons, domain redesigns)
- Very specific: line 44
Before committing any changes under skills/ — catches formatting errors early
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Skill Health Check
Purpose: Cheap structural lint for skill files. Not a runtime diagnostic.
Wrong skill? Runtime skill issues →
superpowers-doctor. Writing new skills →skill-authoring. Skill prose quality →writing-skills.
Announce at start: "I'm running the skill-health-check structural lint."
Companion Skills
- superpowers-doctor: Full runtime diagnostics (heavier than this lint)
- skill-authoring: Writing new skill files
- superpowers-help: Skill discovery (lighter)
- writing-skills: Skill file format reference
- evolution-loop: Self-improvement cycle
When to Use
- After creating or modifying skills
- After bulk skill changes (marathons, domain redesigns)
- Before committing any changes under
skills/— catches formatting errors early
What It Checks
| Check | Severity | What it validates |
| YAML frontmatter | ERROR | name, source, triggers, description fields present |
| Line count | ERROR | No skill.md exceeds 250 lines |
| Reviewer prompt length | ERROR | No reviewers/*.md exceeds 400 lines (dispatched verbatim to sub-agents, so denser than a skill.md — hence a higher ceiling than 250; enforced by tools/harsh-review.sh) |
| Coordination metadata | ERROR | coordination: block present with required keys: group, order, internal |
| Failure modes section | WARN | ## Failure Modes heading present (presence only) |
What it does NOT check: coordination semantic validity (correct group names, valid order numbers), cross-reference accuracy, runtime behavior, install state. Those are superpowers-doctor territory. Structural lint validates that required keys exist; doctor validates they are correct.
Running the Check
# Quick check (skill count + line limits)
bash tools/harsh-review.sh
# Full ecosystem health (checks 1-4, uses Ruby YAML parser)
ruby -ryaml -e '
errors = []; warnings = []
Dir.glob("skills/**/skill.md").each do |path|
content = File.read(path)
parts = content.split("---", 3)
if parts.length < 3
errors << "#{path}: No YAML frontmatter"; next
end
data = YAML.safe_load(parts[1]) rescue (errors << "#{path}: Invalid YAML"; next)
%w[name source triggers description].each do |f|
errors << "#{path}: Missing #{f}" unless data&.key?(f)
end
unless data&.key?("coordination")
errors << "#{path}: Missing coordination block"
else
coord = data["coordination"]
%w[group order internal].each do |k|
errors << "#{path}: coordination missing '#{k}'" unless coord&.key?(k)
end
end
warnings << "#{path}: Missing Failure Modes" unless content.include?("## Failure Modes")
lines = content.count("\n")
errors << "#{path}: #{lines} lines (max 250)" if lines > 250
end
Dir.glob("skills/**/reviewers/*.md").each do |path|
lines = File.read(path).count("\n")
errors << "#{path}: #{lines} lines (max 400)" if lines > 400
end
errors.each { |e| puts "ERROR: #{e}" }
warnings.each { |w| puts "WARN: #{w}" }
puts "\n#{errors.length} errors, #{warnings.length} warnings"
'Failure Modes
| Failure | Fix |
| New skill created without running health check | Run after every skill creation — catches missing fields immediately |
| README count drifted | Update README counts when adding/removing skills |
| Cross-reference points to renamed/deleted skill | Search for old skill name across all skill.md files |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

