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 ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin.py <plugin-path>

For specific checks only:

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin.py <plugin-path> --check=manifest,frontmatter

Component Selection Guide

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:

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

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. Naming convention by type: instruction-type skills use a use-<action> prefix (e.g., use-kicad-cli); knowledge-type skills use a using-<topic> prefix (e.g., using-git-worktrees).
• description: Max 1024 chars. MUST use third-person voice with specific trigger phrases.

Description Best Practices:

Additional fields are supported but affect progressive disclosure alignment.

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

Agent Frontmatter

Required fields (per upstream spec):

• name: 3-50 chars, kebab-case
• description: trigger conditions plus 2-4 <example> blocks

Optional fields: model, color, effort, maxTurns, tools, disallowedTools, skills, memory, background, isolation (only "worktree" is valid).

Forbidden fields in plugin agents (security): hooks, mcpServers, permissionMode.

Field order: name → description (a | block scalar containing trigger conditions and the <example> blocks) → other YAML fields → closing ---. Bare <example> blocks outside the description break YAML parsing.

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 (28+ events including PreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch, PermissionRequest, PermissionDenied, UserPromptSubmit, UserPromptExpansion, Setup, Notification, Stop/StopFailure, SubagentStart/SubagentStop, TaskCreated/TaskCompleted, TeammateIdle, InstructionsLoaded, ConfigChange, CwdChanged, FileChanged, WorktreeCreate/WorktreeRemove, PreCompact/PostCompact, Elicitation/ElicitationResult, SessionStart/SessionEnd). Five hook types: command, http, mcp_tool, prompt, agent.

See ./references/components/hooks.md for the full event table and AI-native structured output patterns.

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.

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/                     # Skills as flat .md files (legacy)
├── agents/                       # Subagent definitions
├── output-styles/                # Output style markdown
├── themes/                       # Color theme JSON
├── monitors/monitors.json        # Background monitor configs
├── hooks/hooks.json              # Hook configuration
├── bin/                          # Executables added to Bash PATH
├── settings.json                 # Plugin default settings
├── .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, forbidden fields
• ./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
• ./references/components/monitors.md - Background monitor configuration
• ./references/components/themes.md - Color theme JSON structure
• ./references/components/output-styles.md - Output style frontmatter

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