Plugin Best Practices

Validation and optimization guidance for Claude Code plugins.

RFC 2119 terms are mandatory: use only MUST, MUST NOT, SHOULD, SHOULD NOT, MAY. Replace REQUIRED/SHALL with MUST, SHALL NOT with MUST NOT, RECOMMENDED with SHOULD, NOT RECOMMENDED with SHOULD NOT, and OPTIONAL with MAY. See references/rfc-2119.md.

Core Principles

• Skills are the preferred extension mechanism for new plugins, with commands reserved for backward compatibility.

Component Model

Skills

Skills are markdown prompts that run in the main conversation context and extend knowledge or provide workflows.

Two skill types are supported:

• Instruction-type (user-invocable: true → commands): imperative voice, phase-based workflows, user-invoked.
• Knowledge-type (user-invocable: false → skills): declarative voice, topic-based references, auto-loaded.

Agents

Agents are autonomous subprocesses with isolated context and their own system prompts.

Key characteristics:

• Isolated context with a dedicated system prompt in the agent .md file.
• Restricted tool allowlists for safety and focus.
• Specialized expertise with judgment over execution details.
• Router-friendly descriptions containing 2–4 <example> blocks.

Selection Guide

• Instruction-type skills apply when a user invokes a workflow via slash command and the process is linear.
• Knowledge-type skills apply when providing reference knowledge for agents or the main session.
• Agents apply when isolation, specialization, and autonomous decision-making are required.

Templates and Structure

Templates are centralized for reuse across components. See ${CLAUDE_PLUGIN_ROOT}/examples/ for complete templates.

plugin.json Declaration

Validation Checklist

• Skills are under 500 lines with progressive disclosure to references/.
• Agents include clear delegation descriptions and a single responsibility.
• Agent descriptions include 2–4 <example> blocks.
• Component names use kebab-case.
• Scripts are executable with shebangs and ${CLAUDE_PLUGIN_ROOT} paths.
• Tool invocations avoid explicit tool-call phrasing (see references/tool-invocations.md).
• Skill references use qualified names (plugin-name:skill-name).
• Component paths are relative and start with ./.
• Components live at plugin root, not inside .claude-plugin/.
• Skills and commands are declared in plugin.json (recommended).
• Skill type matches manifest and writing style:
  • Instruction-type uses imperative voice.
  • Knowledge-type uses declarative voice.

Severity Levels

• Critical: MUST fix before plugin works correctly.
• Warning: SHOULD fix for best-practices compliance.
• Info: MAY improve (optional).

Reference Link Rule

Links to external templates or example files include a one-sentence description of what the target contains before the link.

Additional Resources

Reference documents live in references/:

• Components: references/components/[type].md — component-specific requirements.
• Structure: references/directory-structure.md — layout and naming conventions.
• Manifest: references/manifest-schema.md — plugin.json schema and configuration.
• Tool Usage: references/tool-invocations.md — tool invocation patterns.
• MCP Patterns: references/mcp-patterns.md — MCP server integration.
• Debugging: references/debugging.md — diagnostics for loading failures.
• CLI Commands: references/cli-commands.md — plugin CLI operations.
• TodoWrite Tool: references/todowrite-usage.md — TodoWrite usage.

Prompt Repetition

• Critical rules and safety constraints appear in multiple phases only when execution depends on it.
• Repetition favors concise restatement rather than verbatim duplication.

Parallel Agent Execution

Parallel execution applies when tasks are independent and results can be merged afterward.

Request pattern:

# Explicit parallel request

Launch all agents simultaneously:
- `domain-analyzer` agent
- `quality-validator` agent
- `format-checker` agent

# Or use "in parallel" phrasing

Launch 3 parallel agents to process different aspects independently

Best practices:

• "parallel" or "simultaneously" appears explicitly in the request.
• Descriptive style names the agent and intent.
• Consolidation merges findings and resolves conflicts.

Common pattern:

1. Sequential setup (if needed)
2. Launch specialized analyses in parallel:
   - `aspect-one-analyzer` agent — first dimension
   - `aspect-two-validator` agent — second dimension
   - `aspect-three-checker` agent — third dimension
3. Consolidate results and present unified output