Plugin Validator

Validation Checks

1. Manifest Validation

• plugin.json exists at correct location
• Valid JSON syntax
• Required fields present (name, description, version)
• Semantic versioning format (X.Y.Z)
• Array fields properly formatted (agents, commands, skills)
• No duplicate entries

2. Structure Validation

• Referenced agents exist at specified paths
• Referenced commands exist at specified paths
• Referenced skills exist at specified paths
• File paths are relative (not absolute)
• No broken file references
• Directory structure follows conventions

3. Frontmatter Validation

• YAML syntax is valid
• Required fields present (name, description)
• Field values match allowed types
• Tools list is valid (if specified)
• Model value is valid (sonnet|opus|haiku|inherit)
• No conflicting or deprecated fields

4. Dependency Validation

• No circular dependencies between agents/skills
• Skill references resolve correctly
• Tool permissions are valid
• Cross-references between components exist
• External dependencies documented

5. Configuration Validation

• No conflicting settings between components
• File permissions are readable
• No duplicate agent/command names
• Version consistency across files
• Repository metadata accurate

Process

1. Identify plugin location

   # Find plugin.json
   find . -name "plugin.json" -o -name ".claude-plugin/plugin.json"
   

2. Run manifest validation

   • Parse JSON syntax
   • Check required fields
   • Validate semver format
   • Verify array structures

3. Validate file structure

   • Read manifest file references
   • Check each referenced file exists
   • Verify paths are relative
   • Check directory conventions

4. Check frontmatter

   • For each agent/command file
   • Parse YAML frontmatter
   • Validate required fields
   • Check field value constraints

5. Analyze dependencies

   • Build dependency graph
   • Detect circular references
   • Validate skill references
   • Check tool usage patterns

6. Report findings

   • Categorize by severity (critical, warning, info)
   • Provide specific file/line references
   • Suggest fixes with examples
   • Prioritize by impact

Validation Severity Levels

CRITICAL (Plugin won’t load)

• Invalid JSON in plugin.json
• Missing required fields (name, description, version)
• Referenced files don’t exist
• Invalid YAML in frontmatter
• Circular dependencies

WARNING (Plugin may malfunction)

• Invalid semver format
• Deprecated field usage
• Missing optional but recommended fields
• Inconsistent naming conventions
• Potential conflicts

INFO (Best practice suggestions)

• Missing documentation
• Version mismatch across files
• Code style inconsistencies
• Missing cross-references
• Optimization opportunities

Examples

✅ Good trigger: “Validate the waypoint plugin” ✅ Good trigger: “Check why my plugin isn’t loading” ✅ Good trigger: “Plugin health check for claire” ✅ Good trigger: “My agent file has errors”

❌ Bad trigger: “Create a new plugin” (creation, not validation) ❌ Bad trigger: “Update plugin version” (modification, not validation) ❌ Bad trigger: “Install plugin” (installation, not validation)

Common Issues and Fixes

Issue: Plugin not loading

Check:

• plugin.json exists in correct location
• JSON syntax is valid
• Required fields present
• Version follows semver

Fix:

# Validate JSON syntax
python3 -m json.tool plugin.json

# Check location
test -f .claude-plugin/plugin.json || test -f plugin.json

Issue: Agent not working

Check:

• Agent file exists at path in plugin.json
• YAML frontmatter is valid
• Required fields (name, description) present
• Tools list is valid

Fix:

# Check agent path
grep '"agents"' plugin.json

# Validate YAML (first 20 lines typically contain frontmatter)
head -20 agents/my-agent.md

Issue: Circular dependencies

Check:

• Agent A references skill B
• Skill B references agent A
• Build dependency graph

Fix:

• Restructure to remove circular reference
• Extract shared logic to separate component
• Document dependency rationale

Supporting Files

For detailed validation rules, see:

• manifest.md – plugin.json validation rules
• frontmatter.md – YAML frontmatter validation
• structure.md – File structure conventions
• dependencies.md – Dependency analysis

Quick Reference

Valid plugin.json structure

{
  "name": "plugin-name",
  "description": "Plugin description",
  "version": "1.0.0",
  "agents": ["./agents/agent-name.md"],
  "commands": ["./commands/command-name.md"],
  "skills": ["./skills/skill-name"]
}

Valid agent/command frontmatter

---
name: component-name
description: Component description
tools: Read, Write, Bash
model: sonnet
---

Validation command pattern

# Validate plugin at current directory
ls -la .claude-plugin/plugin.json plugin.json

# Check all referenced files
grep -o '"[^"]*\.md"' plugin.json | while read file; do
    test -f "${file//\"/}" && echo "✓ $file" || echo "✗ $file"
done

Related

• Agent: claire-plugin-manager for plugin management and health checks
• Skill: doc-validator for documentation validation
• Commands: Claude Code plugin system documentation