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

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

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 → blocks → closing

. Fields placed after 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