Validate Skill

Purpose

This skill validates skill directories against the AgentSkills specification. Use it to ensure your skills have proper frontmatter, required fields, and follow naming conventions.

Use when:

• Creating new skills in any agent's skills directory (.claude/skills/ , .cursor/skills/ , etc.)

• Reviewing PRs that modify skills

• Validating skill structure before publishing

Scripts

validate-skill.ts

Validate one or more skill directories.

bunx @plaited/development-skills validate-skill [paths...]

Arguments:

• paths : Paths to validate (defaults to current agent's skills directory)

Options:

• --json : Output results as JSON

Examples:

Validate skills in current directory's .claude/skills/

bunx @plaited/development-skills validate-skill .claude/skills

Validate Cursor skills

bunx @plaited/development-skills validate-skill .cursor/skills

Validate a specific skill

bunx @plaited/development-skills validate-skill .claude/skills/typescript-lsp

Validate multiple paths with JSON output

bunx @plaited/development-skills validate-skill .claude/skills .cursor/skills --json

Validation Rules

Required Fields

• name : Skill name (lowercase, alphanumeric with hyphens)

• description : Brief description of the skill

Naming Conventions

• Name must be lowercase

• Only alphanumeric characters and hyphens allowed

• Cannot start or end with hyphen

• Cannot contain consecutive hyphens

• Maximum 64 characters

• Directory name must match skill name

Optional Fields

• license : License identifier

• compatibility : Runtime requirements

• allowed-tools : Comma-separated list of allowed tools

• metadata : Key-value pairs for additional metadata

Output Format

Human-Readable (default)

✓ .claude/skills/typescript-lsp ✓ .cursor/skills/my-skill ✗ .claude/skills/invalid-skill ERROR: Missing required field in frontmatter: 'description'

2/3 skills valid

JSON (--json)

[ { "valid": true, "path": ".cursor/skills/my-skill", "errors": [], "warnings": [], "properties": { "name": "my-skill", "description": "..." } } ]

Related Skills

• typescript-lsp - Example of a well-structured skill with scripts

• code-documentation - TSDoc standards for TypeScript/JavaScript code