/plugin-best-practices

name: plugin-best-practices
description: This skill should be used when the user asks to "validate plugin structure", "review manifest files", "check frontmatter compliance", "verify tool invocation patterns", "explain plugin component types", or needs Claude Code plugin architectural guidance.
user-invocable: false

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

| Component | When to Use | Key Requirements | |-----------|-------------|------------------| | **Instruction-type Skills** | User-invoked workflows, linear process | Imperative voice, phase-based, declared in `commands`; name with `use-<action>` prefix (e.g., `use-kicad-cli`) | | **Knowledge-type Skills** | Reference knowledge for agents | Declarative voice, topic-based, declared in `skills`; name with `using-<topic>` prefix (e.g., `using-git-worktrees`) | | **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. **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**:

| 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 fie