Validate Skills
Lint every skill folder in a repo against agentskills.io and Claude Code authoring rules before you publish or share a skill pack.
Overview
validate-skills is an agent skill most often used in Build (also Ship review) that audits SKILL.md files in a repo against agentskills.io and Claude Code skill-authoring rules.
Install
npx skills add https://github.com/callstackincubator/agent-skills --skill validate-skillsWhat is this skill?
- Checks agentskills.io spec: name format, directory match, description length, optional metadata fields
- Enforces Claude Code best practices: third-person description, under-500-line body, one-level references, markdown links
- Structured PASS/FAIL report per skill directory for `/validate-skills` workflows
- Covers redundancy, concision, and no nested reference chains in SKILL.md bodies
- Validation checklist covers agentskills.io name rules (1–64 chars) and SKILL.md body under 500 lines
Adoption & trust: 3.8k installs on skills.sh; 1.4k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are shipping agent skills but have no automated way to catch spec drift, bad names, or bloated SKILL.md bodies before others install them.
Who is it for?
Maintainers of a multi-skill repo who want a consistent lint pass via `/validate-skills` before merge or release.
Skip if: Runtime security scanning of third-party skills you did not author—review the Security Audits panel on each Prism listing instead of assuming this skill substitutes for supply-chain review.
When should I use this skill?
Validates skills in this repo against agentskills.io spec and Claude Code best practices; use via /validate-skills command.
What do I get? / Deliverables
You get a structured validation report per skill directory so you can fix spec and best-practice violations before commit or publish.
- Per-skill validation report with PASS/FAIL checks
- Actionable issue list for spec and best-practice fixes
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Skill packages are built and maintained in the agent-tooling lane; validation is the quality gate before those skills ship to teammates or a marketplace. Runs over `skills/` directories and SKILL.md frontmatter—the same artifacts solo builders curate when growing a personal or team skill library.
Where it fits
After drafting a new SKILL.md, run validation before committing so name and directory stay aligned.
Gate a PR that touches ten skills with a single PASS/FAIL report reviewers can scan.
Re-lint the skill tree when agentskills.io rules change so old packages do not silently violate the spec.
How it compares
A repo-local SKILL.md linter for skill authors, not a generic markdown or ESLint pass on application code.
Common Questions / FAQ
Who is validate-skills for?
Solo and indie builders, and small teams, who author multiple Claude Code–style skills in one repository and need spec-compliant SKILL.md files before sharing or listing them.
When should I use validate-skills?
Use it in Build when adding or editing skills under `skills/`, again in Ship before a release or PR that touches skill metadata, and anytime you rename a skill folder or rewrite descriptions for a catalog.
Is validate-skills safe to install?
It is designed to read skill directories and report issues; confirm allowed tools match your policy and review the Security Audits panel on this Prism page before installing from an unfamiliar source.
SKILL.md
READMESKILL.md - Validate Skills
# Validate Skills Validate all skills in `skills/` against the agentskills.io spec and Claude Code best practices. ## Validation Checklist For each skill directory, verify: ### Spec Compliance (agentskills.io) | Check | Rule | |-------|------| | `name` format | 1-64 chars, lowercase alphanumeric + hyphens, no leading/trailing/consecutive hyphens | | `name` matches directory | Directory name must equal `name` field | | `description` length | 1-1024 characters, non-empty | | Optional fields valid | `license`, `metadata`, `compatibility` if present | ### Best Practices (Claude Code) | Check | Rule | |-------|------| | Description format | Third person, describes what + when to use | | Body length | Under 500 lines | | References one-level deep | No nested reference chains | | Links are markdown | Use `[text](path)` not bare filenames | | No redundancy | Don't repeat description in body | | Concise | Only add context Claude doesn't already have | ## How to Run 1. Find all skill directories: ```bash fd -t d -d 1 . skills/ ``` 2. For each skill, read `SKILL.md` and check against the rules above 3. Report issues in this format: ``` ## Validation Results ### skills/example-skill - [PASS] name format valid - [FAIL] name "example" doesn't match directory "example-skill" - [PASS] description length OK (156 chars) ``` ## References - [agentskills.io spec](https://agentskills.io/specification) - [Claude Code best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)