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