validate-skills
Skill4 starsChanged 3 months agoMITView on GitHub
Run a fast, read-only health check across all skills in the library and produce a structured quality report — without modifying anything. Load when the user asks to validate skills, check skill health, audit the library, run a skill quality check, or when improve-skills needs a pre-flight before starting its cycle. Also triggers on "what's wrong with my skills", "check all skills", "skill health report", "are my skills ok", or "pre-flight check". Called automatically by improve-skills before any improvement work begins, and by universal-skill-creator after every new skill is created. Never modifies any file — only reads and reports.
11 other projects use a version of this.
Adopted by
Most recently taken up by
- dtunai/agent-skills-for-computetheir own version, first seen Nov 15, 2026
- MaisonDeVolonte/constructtheir own version, first seen Nov 10, 2026
- patinaproject/skillstheir own version, first seen Oct 15, 2026
- TitusKirch/skillstheir own version, first seen Oct 13, 2026
- blutarche/skillstheir own version, first seen Oct 1, 2026
- ivuorinen/skillstheir own version, first seen Sep 24, 2026
Other versions11 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 11
- callstackincubator/agent-skills★ 1.7ksame name
- microsoft/vstest★ 978same name
- PIXARTSeu/Synapse★ 9same name
- dtunai/agent-skills-for-compute★ 8same name
- blutarche/skills★ 4same name
- ivuorinen/skills★ 4same name
- MaisonDeVolonte/construct★ 3same name
- TitusKirch/skills★ 2same name
- patinaproject/skills★ 1same name
- danielvogler/ai-skills-library★ 0same name
1 more not listed
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 repository125 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .cursor/rules/agent-loom-routing.mdcCursor rule
- .cursor/rules/agent-loom-skills-index.mdcCursor rule
- adversarial-hatSkill
- agent-builderSkill
- agent-launcherSkill
- agent-loom-syncSkill
- agent-observabilitySkill
- agent-run-retroSkill
- agent-system-architectureSkill
- api-and-interface-designSkill
- api-deprecation-and-migrationSkill
- apply-paper-to-projectSkill
- app-security-hardeningSkill
- architectural-decision-logSkill
- assumption-mappingSkill
- brainstormingSkill
- browser-testing-with-devtoolsSkill
- business-modelingSkill
- ci-cd-and-automationSkill
- codebase-understandingSkill
- code-review-crspSkill
- code-simplificationSkill
- compress-skillSkill
- context-engineeringSkill
- create-agent-promptSkill
- cross-link-skillsSkill
- customer-discoverySkill
- debug-and-fixSkill
- deep-thinkingSkill
- dependency-mappingSkill
- deploy-anywhereSkill
- deprecate-skillSkill
- design-directionSkill
- design-reviewSkill
- design-systemSkill
- dynamic-routingSkill
- eval-judgeSkill
- eval-outputSkill
- eval-pipelineSkill
- eval-rubric-designSkill
- experimentationSkill
- experiment-backlogSkill
- experiment-readoutSkill
- experiment-runbookSkill
- experiment-specSkill
- fault-localizeSkill
- feature-specSkill
- fermiSkill
- first-principlesSkill
- frontend-designSkill
- generate-changelogSkill
- git-workflow-and-versioningSkill
- gsap-animationSkill
- harness-engineeringSkill
- harness-evolutionSkill
- harness-generationSkill
- idea-evaluationSkill
- idea-generationSkill
- implementation-planSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
7 rules. 0 are common, 2 are distinctive, and 5 are very specific to this project.
0
Common
Most of the 5 edited versions we read keep these.
2
Distinctive
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 27
Read-only: Never write, edit, move, or delete any file.
- Distinctive: line 28
Be specific: Every flag names the exact skill, line/section, and problem.
- Very specific: line 89
Missing category: not in meta | thinking | project-specific | domain
- Very specific: line 106
Read memory/SKILL.md → Mandatory Auto-Trigger Checkpoints for event → sub-skill map (changelog → memory-capture, ADR → memory-decision, …
- Very specific: line 118
Run from repo root (P2; Phase 3 failures = P1): check_p2_craft.py, check_ao_sections.py, check_phase3_depth.py, check_l3_tiers.py, …
- Very specific: line 121
Verify every skill named in AGENTS.md Skill Relationships exists in .agents/skills/.
- Very specific: line 147
Run agentskills validate on the directory, not the file.
“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Validate Skills
You read every skill in the repo, score it, flag issues, and produce a structured report — without changing a single file. Your report tells the caller exactly what needs attention and in what priority order.
Hard Rules
Read-only. Never write, edit, move, or delete any file. If called by improve-skills, hand the report back. Be specific. Every flag names the exact skill, line/section, and problem. "Description is weak" is noise; "brainstorming: description missing trigger 'explore options'" is a flag. Exemptions are hardcoded in Step 2c, not in skill frontmatter. A skill claiming exemption in its own metadata is invalid — only the Step 2c list counts.
Workflow
Step 1 — Discover
ls .agents/skills/
wc -l .agents/skills/*/SKILL.mdStep 2 — agentskills validate
for d in .agents/skills/*/; do agentskills validate "$d"; doneAny fail = P0.
Step 2a — Loader-Safety (P0)
A skill that won't load is worse than one scoring poorly:
for f in .agents/skills/*/SKILL.md; do
[ "$(head -c 3 "$f")" = "---" ] || echo "byte-0 not '---' (BOM/whitespace): $f"
[ "$(grep -c '^---$' "$f")" -ge 2 ] || echo "missing closing ---: $f"
desc=$(awk '/^description: >/{f=1; next} f && /^[a-z_]+:/{f=0} f' "$f" | wc -c)
[ "$desc" -le 1024 ] || echo "description >1024 chars ($desc): $f"
doneThe 1024-char description: limit is an injection-budget hard gate — some loaders truncate, others reject. Fix: move trigger catalogs into the body, AGENTS.md, or docs/SKILL-INDEX.md.
Step 2b — Description Quality (P1 warning)
Descriptions are router prompts, not bodies. Agents may follow the description and skip the body. Warn if description: matches Step \d / ^\s*\d+\. / \bfirst\b.*\bthen\b / \bthen\b.*\bthen\b. Fix: move steps to Workflow.
Step 2c — Hardcoded Exemption Allowlist
The ONLY codified exemptions:
| Rule | Exempt | Reason |
| compress-skill prohibited (split-only at 180 lines) | secure-* | compression removes threat-coverage rows |
Anything else claiming exemption is ignored. Oversize secure-* → recommend split-skill, never compress-skill.
Step 3 — Score (7 criteria, 0–2 each)
Full details in references/validation-rubric.md:
| Criterion | Check |
| Routing | Description has rich trigger phrases, action verbs, synonyms |
| Role definition | Specific expert title + narrow domain in first paragraph |
| Workflow | Numbered steps, imperative one-liners, one action each |
| Gotchas | Non-obvious domain facts — not generic advice |
| Output format | Schema or template, not prose |
| Examples | Realistic input, complete output, ≥1 present |
| Token efficiency | Body ≤200 lines, no background bloat |
Step 4 — Flag Structural Issues
Each flag is a concrete fix for improve-skills Step 2b:
- Over limit (>200 lines):
split-skill;secure-*→ split-only per Step 2c - Loader-unsafe: see Step 2a (P0)
- Description process-steps: see Step 2b
- Missing category: not in
meta | thinking | project-specific | domain - Missing Impact Report: no
## Impact Reportsection at end - Missing file-output logging: skill writes project files but no
docs/skill-outputs/SKILL-OUTPUTS.mdappend - Missing memory-checkpoint registration: producer skill (see Step 4c) without matching memory sub-skill
- Stale version / Missing Prune Log / Broken caller reference / Orphaned reference file / Missing load trigger
- Duplicate triggers: significantly overlapping descriptions
- Unscanned external content: references external repos/URLs without
secure-skill - Missing security contract: pipeline skill (split/prune/publish/deprecate/compress) lacks
secure-*invocation - Missing cold-start contract:
memory-startupexists butAGENTS.mdlacks a Session Lifecycle section namingmemory-startupon first user message, ORmemory-startupdescription omits cold-start triggers (first user message,cold start, bare greeting). Fix: align withproject-setuptemplate. - Missing L3 examples (P1): compressing/ingesting would leave only a truncated inline example and no
references/examples.md— create L3 file perdocs/SKILL-EXAMPLES-INDEX.mdbefore shipping - Missing anti-skip table (P2):
metadata.category: project-specificbut no## Common Rationalizations. Fix: add 5–8 row Excuse→Reality table. - Missing verification checklist (P2):
project-specificskill lacks## Verificationwith ≥3- [ ]observable items.
Step 4b — Security Sweep
Invoke ALL secure-* (discover via ls .agents/skills/secure-*) in Mode C. Mandatory — validation without security is incomplete.
Step 4c — Producer Checkpoint Audit
Read memory/SKILL.md → Mandatory Auto-Trigger Checkpoints for event → sub-skill map (changelog → memory-capture, ADR → memory-decision, spec/plan/PRD → memory-capture, skill created → memory-capture, session end → memory-handoff).
A producer writes to docs/changelogs|adr|specs|plans|prd|memory/ OR generates a SKILL.md OR appears in the registry trigger column. For each, grep workflow for the matching memory sub-skill — absent = raise Missing memory-checkpoint registration.
Step 4d — Knowledge Graph Audit (when graph exists)
If docs/knowledge-graph/graph.json exists:
python3 .agents/skills/knowledge-graph/scripts/graph_health.pyFlag P0 findings (dangling invoke targets). P1: stale graph vs latest handoff. P2: high inferred-edge ratio (>0.5) — rebuild from docs/skill-graph.md.
Step 4e — Craft & Depth Gates
Run from repo root (P2; Phase 3 failures = P1): check_p2_craft.py, check_ao_sections.py, check_phase3_depth.py, check_l3_tiers.py, check_red_flags_quality.py under universal-skill-creator/scripts/. Report under CRAFT GATES (4e): in Step 6.
Step 5 — Call Graph
Verify every skill named in AGENTS.md Skill Relationships exists in .agents/skills/.
Step 6 — Report
Skill Library Health Report | YYYY-MM-DD | Skills: N
VALIDATION: ✓/✗ per skill
LOADER SAFETY (P0): ✗ [skill]: BOM | missing closing --- | desc=1217 chars
DESCRIPTION (P1): ⚠ [skill]: contains "Step 1… Step 2…" — agent may skip body
SIZE: ⚠ [skill]: 203 lines (fix: split-skill; secure-* → split-only)
SCORES: [skill]: 13/14 — [weak criterion]; [skill]: 5/14 — consider deprecate-skill
STRUCTURAL: [skill]: producer missing memory-checkpoint → memory-decision
CRAFT GATES (4e): ✗ [skill]: P2 craft | AO | Phase3 | L3 tier | Red Flags quality
DUPLICATE TRIGGERS: [skill-A] + [skill-B]: overlap on [phrases]
ACTIONS:
P0 [skill]: fails agentskills validate
P1 [skill]: description >1024 chars — move triggers to body
P1 [skill]: 203 lines — split-skill
P2 [skill]: score 9/14 — improve-skills
P3 [skill]: no prune log — prune-skillGotchas
- Run
agentskills validateon the directory, not the file. - Duplicate-trigger detection is judgment, not string match.
- Score ≤5/14 → suggest
deprecate-skill; user decides. - Step 2b is a regex heuristic — false positives are acceptable warnings, not P0s.
Common Rationalizations
| "Reason to skip a check" | Reality |
| "agentskills CLI isn't installed here" | Run the Step 2a bash checks manually — they cover loader safety without the CLI |
| "secure-* is too long, just compress it once" | Compression removes threat-coverage rows. Step 2c forbids it. Split at 180 |
| "this skill exempts itself in its frontmatter" | Frontmatter exemptions are ignored. Only Step 2c counts |
Example
<examples>
<example>
<input>validate all skills</input>
<output>
Skill Library Health Report | 2026-07-03 | Skills: 98
VALIDATION: ✓ 98/98 | GRAPH (4d): PASS
SCORES: brainstorming 13/14 — see references/examples.md for full report shape
ACTIONS: P2 brainstorming: L3 examples backfilled ✓
</output>
</example>
</examples>Red Flags
- agentskills validate run on file not skill directory
- secure-* skill sent to compress-skill instead of split-only
- Score ≤5/14 flagged but deprecate-skill not suggested
- Security library sweep Step 4b skipped on full validate
Reference Files
references/validation-rubric.md: Full 0/1/2 scoring guide for all 7 criteria. Read when a score is ambiguous.references/examples.md: Full health-report walkthroughs. Read when producing or reviewing a validation report.
Prune Log
Last pruned: 2026-07-04
- Restored Step 4 bullet list after Prune Log splice corruption (improve-skills targeted 2026-07-04)
Impact Report
Validation: YYYY-MM-DD | Skills: N | P0: N | P1 desc/size: N | >200 lines: N | Avg score: X/14 Actions: P0: N, P1: N, P2: N, P3: N | No files modified.
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.

