Index of every page on this site: llms.txt
All skills
callstackincubator avatar

/validate-skills

@59e9d17 official
by Callstack Incubatorcallstackincubator/agent-skills1.7k stars
117
Run it yourself

Validates skills in this repo against agentskills.io spec and Claude Code best practices. Use via /validate-skills command.

Use this Skill: https://skilld.dev/gh/callstackincubator/agent-skills/validate-skills

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈35 tokens for metadata: the name and description. ≈602 when used: this file.

Description uses 1.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈141 characters, or 1.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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

  1. Find all skill directories:

    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

Source: SKILL.md on GitHub

Skill behaviors

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

Third-party checks

No alerts1mo5 checks · Risk SAFE
  • Gen Agent Trust Hub1mo

    The skill is a static documentation file defining rules and procedures for validating other AI agent skills against established guidelines. It contains no executable code, remote script downloads, or data exfiltration vectors, and is safe to use.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: LOW · No issues

  • Runlayer8mo

    1 file scanned · No issues

  • ZeroLeaks6mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at 59e9d17. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated 4 months ago

Capability

metadata
{
  "author": "Callstack",
  "tags": "validation, linting, skill-authoring"
}

Topics

  • validation
  • linting
  • skill-authoring
  • agentskills
  • claude-code
  • spec-compliance

README badge

README badge for callstackincubator/agent-skills/validate-skills

What it does

Validates skill directories against the agentskills.io spec and Claude Code best practices, checking metadata format, description length, and documentation structure. Run via `/validate-skills` command to lint all skills in a `skills/` folder.

Generated from the current SKILL.md.

Frequently asked

What does this skill validate against?
It checks skills against the agentskills.io specification (name format, description length, optional fields) and Claude Code best practices (third-person description, body length under 500 lines, markdown link format, no redundancy).
How do I run the validation?
Use the /validate-skills command in Claude Code. The skill finds all directories in skills/, reads each SKILL.md, and reports pass/fail results for each rule.
Does this check the actual skill implementation?
No. This skill only validates the SKILL.md file metadata and documentation structure, not the bundled scripts or templates.
Can I use this outside of Claude Code?
The skill is designed for the /validate-skills command in Claude Code. Manual validation is possible by following the checklist and bash command provided, but automation requires the skill to be installed.

Generated from the current SKILL.md. These answers refresh after source changes.