plugin-best-practices

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:

1. Structure: File patterns, directory layout, kebab-case naming
2. Manifest: plugin.json required fields and schema compliance
3. Frontmatter: YAML frontmatter in components, third-person descriptions
4. Tool Invocations: Anti-pattern detection (implicit vs explicit tool calls)
5. 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

Field order: name → description → model/color/skills/tools/isolation → <example> blocks → closing ---. Fields placed after <example> blocks are not parsed as YAML.

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