agentleFS
sd0xdevsd0xdev/sd0x-dev-flow/skills/skill-health-check/SKILL.md

skill-health-check

Skill192 starsChanged 42 days agoMITView on GitHub

Validate skill quality against routing, progressive loading, and verification criteria. Use when: auditing skills, checking skill health, reviewing skill design. Not for: code review (use codex-code-review) or doc review (use doc-review). Output: health report with per-skill ratings + Gate.

3 other projects use a version of this.

Adopted by

Most recently taken up by

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
  1. Very specific:

    Document review (use /codex-review-doc)

    line 17
  2. Distinctive:

    Read flagged skills and evaluate:

    line 75
  3. Distinctive:

    Only run Step 2 when user explicitly requests deep audit.

    line 84

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Skill Health Check

Trigger

  • Keywords: skill health, skill audit, skill lint, check skills, skill quality, validate skills

When NOT to Use

  • Code review (use /codex-review-fast)
  • Document review (use /codex-review-doc)
  • Creating new skills (use skill-creator plugin, external)
  • .claude directory structure check (use /claude-health)

Core Principle

Skills are on-demand context packages. Their value comes from routing precision (right skill triggers at right time) and context efficiency (minimum tokens for maximum capability). A poorly routed skill wastes context on every mismatch; a well-routed skill transforms a generalist into a specialist at exactly the right moment.

Workflow

Run automated lint → Review manual dimensions → Produce integrated report → Gate

Step 1: Automated Lint

node skills/skill-health-check/scripts/skill-lint.js --fix-hint

Script I/O contract:

ParameterDescription
--skills-dir <path>Skills directory (default: ./skills)
--agents-dir <path>Agents directory (default: ./agents)
--jsonOutput JSON instead of markdown
--fix-hintInclude fix suggestions
Exit 0All pass
Exit 1Warnings only (P2)
Exit 2Errors found (P0/P1)

Per-skill checks (11 items):

#CheckSeverityCriteria
1Frontmatter existsP0name + description required
2Routing signatureP1Description has at least 2 of 3 routing cues (Use/Avoid/Output); 0 cues = P1, 1 cue = P2
3When NOT sectionP1Body has "When NOT to Use" heading
4Output sectionP2Body defines expected deliverable
5Verification sectionP2Body has verification checklist
6References routingP2Each reference file mentioned in body
7Scripts contractP2Each script filename referenced in SKILL.md body
8Line countP2Warning >150, flag >250
9Agent entitlementP2Body describes Agent() dispatch but allowed-tools lacks Agent
10Task entitlementP2Body describes Task() dispatch but allowed-tools lacks Task
11Cross-skill ref pathP1Bare ref paths not found locally but existing in another skill → must use @skills/<parent>/ prefix

Cross-skill checks (3 items):

#CheckSeverityCriteria
12Description overlapP2Jaccard similarity >60% flagged
13Agent ref validityP1subagent_type references in skills must exist in agents/
14Agent tools syntaxP2Agent .md tools field uses canonical format (ToolName or Bash(<prefix>:*))

Step 2: Manual Review (when comprehensive audit requested)

Read flagged skills and evaluate:

DimensionQuestionRating
Why > WhatDoes skill explain underlying principles, not just steps?⭐1-5
Scope fitnessIs the skill focused? Could it be split?⭐1-5
Progressive loadingIs heavy content in references/, not inline?⭐1-5
Routing precisionWould a user's request unambiguously trigger this skill?⭐1-5

Only run Step 2 when user explicitly requests deep audit. Default: Step 1 only.

Output

# Skill Health Check Report

## Summary

| Metric | Value |
|--------|-------|
| Skills scanned | N |
| Checks passed | N |
| P0 (Must Fix) | N |
| P1 (Should Fix) | N |
| P2 (Suggestion) | N |

## Per-Skill Results

| Skill | Routing | When-NOT | Output | Verification | Refs | AgEnt | TskEnt | Lines | Status |
|-------|---------|----------|--------|--------------|------|-------|--------|-------|--------|
| name  | ✅/🟡/⚪ | ...    | ...    | ...          | ...  | ✅/⚪ | ✅/⚪  | N     | ✅/🟡/⚪/🔴 |

## P0 (Must Fix)
- **skill-name**: Issue → Fix recommendation

## P1 (Should Fix)
- **skill-name**: Issue → Fix recommendation

## P2 (Suggestion)
- **skill-name**: Issue → Fix recommendation

## Gate: ✅ All Pass / ⛔ N issues need fixing

Verification

  • Automated lint executed (exit code checked)
  • All P0/P1 findings have fix recommendations
  • Per-skill table includes all scanned skills
  • Gate sentinel present for hook parsing

References

  • references/routing-signature-guide.md — How to write effective routing signatures (read when fixing P1 routing issues)

Examples

Input: /skill-health-check
Action: Run skill-lint.js → Output markdown report + Gate

Input: /skill-health-check --deep
Action: Run skill-lint.js → Manual review of flagged skills → Integrated report

Input: Are my skills well-designed?
Action: Trigger health check → Report + improvement suggestions

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.