From plugin-optimizer
Validates Claude Code plugins for structure, manifest, frontmatter, tool invocations, and token budgets using Python scripts. Guides selection of components like skills, agents, MCP/LSP servers, hooks.
npx claudepluginhub fradser/dotclaude --plugin plugin-optimizerThis skill uses the workspace's default tool permissions.
Validates Claude Code plugins against architectural standards. This file is a navigation guide; detailed content lives in `references/`.
references/agent-teams.mdreferences/cli-commands.mdreferences/component-model.mdreferences/components/agents.mdreferences/components/commands.mdreferences/components/hooks.mdreferences/components/lsp-servers.mdreferences/components/mcp-servers.mdreferences/components/skills.mdreferences/debugging.mdreferences/directory-structure.mdreferences/manifest-schema.mdreferences/mcp-patterns.mdreferences/parallel-execution.mdreferences/rfc-2119.mdreferences/task-management.mdreferences/tool-design-philosophy.mdreferences/tool-invocations.mdreferences/validation-checklist.mdGuides Claude Code plugin creation, directory structure, plugin.json manifest setup, component organization for commands/agents/skills/hooks/lspServers, file conventions, and best practices like auto-discovery and CI integration.
Guides creating, validating, and troubleshooting Claude Code plugin.json files. Useful for plugin setup, schema compliance, and configuration issues.
Guides creation, validation, and troubleshooting of Claude Code plugin.json files, including schema, required fields, and best practices.
Share bugs, ideas, or general feedback.
Validates Claude Code plugins against architectural standards. This file is a navigation guide; detailed content lives in references/.
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 | 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 | PreToolUse/PostToolUse events, command/prompt/agent types |
See ./references/component-model.md for detailed selection criteria and ./references/components/ for implementation guides.
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:
See ./references/component-model.md for complete token budget guidelines.
Five sequential checks cover all plugin quality dimensions:
Run validation with -v flag for verbose output showing all passing checks.
See ./references/validation-checklist.md for complete criteria.
Plugin documentation uses RFC 2119 requirement levels:
See ./references/rfc-2119.md for complete RFC 2119 specification.
| 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.
Required fields:
name: Max 64 chars, lowercase letters/numbers/hyphens onlydescription: 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.
Required fields:
name: 3-50 chars, kebab-casemodel: inherit, sonnet, opus, or haikucolor: blue, cyan, green, yellow, magenta, or red<example> blocks: 2-4 required for router-friendlinessisolation: worktree: Optional — enables automatic git worktree isolation for parallel executionField order: name → description → model/color/skills/tools/isolation → <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.
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:
in_progress BEFORE starting, completed AFTER finishingcompleted when FULLY doneSee ./references/task-management.md for complete patterns and examples.
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 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.
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.
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:
.claude-plugin/${CLAUDE_PLUGIN_ROOT} for paths./See ./references/directory-structure.md for complete layout guidelines.
./references/validation-checklist.md - Complete quality checklist./references/rfc-2119.md - Requirement levels (MUST/SHOULD/MAY)./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./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./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./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