Validate Skill Skill | Agent Skills

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

Agent Skills: Validate Skill

Install this agent skill to your local

Skill Files