gh-hyperskill-claude-code-marketplace-plugins-plugin-development/commands/validate.md

description

description
Validate plugin structure, manifest, and component files for common issues

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

5. Validate Skills

For each directory in skills/:

• SKILL.md exists: In uppercase
• Frontmatter present: Has --- delimiters
• Required fields: name and description present
• Name matches directory: Exact match, kebab-case
• Description is specific: Includes when/why to use

6. Validate Agents

For each file in agents/:

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

7. Validate Hooks

If hooks.json exists:

• Valid JSON: Can parse without errors
• Proper structure: Has hooks object
• Event names: Valid events (PreToolUse, PostToolUse, etc.)
• Hook commands: Scripts use ${CLAUDE_PLUGIN_ROOT}
• Scripts exist: Referenced scripts are present
• Scripts executable: Have execute permissions

Validation Output Format

Report findings in this structure:

🔍 Validating plugin: <plugin-name>

✅ Structure
  ✓ .claude-plugin/plugin.json exists
  ✓ Component directories present

✅ Manifest (plugin.json)
  ✓ Valid JSON
  ✓ Required fields: name, version, description
  ✓ Name format: kebab-case
  ✓ Version format: SemVer
  ✓ Paths are relative

✅ Commands (3 files)
  ✓ commands/init.md
  ✓ commands/validate.md
  ✓ commands/test-local.md

✅ Skills (1 skill)
  ✓ skills/plugin-authoring/SKILL.md
    - name matches directory: ✓
    - description present: ✓

✅ Agents (1 agent)
  ✓ agents/plugin-reviewer.md

✅ Hooks
  ✓ hooks/hooks.json is valid
  ✓ Scripts exist and are executable

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Validation passed: 0 errors, 0 warnings

Error Reporting

If issues are found, report clearly:

❌ Errors Found

1. Manifest: plugin.json missing required field "version"
   Fix: Add "version": "1.0.0" to .claude-plugin/plugin.json

2. Command: commands/myCommand.md uses camelCase
   Fix: Rename to commands/my-command.md (kebab-case)

3. Skill: skills/MySkill/SKILL.md name doesn't match directory
   Fix: Change frontmatter 'name' to "my-skill" (matches directory)

⚠️  Warnings

1. No README.md found
   Suggestion: Create README.md with usage documentation

2. No keywords in plugin.json
   Suggestion: Add keywords array for discoverability

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ Validation failed: 3 errors, 2 warnings

Validation Categories

Critical (Must Fix)

• Missing plugin.json
• Invalid JSON in config files
• Missing required fields (name, version, description)
• Absolute paths in configuration
• Component name mismatches (skill name ≠ directory)
• Non-executable hook scripts

Warnings (Should Fix)

• Missing README.md
• No keywords in plugin.json
• Empty component directories
• Commands missing argument-hint
• Skills without progressive disclosure structure

Suggestions (Nice to Have)

• Add CHANGELOG.md
• Include examples directory
• Add more descriptive descriptions
• Use consistent naming patterns

Common Issues Detected

Issue: Paths Not Relative

❌ "commands": "/Users/you/plugin/commands/"
✅ "commands": "./commands/"

Issue: Name Mismatch

Directory: skills/code-review/
Frontmatter: name: codeReview
❌ Names don't match

Fix: Change frontmatter to name: code-review

Issue: Missing Frontmatter

# My Command

Instructions...

❌ No frontmatter with description

---
description: What this command does
---

# My Command

Instructions...

✅ Has required frontmatter

Issue: Hook Script Not Executable

$ ls -l scripts/validate.sh
-rw-r--r--  validate.sh
❌ Not executable

$ chmod +x scripts/validate.sh
✅ Now executable

Validation Checklist

Complete checklist used for validation:

Structure:
□ .claude-plugin/plugin.json exists
□ At least one component directory present
□ README.md exists

Manifest:
□ Valid JSON syntax
□ name field: present, kebab-case
□ version field: present, valid SemVer
□ description field: present, non-empty
□ Paths are relative (start with ./)
□ Referenced paths exist

Commands:
□ .md extension
□ Frontmatter with description
□ kebab-case naming
□ Non-empty content

Skills:
□ Directory structure (skill-name/SKILL.md)
□ SKILL.md in uppercase
□ Frontmatter with name and description
□ Name matches directory (exact, kebab-case)

Agents:
□ .md extension
□ Frontmatter with description
□ kebab-case naming
□ Non-empty content

Hooks:
□ hooks.json valid JSON
□ Proper structure (hooks object)
□ Valid event names
□ Scripts use ${CLAUDE_PLUGIN_ROOT}
□ Scripts exist
□ Scripts are executable (chmod +x)

After Validation

If Validation Passes

✅ Plugin is valid and ready for testing!

Next steps:
1. Test locally: /plugin-development:test-local
2. Create dev marketplace and install
3. Test all commands and features
4. Register in team marketplace when ready

If Validation Fails

❌ Please fix the errors above before testing.

Need help?
- Review error messages for specific fixes
- Check best practices: /plugin-development:help
- Common issues documented in examples

Example Usage

Input: /plugin-development:validate

Output:

🔍 Validating plugin: my-awesome-plugin

✅ All checks passed
✓ Structure correct
✓ Manifest valid
✓ 5 commands validated
✓ 2 skills validated
✓ 1 agent validated
✓ Hooks configured correctly

✅ Plugin ready for testing!

Best Practices

1. Validate often: Run before testing or commits
2. Fix errors first: Address critical issues before warnings
3. Read messages carefully: Each error includes fix instructions
4. Use debug mode: Run claude --debug for deep inspection
5. Incremental fixes: Fix and re-validate one issue at a time

Notes

• This command only reads files (no modifications)
• Validation is comprehensive but not exhaustive
• Some issues may only appear during runtime testing
• Always test in a dev marketplace after validation passes