validate-skills

★ 1,500

by callstackincubator · part of callstackincubator/agent-skills

Validates skills against agentskills.io spec and Claude Code best practices. Checks skill metadata compliance including name format, description length, and optional fields like license and compatibility Enforces Claude Code best practices: third-person descriptions, body length limits, single-level references, and markdown link formatting Provides structured validation reports flagging spec violations and authoring guideline deviations Designed for use via /validate-skills command within a...

🔥🔥🔥✓ VerifiedFreeQuick setup

#git

🧩 One of 7 skills in the callstackincubator/agent-skills package — works on its own, and pairs well with its siblings.

Inspect the full instructions your agent will receiveExpand

This is the exact playbook injected into your agent when the skill activates — shown here so you can audit it before installing. You don't need to read it to use the skill.

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:
Copy & paste — that's it
```
fd -t d -d 1 . skills/
```
For each skill, read SKILL.md and check against the rules above

Report issues in this format:

Copy & paste — that's it