Skip to main content
skill CX Codex

plugin-best-practices — Claude Code skill: plugin validation

plugin-best-practices validates Claude Code plugin structure, manifests, and architecture against framework standards. Ensures your plugin meets requirements before marketplace submission.

MIT 121 installs ★ 597 updated 2026-11-06

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add FradSer/dotclaude --skill plugin-best-practices -a claude-code
Open on GitHub

What plugin-best-practices does

Runs five sequential checks: file structure and layout, plugin.json schema compliance, YAML frontmatter in components, tool invocation patterns, and token budget adherence. Execute via validate-plugin.py script with optional flags to test specific aspects only.

Includes component selection guides: when to use instruction-type and knowledge-type skills, agents, MCP servers, hooks, monitors, themes, and output styles. Each component has naming rules (instruction skills prefix use-<action>, knowledge skills prefix using-<topic>), frontmatter requirements, and structural patterns.

Follows three-tier progressive disclosure: metadata loads first, SKILL.md stays under 5k tokens, reference files load on demand. Validation runs sequentially through file structure, manifest fields, frontmatter format, tool calls, and token compliance.

What it helps with

  • Verify plugin structure meets architectural standards
  • Check manifest fields and JSON schema compliance
  • Validate frontmatter formatting and trigger phrases
  • Detect anti-patterns in tool invocation syntax
  • Ensure SKILL.md token budget compliance

Example prompts for the agent

  • Validate the plugin structure in my project
  • Check manifest and frontmatter for errors
  • Run validation with verbose output for all checks

How to install plugin-best-practices

1Skills CLI (Vercel)

npx skills add FradSer/dotclaude --skill plugin-best-practices -a claude-code

2Manually: put the files in place

~/.claude/skills/plugin-best-practices/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/plugin-best-practices/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about plugin-best-practices

How do I install plugin-best-practices in Claude Code?

Run npx skills add FradSer/dotclaude --skill plugin-best-practices -a claude-code, then open ~/.claude/skills/plugin-best-practices/SKILL.md.

What does plugin-best-practices do?

Validates Claude Code plugins against five dimensions: file structure, manifest schema, frontmatter format, tool invocation patterns, and token budget. Helps ensure your plugin meets architectural standards.

What checks does the validation run?

Validates directory layout, required fields in plugin.json, third-person descriptions with trigger phrases, implicit vs explicit tool calls, and SKILL.md size (under 5k tokens).

Source text

SKILL.md · MIT
---
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:

```bash
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin.py <plugin-path>
```

For specific checks only:
```bash
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, `user-invocable: true`; name with `use-<action>` prefix (e.g., `use-kicad-cli`) |
| **Knowledge-type Skills** | Reference knowledge for agents | Declarative voice, topic-based, `user-invocable: false`; 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 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.

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

© FradSer · MIT · FradSer/dotclaude

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set16

The whole set →
commit-and-push commit-and-push — a skill for Claude Code, Codex, Cursor, and other platforms that generates atomic commits using Conventional Commits standard via git-agent and pushes them to the remote repository. CX Codex +1 126installs brainstorming brainstorming — a skill for Claude Code and five other tools that turns raw ideas into ready BDD specs. It researches your codebase autonomously and commits the technical design without asking questions mid-run. CX Codex +1 124installs writing-plans writing-plans — a skill for Claude Code, Codex, Cursor and other platforms that transforms a finished design into an executable implementation plan. CX Codex +1 123installs refactor-project refactor-project — a skill for Claude Code, Codex, Cursor and other agents that runs automated refactoring across every file in the project at once. Cuts duplication, normalises patterns, and strips legacy code in a single pass. CX Codex +1 122installs commit This skill creates atomic conventional commits through git-agent. Use it when a short intent should become a focused Git commit. CX Codex +1 121installs optimize-plugin optimize-plugin validates Claude plugin structure, runs Python sanity checks, and fixes issues via a subagent. Useful when auditing or refactoring plugin manifests and components. CX Codex +1 117installs create-prd The create-prd skill turns product ideas into a structured PRD through a guided interview, then saves it as Markdown or creates a Feishu document. CX Codex +1 117installs create-issues create-issues automates GitHub issue creation with TDD principles, proper labeling, and auto-closing keywords. Detects repository templates, applies conventions, and links issues to epics or related tasks. CX Codex +1 116installs

Project sponsors

Companies that keep this analytics open