validate-skills
starsforks
How to install validate-skills?
callstackincubator/agent-skills/validate-skills
$npx -y skills add callstackincubator/agent-skills --skill validate-skillsValidates skills in this repo against agentskills.io spec and Claude Code best practices. Use via /validate-skills command.
SKILL.md
| 1 | # Validate Skills |
| 2 | |
| 3 | Validate all skills in `skills/` against the agentskills.io spec and Claude Code best practices. |
| 4 | |
| 5 | ## Validation Checklist |
| 6 | |
| 7 | For each skill directory, verify: |
| 8 | |
| 9 | ### Spec Compliance (agentskills.io) |
| 10 | |
| 11 | | Check | Rule | |
| 12 | |-------|------| |
| 13 | | `name` format | 1-64 chars, lowercase alphanumeric + hyphens, no leading/trailing/consecutive hyphens | |
| 14 | | `name` matches directory | Directory name must equal `name` field | |
| 15 | | `description` length | 1-1024 characters, non-empty | |
| 16 | | Optional fields valid | `license`, `metadata`, `compatibility` if present | |
| 17 | |
| 18 | ### Best Practices (Claude Code) |
| 19 | |
| 20 | | Check | Rule | |
| 21 | |-------|------| |
| 22 | | Description format | Third person, describes what + when to use | |
| 23 | | Body length | Under 500 lines | |
| 24 | | Loading is one-level deep | `SKILL.md` is the only progressive-disclosure entry point: every reference file must be reachable from `SKILL.md`. References may cross-link each other for navigation (see note below). | |
| 25 | | Links are markdown | Use `[text](path)` not bare filenames | |
| 26 | | No redundancy | Don't repeat description in body | |
| 27 | | Concise | Only add context Claude doesn't already have | |
| 28 | |
| 29 | > **One-level-deep vs. cross-linking.** The one-level-deep rule targets *progressive-disclosure loading chains* — a reference that can only be discovered by loading another reference first (`SKILL.md` → `a.md` → `b.md`, where `b.md` is not linked from `SKILL.md`). That is a defect: it hides content from the loader. |
| 30 | > |
| 31 | > It does **not** forbid *navigational* cross-links. Per [AGENTS.md](../../../AGENTS.md), reference files end with a "Related Skills" footer linking sibling references, and this is required. A cross-link is fine as long as both endpoints are also reachable directly from `SKILL.md`. Only flag a reference that is reachable *exclusively* through another reference. |
| 32 | |
| 33 | ## How to Run |
| 34 | |
| 35 | 1. Find all skill directories: |
| 36 | ```bash |
| 37 | fd -t d -d 1 . skills/ |
| 38 | ``` |
| 39 | |
| 40 | 2. For each skill, read `SKILL.md` and check against the rules above |
| 41 | |
| 42 | 3. Report issues in this format: |
| 43 | ``` |
| 44 | ## Validation Results |
| 45 | |
| 46 | ### skills/example-skill |
| 47 | - [PASS] name format valid |
| 48 | - [FAIL] name "example" doesn't match directory "example-skill" |
| 49 | - [PASS] description length OK (156 chars) |
| 50 | ``` |
| 51 | |
| 52 | ## References |
| 53 | |
| 54 | - [agentskills.io spec](https://agentskills.io/specification) |
| 55 | - [Claude Code best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) |
People who liked this also viewed
6 picksType
- find-skillsHelps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skSkillsJul 2026
- grill-meA relentless interview to sharpen a plan or design.SkillsJul 2026
- vercel-react-best-practicesVercel's official collection of agent skillsSkillsJul 2026
- improve-codebase-architectureScan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.SkillsJul 2026
- setup-matt-pocock-skillsConfigure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.SkillsJul 2026
- triageMove issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.SkillsJul 2026
