Plugin Validator

Overview

A valid plugin is a working plugin. This skill guides systematic validation of the entire Bosun plugin - manifest, agents, skills, and commands - and their cross-references.

Core principle: Validate the whole, not just the parts. Components must work together.

The Validation Process

Phase 1: Manifest Validation

Check .claude-plugin/plugin.json:

1. Structure

   • Valid JSON syntax
   • Required fields present (name, version, description)
   • Version follows semver (x.y.z)

2. File References

   • All referenced agent files exist
   • All referenced command files exist
   • All referenced skill directories exist

Phase 2: Agent Validation

Check each file in agents/*.md:

1. Frontmatter

   • Required: name, description, tools, model
   • Optional: skills, disallowedTools

2. Model Selection

   • opus - For critical work (security, architecture)
   • sonnet - For standard work (quality, docs)
   • haiku - For quick tasks

3. Skill References

   • All skills in skills: [...] exist in skills/ directory
   • Skills match agent's purpose

4. Tool Selection

   • Tools are valid Claude Code tools
   • Read-only agents use disallowedTools: Edit, Write

Phase 3: Skill Validation

Delegate to skill-validator skill for each skill, plus:

1. Agent Coverage

   • Which agents reference each skill?
   • Are any skills orphaned (no agent uses them)?

2. Category Balance

   • Domain skills (security, architect, testing, etc.)
   • Language skills (golang, typescript, python, etc.)
   • Cloud skills (aws, gcp, azure)

Phase 4: Command Validation

Check each file in commands/*.md:

1. Frontmatter

   • Required: name, description

2. Content

   • Clear usage instructions
   • Example output shown
   • Error handling documented

Phase 5: Cross-Reference Validation

Check relationships between components:

1. Skill-Agent Mapping

   • All skills referenced by agents exist
   • Identify orphaned skills
   • Identify agents with no skills

2. Consistency

   • Naming conventions followed
   • No duplicate names across components

Red Flags - STOP and Fix

Manifest Red Flags

// ❌ Invalid JSON
{ name: "bosun" }  // Missing quotes

// ❌ Missing version
{ "name": "bosun", "description": "..." }

// ❌ Invalid semver
{ "version": "1.0" }  // Should be "1.0.0"

Agent Red Flags

# ❌ Missing required field
name: security-agent
description: "..."
# Missing: tools, model

# ❌ Invalid model
model: gpt-4  # Should be opus, sonnet, or haiku

# ❌ Non-existent skill
skills: [nonexistent]

# ❌ Read-only agent with write tools
disallowedTools: Edit  # Missing Write

Cross-Reference Red Flags

- Agent references skill that doesn't exist
- Skill exists but no agent uses it
- Command references non-existent agent
- Duplicate component names

Common Rationalizations - Don't Accept These

Validation Checklist

Before approving the plugin:

Manifest:

• Valid JSON syntax
• Version follows semver
• All referenced files exist

Agents:

• All have required frontmatter fields
• Model is valid (opus/sonnet/haiku)
• Referenced skills exist
• Tools are valid

Skills:

• All pass skill-validator checks
• No orphaned skills (or documented why)
• Good category coverage

Commands:

• All have required frontmatter
• Usage documented
• Error handling covered

Cross-References:

• All skill references resolve
• No duplicate names
• Naming conventions followed

Quick Validation Commands

# Validate manifest JSON
jq . .claude-plugin/plugin.json

# List all agents
ls agents/*.md

# List all skills
ls -d skills/*/

# List all commands
ls commands/*.md

# Find skills referenced by agents
grep -h "^skills:" agents/*.md

# Find orphaned skills (not in any agent)
comm -23 <(ls -d skills/*/ | xargs -n1 basename | sort) \
         <(grep -h "^skills:" agents/*.md | tr '[],' '\n' | grep bosun | sort -u)

Validation Output Format

When validating, report findings like this:

Bosun Plugin Validation
=======================

Manifest (.claude-plugin/plugin.json)
  ✓ Valid JSON
  ✓ Version: 1.0.0
  ✓ All file references valid

Agents (9 files)
  ✓ security-agent (opus, 2 skills)
  ✓ quality-agent (sonnet, 4 skills)
  ✓ architecture-agent (opus, 2 skills)
  ... all valid

Skills (20 directories)
  ✓ 18/20 valid
  ✗ security: missing reference security-headers.md
  ✗ architect: missing references api-design.md, architecture-patterns.md

Commands (3 files)
  ✓ All valid

Cross-References
  ⚠ Orphaned skills: rust, java, csharp
    (exist but not assigned to any agent)

Overall: PASS with warnings

References

• skill-validator for individual skill validation
• CLAUDE.md for Bosun conventions
• .claude-plugin/plugin.json for manifest schema