validate

Validate Plugin

Comprehensive validation of plugin structure, configuration, and components.

Prerequisites

• Must be run from a plugin root directory (containing .claude-plugin/plugin.json)

Instructions

What This Command Does

Performs a thorough validation of the plugin:

1. Structure validation: Check directories and files exist
2. Manifest validation: Verify plugin.json is valid and complete
3. Component validation: Check commands, agents, skills, hooks
4. Path validation: Ensure all paths are relative and resolve correctly
5. Naming validation: Verify kebab-case conventions
6. Common issues: Flag typical mistakes

Validation Steps

1. Check Core Structure

Verify these exist:

□ .claude-plugin/plugin.json
□ At least one component directory (commands/, agents/, skills/, or hooks/)

2. Validate plugin.json

Read and check:

• Valid JSON: Can parse without errors
• Required fields present: name, version, description
• Name format: kebab-case (lowercase with hyphens)
• Version format: Valid SemVer (e.g., "1.0.0")
• Paths are relative: Start with ./ not /
• Author format: If present, valid object or string

Example valid structure:

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "What the plugin does",
  "author": {
    "name": "Your Name"
  },
  "license": "MIT",
  "keywords": ["keyword1"],
  "commands": "./commands/",
  "agents": "./agents/",
  "hooks": "./hooks/hooks.json"
}

3. Validate Component Paths

For each path in plugin.json:

• commands: Check directory exists, contains .md files
• agents: Check directory exists, contains .md files
• skills: Check directory exists, contains skill folders with SKILL.md
• hooks: Check file exists and is valid JSON

4. Validate Commands

For each file in commands/:

• File extension: Must be .md
• Frontmatter present: Has --- delimiters
• Description field: Frontmatter includes description
• Naming: kebab-case filename
• Content: Not empty after frontmatter