home / skills / callstackincubator / agent-skills / validate-skills

validate-skills skill

safe

This skill validates all skills against agentskills.io and Claude Code best practices, ensuring directory-name alignment, proper descriptions, and compliance.

npx playbooks add skill callstackincubator/agent-skills --skill validate-skills

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.8 KB

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

Overview

This skill validates individual skill directories against the agentskills.io specification and Claude Code best practices. It runs a checklist of structural, naming, and content rules and produces a clear pass/fail report for each skill. Use the /validate-skills command to run validation across the skills collection.

How this skill works

The validator locates each skill folder and reads the skill document and manifest to inspect fields like name, description, and optional metadata. It applies spec rules (name format, directory match, description length, optional fields) and best-practice checks (tone, length, link format, redundancy). Results are emitted as a human-readable report listing pass/fail items per skill.

When to use it

Before publishing or sharing new or updated skills
During CI to catch spec or style regressions
When auditing a collection for consistency and quality
Prior to submitting skills to a registry or marketplace
When onboarding contributors to enforce standards

Best practices

Enforce name: 1–64 chars, lowercase alphanumeric and hyphens, no leading/trailing/consecutive hyphens
Keep descriptions concise and in third person; explain what the skill does and when to use it
Limit documentation body length and avoid repeating the short description
Use one-level references only and format links as markdown [text](path)
Validate optional fields (license, metadata, compatibility) when present

Example use cases

Run validation in CI to fail builds when a skill breaks the spec
Audit all skills before a public release to ensure uniform quality
Train contributors by pointing to exact checklist items for fixes
Automate pre-merge checks so maintainers get consistent reports
Generate a remediation list for each skill with explicit pass/fail details

FAQ

What command runs the validator?

Use the /validate-skills command to execute the full validation across all skills.

Which fields are mandatory?

Name and description are required; license, metadata, and compatibility are optional but validated if present.