ReddRadar
Agent skill
skill-health-check
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.
Install this agent skill to your Project
npx add-skill https://github.com/sd0xdev/sd0x-dev-flow/tree/main/skills/skill-health-check
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-creatorplugin, 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:
| Parameter | Description |
|---|---|
--skills-dir <path> |
Skills directory (default: ./skills) |
--agents-dir <path> |
Agents directory (default: ./agents) |
--json |
Output JSON instead of markdown |
--fix-hint |
Include fix suggestions |
| Exit 0 | All pass |
| Exit 1 | Warnings only (P2) |
| Exit 2 | Errors found (P0/P1) |
Per-skill checks (11 items):
| # | Check | Severity | Criteria |
|---|---|---|---|
| 1 | Frontmatter exists | P0 | name + description required |
| 2 | Routing signature | P1 | Description has at least 2 of 3 routing cues (Use/Avoid/Output); 0 cues = P1, 1 cue = P2 |
| 3 | When NOT section | P1 | Body has "When NOT to Use" heading |
| 4 | Output section | P2 | Body defines expected deliverable |
| 5 | Verification section | P2 | Body has verification checklist |
| 6 | References routing | P2 | Each reference file mentioned in body |
| 7 | Scripts contract | P2 | Each script filename referenced in SKILL.md body |
| 8 | Line count | P2 | Warning >150, flag >250 |
| 9 | Agent entitlement | P2 | Body describes Agent() dispatch but allowed-tools lacks Agent |
| 10 | Task entitlement | P2 | Body describes Task() dispatch but allowed-tools lacks Task |
| 11 | Cross-skill ref path | P1 | Bare ref paths not found locally but existing in another skill → must use @skills/<parent>/ prefix |
Cross-skill checks (3 items):
| # | Check | Severity | Criteria |
|---|---|---|---|
| 12 | Description overlap | P2 | Jaccard similarity >60% flagged |
| 13 | Agent ref validity | P1 | subagent_type references in skills must exist in agents/ |
| 14 | Agent tools syntax | P2 | Agent .md tools field uses canonical format (ToolName or Bash(<prefix>:*)) |
Step 2: Manual Review (when comprehensive audit requested)
Read flagged skills and evaluate:
| Dimension | Question | Rating |
|---|---|---|
| Why > What | Does skill explain underlying principles, not just steps? | ⭐1-5 |
| Scope fitness | Is the skill focused? Could it be split? | ⭐1-5 |
| Progressive loading | Is heavy content in references/, not inline? | ⭐1-5 |
| Routing precision | Would 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
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
sd0xdev/sd0x-dev-flow
runbook
Generate and update feature release runbooks from existing docs and codebase. Use when: creating operational runbook, release handbook, deployment checklist, pre-release preparation. Not for: incident response (v2), code review (use codex-code-review), architecture design (use architecture).
sd0xdev/sd0x-dev-flow
ask
Context-aware Q&A with auto context gathering. Use when: user has a quick question about codebase, git history, rules, docs, or skills during development. Not for: code changes (use feature-dev), code review (use codex-review-fast), deep research (use deep-research), full code trace (use code-explore). Output: structured answer with source attribution.
sd0xdev/sd0x-dev-flow
project-brief
Convert a technical spec into a PM/CTO-readable executive summary. Simplify technical details, focus on business value.
sd0xdev/sd0x-dev-flow
codex-test-gen
Generate unit tests for specified functions using Codex MCP
sd0xdev/sd0x-dev-flow
bug-fix
Bug fix workflow. Use when: fixing bugs, resolving issues, regression fixes. Not for: new features (use feature-dev), understanding code (use code-explore). Output: fix + regression test + review gate.
sd0xdev/sd0x-dev-flow
doc-refactor
Refactor documents — simplify without losing information, visualize flows with sequenceDiagram.
Didn't find tool you were looking for?