plugin-best-practices

What this skill does

# 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:

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

For specific checks only:
```bash
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 | Lifecycle events, `command`/`http`/`mcp_tool`/`prompt`/`agent` types |
| **Monitors** | Long-running watchers (logs, deploys) | `name`+`command`+`description` per entry; v2.1.105+ |
| **Themes** | Bundled color presets | JSON with `name`, `base`, `overrides` |
| **Output Styles** | Adjust response formatting | Markdown with `name` + `description` frontmatter |

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** (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` → other YAML fields → `<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 (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.

| | Subagents | Ag