Plugin Validation & Best Practices

Validates Claude Code plugins against architectural standards. This file is a navigation guide; detailed content lives in references/.

Quick Start

Run validation on a plugin:

python3 plugin-optimizer/scripts/validate-plugin.py <plugin-path>

For specific checks only:

python3 plugin-optimizer/scripts/validate-plugin.py <plugin-path> --check=manifest,frontmatter

Component Selection Guide

Component	When to Use	Key Requirements
Instruction-type Skills	User-invoked workflows, linear process	Imperative voice, phase-based, declared in `commands`
Knowledge-type Skills	Reference knowledge for agents	Declarative voice, topic-based, declared in `skills`
Agents	Isolated, specialized decision-making	Restricted tools, 2-4 `<example>` blocks, isolated context
MCP Servers	External tool/data integration	stdio/http/sse transport, ${CLAUDE_PLUGIN_ROOT} paths
LSP Servers	IDE features (go to definition)	Language server binary, extension mapping
Hooks	Event-driven automation	PreToolUse/PostToolUse events, command/prompt/agent types

See ./references/component-model.md for detailed selection criteria and ./references/components/ for implementation guides.

Progressive Disclosure

Three-tier token structure ensures efficient context usage:

Level	Content	Token Budget	Loading
1	Metadata (name + description)	~100 tokens	Always (at startup)
2	SKILL.md body	Under 5k tokens	When skill triggered
3	References/ files	Effectively unlimited	On-demand via bash

Implementation Pattern:

SKILL.md: Overview and navigation to reference files
References/: Detailed specs, examples, patterns
Scripts/: Executable utilities (no context cost until executed)

See ./references/component-model.md for complete token budget guidelines.

Validation Workflow

Five sequential checks cover all plugin quality dimensions:

Structure: File patterns, directory layout, kebab-case naming
Manifest: plugin.json required fields and schema compliance
Frontmatter: YAML frontmatter in components, third-person descriptions
Tool Invocations: Anti-pattern detection (implicit vs explicit tool calls)
Token Budget: Progressive disclosure compliance (under 5k tokens for SKILL.md)

Run validation with -v flag for verbose output showing all passing checks.

See ./references/validation-checklist.md for complete criteria.

Requirement Levels (RFC 2119)

Plugin documentation uses RFC 2119 requirement levels:

MUST / MUST NOT: Absolute requirement or prohibition
SHOULD / SHOULD NOT: Recommended practice with known exceptions
MAY: Truly optional

See ./references/rfc-2119.md for complete RFC 2119 specification.

Critical Patterns

Tool Invocation Rules

Tool	Style	Example
Read, Write, Edit, Glob, Grep	Implicit	"Find files matching..."
Bash	Implicit	"Run `git status`"
Task	Implicit	"Launch `plugin-name:agent-name` agent"
Skill	Explicit	"Load `plugin-name:skill-name` skill using the Skill tool"
TaskCreate	Explicit	"Use TaskCreate tool to track progress"
AskUserQuestion	Explicit	"Use `AskUserQuestion` tool to [action]"
MCP Tools	Implicit	"Query the database for user records"

Qualified names: MUST use plugin-name:component-name format for plugin components.

allowed-tools: NEVER use bare Bash - always use filters like Bash(git:*).

Inline Bash: Use inline syntax (exclamation + backtick + command + backtick) for dynamic context.

MCP Tool Invocation: Use natural language to describe intent — Claude automatically identifies the appropriate MCP tool. Never specify exact MCP tool names like mcp__server__tool in skill content.

See ./references/tool-invocations.md for complete patterns and anti-patterns. See ./references/mcp-patterns.md for MCP-specific invocation patterns.

Skill Frontmatter (Official Best Practices)

Required fields:

name: Max 64 chars, lowercase letters/numbers/hyphens only
description: Max 1024 chars. MUST use third-person voice with specific trigger phrases.

Description Best Practices:

Requirement	Description
Person	Third-person only ("This skill should be used when...")
Structure	[What it does]. Use when [scenario 1], [scenario 2], or [user phrases].
Purpose	Skill discovery - Claude uses this to select from 100+ skills
Trigger phrases	Include specific user phrases like "validate plugin", "check frontmatter"

Additional fields are supported but affect progressive disclosure alignment.

See ./references/components/skills.md for complete frontmatter specification.

Agent Frontmatter

Required fields:

name: 3-50 chars, kebab-case
model: inherit, sonnet, opus, or haiku
color: blue, cyan, green, yellow, magenta, or red
<example> blocks: 2-4 required for router-friendliness
isolation: worktree: Optional — enables automatic git worktree isolation for parallel execution

See ./references/components/agents.md for complete agent design guidelines including CO-STAR framework.

Task Management

Tasks with 3+ distinct steps, multi-file work, or sequential dependencies warrant TaskCreate. Single-file edits and 1-2 step operations do not.

Core Requirements:

Dual form naming: subject ("Run tests") + activeForm ("Running tests")
Mark in_progress BEFORE starting, completed AFTER finishing
Only mark completed when FULLY done

See ./references/task-management.md for complete patterns and examples.

MCP Server Configuration

MCP servers are configured in .mcp.json at plugin root or inline in plugin.json under mcpServers. Three transport types are supported: stdio (local CLI tools), http (remote APIs, most widely supported), and sse (real-time streaming).

NEVER hardcode secrets — always use ${ENV_VAR} syntax.

See ./references/mcp-patterns.md for complete MCP integration patterns. See ./references/components/mcp-servers.md for component configuration details.

Hook Configuration

Hook events cover the full session lifecycle: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, UserPromptSubmit, Notification, Stop, SubagentStart, SubagentStop, SessionStart, SessionEnd, PreCompact. Three hook types are available: command, prompt, and agent.

See ./references/components/hooks.md for complete hook patterns including AI-native structured output.

Agent Teams vs Subagents

Subagents are isolated, single-direction sub-processes returning results to the caller. Agent Teams are multiple independent sessions sharing a task list with direct peer-to-peer communication — suited for parallel investigation, multi-module features, and competing hypotheses.

	Subagents	Agent Teams
Context	Returns to caller	Fully independent
Communication	To main agent only	Direct peer-to-peer
Token cost	Lower (summarized)	Higher (full instances)

Agent Teams are experimental. Enable with export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.

See ./references/agent-teams.md for complete guide and ./references/parallel-execution.md for parallel coordination patterns.

Directory Structure

Standard Layout:

plugin-name/
├── .claude-plugin/plugin.json    # Manifest (declare components here)
├── skills/                       # Agent Skills (RECOMMENDED)
│   └── skill-name/
│       ├── SKILL.md
│       └── references/
├── commands/                     # Legacy commands (optional)
├── agents/                       # Subagent definitions
├── hooks/hooks.json              # Hook configuration
├── .mcp.json                     # MCP server definitions
├── .lsp.json                     # LSP server configurations
└── scripts/                      # Executable scripts

Critical Rules:

Components live at plugin root, NOT inside .claude-plugin/
Scripts MUST be executable with shebangs
Scripts MUST use ${CLAUDE_PLUGIN_ROOT} for paths
All paths MUST be relative and start with ./

See ./references/directory-structure.md for complete layout guidelines.

Reference Directory

Validation & Quality

./references/validation-checklist.md - Complete quality checklist
./references/rfc-2119.md - Requirement levels (MUST/SHOULD/MAY)

Component Implementation

./references/component-model.md - Component types, selection criteria, token budgets
./references/components/skills.md - Skill structure, frontmatter, progressive disclosure
./references/components/agents.md - Agent design, CO-STAR framework, example blocks
./references/components/commands.md - Command frontmatter, dynamic context
./references/components/hooks.md - Hook events, types, AI-native patterns, templates
./references/components/mcp-servers.md - MCP configuration, stdio/http/sse
./references/components/lsp-servers.md - LSP setup, binary requirements

Configuration & Integration

./references/directory-structure.md - Plugin layout, naming conventions
./references/manifest-schema.md - plugin.json schema, required fields
./references/mcp-patterns.md - MCP transport types, security best practices

Development Patterns

./references/tool-invocations.md - Tool usage patterns and anti-patterns
./references/tool-design-philosophy.md - Principles for designing tools that work with Claude's strengths
./references/task-management.md - TaskCreate patterns, dual-form naming
./references/cli-commands.md - CLI commands for plugin management

Advanced Topics

./references/agent-teams.md - Parallelizable tasks, multi-perspective analysis
./references/parallel-execution.md - Parallel agent coordination patterns
./references/debugging.md - Common issues, error messages, troubleshooting

plugin-best-practices