validate-skills

callstackincubator/agent-skills

Validate skills against agentskills.io spec and Claude Code best practices.

What is validate-skills?

Validates all skills in a repository against the agentskills.io specification and Claude Code best practices. Use this when authoring or reviewing skills to ensure they meet naming conventions, description requirements, file structure, and documentation standards.

Checks skill name format (1-64 chars, lowercase alphanumeric + hyphens, no leading/trailing/consecutive hyphens)
Verifies skill name matches its directory name
Validates description length (1-1024 characters, non-empty)
Ensures SKILL.md is the only progressive-disclosure entry point with all references reachable from it
Checks that descriptions use third-person voice and explain what + when to use
Verifies body length stays under 500 lines and uses markdown links

How to install validate-skills

npx skills add https://github.com/callstackincubator/agent-skills --skill validate-skills

Claude Code

Cursor

Windsurf

Cline

How to use validate-skills

1.Run the /validate-skills command in Claude Code
2.The tool will scan all skill directories in skills/
3.For each skill, it checks name format, description length, and file structure
4.Review the validation report for any FAIL items
5.Fix issues according to the agentskills.io spec and best practices rules

Use cases

Good for

Validate a new skill before submitting to a skill repository
Check all skills in a repository for compliance during a review cycle
Ensure skill documentation follows best practices before publishing
Verify skill naming and structure conform to agentskills.io spec
Audit existing skills for documentation quality and accessibility

Who it's for

Skill authors and maintainers
Repository maintainers managing skill collections
Teams establishing skill quality standards
Developers integrating skills into agent systems

validate-skills FAQ

What is the one-level-deep loading rule?

SKILL.md must be the only entry point for discovering content. All reference files must be reachable directly from SKILL.md. Cross-links between references are allowed for navigation as long as both endpoints are also linked from SKILL.md.

What name format is required for skills?

Names must be 1-64 characters, lowercase alphanumeric with hyphens allowed, and cannot have leading, trailing, or consecutive hyphens.

How long should a skill description be?

Descriptions must be between 1-1024 characters and non-empty. They should use third-person voice and explain what the skill does and when to use it.

What is the maximum body length for a skill?

Skill documentation body should stay under 500 lines to keep content concise and avoid redundancy with the description.

Where can I find the full specification?

Refer to the agentskills.io spec at https://agentskills.io/specification and Claude Code best practices at https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices.

Full instructions (SKILL.md)

Source of truth, from callstackincubator/agent-skills.

name: validate-skills description: Validates skills in this repo against agentskills.io spec and Claude Code best practices. Use via /validate-skills command. license: MIT metadata: author: Callstack tags: validation, linting, skill-authoring

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
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).
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

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.

It does not forbid navigational cross-links. Per 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.

How to Run

Find all skill directories:
```
fd -t d -d 1 . skills/
```
For each skill, read SKILL.md and check against the rules above

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)