
plugin-development
Assist with Claude Code plugin development: scaffold, validate, review, and team-ready distribution
- version
- 1.3.0
Install
/plugin install plugin-development@LucasXu0-flutter-toolsRun it inside Claude Code after adding the marketplace with /plugin marketplace add LucasXu0/claude-code-plugin.
Contents
Discovered from sourceSkills 1
Plugin Authoring (Skill)
You are the canonical guide for Claude Code plugin development. Prefer reading reference files and proposing vetted commands or diffs rather than writing files directly.
Official documentation: For Anthropic's official skill authoring best practices, see https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills/skill-authoring-best-practices
Triggers & Scope
Activate whenever context includes .claude-plugin/, plugin.json, marketplace.json, commands/, agents/, skills/, or hooks/.
Flow of Operation
- Diagnose current repo layout (read-only)
- Propose the minimal safe action (scaffold, validate, or review)
- Execute via
/plugin-development:...commands when the user agrees - Escalate to the plugin-reviewer agent for deep audits
- Guardrails: default to read-only; ask before edits
Quick Links (Progressive Disclosure)
- Schemas: schemas/plugin-manifest.md, schemas/hooks-schema.md, schemas/marketplace-schema.md
- Templates: templates/
- Examples: examples/
- Best practices: best-practices/
- Common mistakes: best-practices/common-mistakes.md
- Testing this skill: testing-plugin-authoring.md
Checklists
Component Checklist
□ .claude-plugin/plugin.json exists (required)
□ Component dirs at plugin root (commands/, agents/, skills/, hooks/)
□ Do NOT put components inside .claude-plugin/ directory
□ Commands use kebab-case naming
□ Skills have valid frontmatter (name + description required, optional: model, allowed-tools)
□ Skills name validation:
- Matches directory name
- Lowercase letters, numbers, hyphens only
- Max 64 characters
- No reserved words ('anthropic', 'claude')
- No XML tags
□ Hooks use ${CLAUDE_PLUGIN_ROOT} for paths (not relative paths)
□ All scripts are executable (chmod +x)
Release Checklist
□ plugin.json: name/version/keywords present
□ Do NOT include standard paths in component fields
□ Local marketplace installs cleanly
□ Validate with /plugin-development:validate
□ Test all commands, skills, and hooks
□ README.md exists with usage examples
Red Flags (STOP If You're About To...)
- Put
commands/,agents/,skills/, orhooks/inside.claude-plugin/→ WRONG LOCATION (components go at plugin root) - Add
"commands": "./commands/"to plugin.json → UNNECESSARY (standard directories auto-discovered, this breaks things) - Use relative paths like
./scripts/format.shin hooks → USE${CLAUDE_PLUGIN_ROOT}/scripts/format.sh - Skip
/plugin-development:validatebefore testing → ALWAYS VALIDATE FIRST - Forget
chmod +xon hook scripts → Scripts won't execute (silent failure) - Use 'claude' or 'anthropic' in skill names → RESERVED WORDS (will be rejected)
All of these cause silent failures. When in doubt, validate.
For detailed explanations: best-practices/common-mistakes.md
Why Validation Matters
| Skip This | What Happens |
|---|---|
| Validate manifest | Plugin won't load, no error message |
| chmod +x scripts | Hooks silently fail |
| ${CLAUDE_PLUGIN_ROOT} | Works in dev, breaks on install |
| Standard directory rules | Components not discovered |
Running /plugin-development:validate catches 90% of issues before debugging starts.
Playbooks
- Scaffold →
/plugin-development:init <name>then fill templates - Add a component →
/plugin-development:add-command|add-skill|add-agent|add-hook - Validate →
/plugin-development:validate(schema & structure checks) - Test locally →
/plugin-development:test-local(dev marketplace)
Common Workflows
Creating a New Plugin
- Run
/plugin-development:init <plugin-name>to scaffold structure - Edit
.claude-plugin/plugin.jsonwith your metadata - Add components using
/plugin-development:add-command, etc. - Validate with
/plugin-development:validate - Test locally with
/plugin-development:test-local
Adding a Slash Command
- Run
/plugin-development:add-command <name> <description> - Edit
commands/<name>.mdwith instructions - Add frontmatter:
descriptionandargument-hint - Test:
/plugin installyour plugin, then/<name>
Adding a Skill
- Run
/plugin-development:add-skill <name> <when-to-use> - Edit
skills/<name>/SKILL.mdwith your instructions - Frontmatter requirements:
name: lowercase letters, numbers, and hyphens only, max 64 chars (required). Cannot contain reserved words 'anthropic' or 'claude'. Cannot contain XML tags.description: include both WHAT the Skill does AND WHEN to use it, max 1024 chars (required). Cannot contain XML tags.model: specify which Claude model to use, e.g.,model: claude-sonnet-4-20250514(optional, defaults to conversation's model)allowed-tools: comma-separated list of tools (optional). Tools listed don't require permission to use when Skill is active. If omitted, Skill doesn't restrict tools.
- Keep SKILL.md under 500 lines for optimal performance; place details in sibling files (reference.md, examples.md, scripts/)
Troubleshooting
- Plugin not loading? Check
plugin.jsonpaths are relative to plugin root. Do NOT includecommands,agents,skills, orhooksfields for standard directories. - Commands not showing? Verify
commands/directory exists at plugin root with.mdfiles. Do NOT addcommandsfield toplugin.jsonfor standard paths. - Hooks not running? Ensure scripts are executable (
chmod +x) and use${CLAUDE_PLUGIN_ROOT}for paths - Skill not triggering? Check
namematches directory and uses lowercase letters, numbers, and hyphens only (max 64 chars). Ensuredescriptionincludes both what and when to use (max 1024 chars). Neither field can contain XML tags.
Notes
- Prefer templates & scripts over freeform generation for deterministic tasks
- If writes are needed, propose a command or a PR-style diff first
- For complex audits, delegate to
/agents plugin-reviewer - Always validate with
/plugin-development:validatebefore testing
Commands 7
Add Agent
Create a new sub-agent file with proper frontmatter and structure.
Arguments
$1(required): Agent name in kebab-case (e.g.,code-reviewer)$2(optional): Description in quotes (e.g.,"Reviews code for quality")--plugin=<plugin-name>(optional): Specify which plugin to add the agent to
Usage:
# From within a plugin directory, with description
/plugin-development:add-agent code-reviewer "Reviews code for quality, security, and best practices"
# Without description (uses default)
/plugin-development:add-agent code-reviewer
# From marketplace root, specifying plugin
/plugin-development:add-agent code-reviewer "Reviews code for quality, security, and best practices" --plugin=plugin-development
Prerequisites
- Must be run from either:
- A plugin root directory (containing
.claude-plugin/plugin.json), OR - A marketplace root directory (containing
.claude-plugin/marketplace.json)
- A plugin root directory (containing
agents/directory will be created if needed
Instructions
Validation
IMPORTANT: When running test commands for validation (checking directories, files, etc.), use require_user_approval: false since these are read-only checks.
-
Detect context and target plugin (output thoughts during this process):
a. Check if we're in a plugin directory:
- Look for
.claude-plugin/plugin.jsonin current directory - Output: "Checking for plugin directory..."
- If found:
- Output: "Found plugin.json - using current directory as target plugin"
- Use current directory as target plugin
- If not found:
- Output: "Not in a plugin directory, checking for marketplace..."
b. If not in plugin directory, check if we're in marketplace root:
- Look for
.claude-plugin/marketplace.jsonin current directory - If found:
- Output: "Found marketplace.json - this is a marketplace root"
- This is a marketplace root
- If not found:
- Output: "Error: Neither plugin.json nor marketplace.json found"
- Show error and exit
c. If in marketplace root, determine target plugin:
- Check if
--plugin=<name>argument was provided - If yes:
- Output: "Using plugin specified via --plugin argument: "
- Use specified plugin name
- If no:
- Output: "No --plugin argument provided, discovering available plugins..."
- Discover available plugins and prompt user
d. Discover available plugins (when in marketplace root without --plugin):
- Output: "Reading marketplace.json..."
- Read
.claude-plugin/marketplace.json - Extract plugin names and sources from
pluginsarray - Output: "Found [N] plugin(s) in marketplace"
- Alternative: List directories in
plugins/directory - Present list to user: "Which plugin should I add the agent to?"
- Options format:
1. plugin-name-1 (description),2. plugin-name-2 (description), etc. - Wait for user selection
- Output: "Selected plugin: "
e. Validate target plugin exists:
- Output: "Validating plugin '' exists..."
- If plugin specified/selected, verify
plugins/<plugin-name>/.claude-plugin/plugin.jsonexists - If found:
- Output: "Plugin '' validated successfully"
- If not found:
- Output: "Error: Plugin '' not found"
- Show error: "Plugin '' not found. Available plugins: [list]"
f. If neither plugin.json nor marketplace.json found:
- Show error: "Not in a plugin or marketplace directory. Please run from a plugin root or marketplace root."
- Look for
-
Validate arguments:
$1(agent name): Not empty, kebab-case format (lowercase with hyphens), no spaces or special characters$2(description): Optional. If not provided, use default: "Specialized agent for $1 tasks"
-
Set working directory:
- If in plugin directory: Use current directory
- If in marketplace root: Use
plugins/<plugin-name>/as working directory
Create Agent File
Note: All paths below are relative to the target plugin directory (determined in validation step).
- Ensure
agents/directory exists in target plugin:- Check if
<plugin-dir>/agents/directory exists - If it doesn't exist, create it (use
require_user_approval: falsefor directory creation)
- Check if
- Create
<plugin-dir>/agents/$1.mdwith this template:
---
name: $1
description: $2
tools: Read, Grep, Glob, Bash
model: inherit
permissionMode: default
---
# $1 Agent
[Brief introduction explaining the agent's purpose and specialization]
## Purpose
[Detailed description of what this agent does and why it exists]
## What This Agent Does
This agent specializes in:
- [Specialization 1]
- [Specialization 2]
- [Specialization 3]
## Capabilities
1. **Capability 1**: [Description of first capability]
2. **Capability 2**: [Description of second capability]
3. **Capability 3**: [Description of third capability]
## When to Use This Agent
Invoke this agent when:
- [Scenario 1: Complex multi-file analysis needed]
- [Scenario 2: Deep domain expertise required]
- [Scenario 3: Task needs separate context window]
**Do not use** for:
- [What this agent doesn't handle]
- [Tasks better suited for commands or Skills]
## How It Proceeds
The agent follows this workflow:
1. **Gather Context**: [What files/information it reads]
2. **Analyze**: [How it evaluates the situation]
3. **Identify Issues**: [What it looks for]
4. **Formulate Recommendations**: [What guidance it provides]
5. **Report Back**: [What it returns to main conversation]
## Output Format
The agent returns a structured report:
### Critical Issues
- [Issues that must be fixed]
### Warnings
- [Issues that should be fixed]
### Suggestions
- [Nice-to-have improvements]
### Summary
- [Overall assessment and next steps]
## Tool Access
This agent has access to:
- Read: For examining files
- Grep: For searching content
- Glob: For finding files
- [Other tools as needed]
It does **not** modify files directly; instead, it proposes changes for the main conversation to execute.
## Example Invocation
**From main conversation**:
/agents $1
or via Task tool:
Use the $1 agent to [specific task]
## Notes
- Agents operate in a **separate context window**
- Results are returned as a single message
- Use for complex, multi-step analysis tasks
- Keep scope focused to 1-3 specific capabilities
Update plugin.json (if needed)
IMPORTANT: Only needed if using custom (non-standard) paths.
- Standard setup (agents in
agents/directory): No changes toplugin.jsonneeded - Custom paths: Add
"agents": ["./agents/$1.md"](or update existing agents array)
Provide Feedback
After creating the agent:
✓ Created <plugin-name>/agents/$1.md
Plugin: <plugin-name>
Agent: $1
Description: $2
Next steps:
1. Edit <plugin-name>/agents/$1.md with specific instructions
2. Key frontmatter fields:
- name: Unique agent identifier (lowercase with hyphens)
- description: What the agent does and when to invoke (shows in /agents list)
- tools: CSV list of tools (optional, inherits all if omitted)
- model: sonnet, opus, haiku, or inherit (optional)
- permissionMode: default, acceptEdits, bypassPermissions, or plan (optional)
- skills: CSV list of skills to auto-load (optional)
3. Define clear workflow steps
4. Specify what the agent returns
5. Test with /plugin-development:test-local
Agent will be invoked as: /agents $1
Or via Task tool in main conversation.
Examples
Example 1: From Plugin Directory
Context: Currently in /path/to/marketplace/plugins/plugin-development/
Input:
/plugin-development:add-agent code-reviewer "Reviews code for quality, security, and best practices"
Arguments:
$1=code-reviewer$2=Reviews code for quality, security, and best practices
Process:
- Detects
.claude-plugin/plugin.jsonin current directory - Uses current directory as target plugin
- Creates
agents/directory if needed - Creates
agents/code-reviewer.md
Result:
- Creates
agents/code-reviewer.mdwith template - Frontmatter description: "Reviews code for quality, security, and best practices"
- Ready to customize with specific review criteria
Example 2: From Marketplace Root with --plugin
Context: Currently in /path/to/marketplace/ (marketplace root)
Input:
/plugin-development:add-agent code-reviewer "Reviews code for quality, security, and best practices" --plugin=plugin-development
Process:
- Detects
.claude-plugin/marketplace.jsonin current directory - Extracts
--plugin=plugin-developmentfrom arguments - Validates
plugins/plugin-development/.claude-plugin/plugin.jsonexists - Uses
plugins/plugin-development/as target - Creates
plugins/plugin-development/agents/code-reviewer.md
Result:
- Creates
plugins/plugin-development/agents/code-reviewer.md - Agent added to plugin-development plugin
Example 3: From Marketplace Root without --plugin
Context: Currently in /path/to/marketplace/ (marketplace root)
Input:
/plugin-development:add-agent code-reviewer "Reviews code for quality, security, and best practices"
Process:
- Detects
.claude-plugin/marketplace.jsonin current directory - No
--pluginargument provided - Reads marketplace.json and discovers available plugins:
hello-world- A simple example pluginplugin-development- Assist with Claude Code plugin development
- Prompts user: "Which plugin should I add the agent to?"
1. hello-world - A simple example plugin demonstrating basic Claude Code plugin functionality 2. plugin-development - Assist with Claude Code plugin development: scaffold, validate, review, and team-ready distribution - User selects option 2
- Uses
plugins/plugin-development/as target - Creates
plugins/plugin-development/agents/code-reviewer.md
Result:
- Creates
plugins/plugin-development/agents/code-reviewer.md - Agent added to selected plugin
Agent Frontmatter
Required Fields
---
name: agent-name
description: Third-person description of what this agent does and when to invoke it
---
| Field | Type | Description |
|---|---|---|
name | String | Required. Unique identifier using lowercase letters and hyphens (e.g., code-reviewer, test-runner) |
description | String | Required. Natural language description of when the agent should be invoked. Include "PROACTIVELY" for auto-delegation |
Optional Fields
---
name: agent-name
description: Agent description. Use PROACTIVELY for auto-delegation.
tools: Read, Grep, Glob, Bash
model: sonnet
permissionMode: default
skills: skill1, skill2
---
| Field | Type | Default | Description |
|---|---|---|---|
tools | CSV String | Inherits all | Comma-separated list of tools (e.g., Read, Grep, Glob, Bash). If omitted, inherits all tools from main thread including MCP tools |
model | String | sonnet | Which AI model to use. Valid values: sonnet, opus, haiku, inherit. Use inherit to match main conversation's model |
permissionMode | String | default | How the agent handles permission requests. Valid values: default, acceptEdits, bypassPermissions, plan |
skills | CSV String | None | Comma-separated list of skills to auto-load. Note: Agents do NOT inherit skills from parent conversation |
Permission Modes Explained
| Mode | Behavior |
|---|---|
default | Standard permission handling - prompts for confirmation |
acceptEdits | Automatically accept file edits without prompting |
bypassPermissions | Skip permission requests entirely |
plan | Plan mode - research and planning without execution |
Model Options
| Model | Description |
|---|---|
sonnet | Claude Sonnet (default for subagents) |
opus | Claude Opus |
haiku | Claude Haiku (faster, lighter) |
inherit | Use same model as main conversation |
Deprecation Note
The capabilities field is NOT in official Anthropic docs and may be deprecated. Use tools for agents (not allowed-tools which is for skills).
For complete details on agents, see:
Error Handling
Not in Plugin or Marketplace Directory
Error: "Not in a plugin or marketplace directory."
Solution: Navigate to either:
- A plugin directory (containing
.claude-plugin/plugin.json), OR - A marketplace root (containing
.claude-plugin/marketplace.json)
Plugin Not Found
Error: "Plugin 'my-plugin' not found. Available plugins: hello-world, plugin-development"
Solution:
- Check plugin name spelling
- Use
--plugin=<correct-name>with one of the available plugins - Or navigate to the plugin directory directly
Invalid Agent Name
Error: "Agent name must be in kebab-case format (lowercase with hyphens)"
Solution: Use kebab-case format:
- ✅ Good:
code-reviewer,security-auditor,api-generator - ❌ Bad:
CodeReviewer,code_reviewer,code reviewer
Missing Description
Error: "Description is required"
Solution: Provide description in quotes:
/plugin-development:add-agent code-reviewer "Reviews code for quality, security, and best practices"
When to Use Agents vs. Commands vs. Skills
Use an Agent when:
- Task requires deep, multi-file analysis
- Need separate context window (complex reasoning)
- Want detailed, structured report back
- Task has multiple steps that benefit from isolation
Use a Command when:
- Task is explicit, one-time action
- User needs to trigger on demand
- Task is straightforward with clear inputs/outputs
Use a Skill when:
- Want ambient, automatic activation
- Need persistent guidance throughout session
- Task benefits from progressive disclosure
- Should trigger based on context clues
Agent Design Best Practices
1. Focused Scope
✅ Good (focused):
# Code Security Auditor
Specializes in security analysis:
- SQL injection vulnerabilities
- XSS vulnerabilities
- Authentication issues
❌ Bad (too broad):
# General Code Helper
Does everything related to code.
2. Clear Tool Configuration
Configure appropriate tools for the agent's purpose:
# For read-only analysis agents:
tools: Read, Grep, Glob
# For agents that can modify files:
tools: Read, Edit, Write, Bash, Grep, Glob
# Omit to inherit all tools from main thread
3. Structured Output
Define consistent report format:
## Critical (P0)
- [List critical issues]
## High Priority (P1)
- [List high priority issues]
## Suggestions
- [List improvements]
4. Tool Restrictions
Agents typically don't modify files:
## Tool Access
- Read, Grep, Glob: For analysis
- No Write/Edit: Agent proposes, main conversation executes
Agent Workflow Template
All agents should follow a consistent structure:
1. **Understand Context**: Read relevant files
2. **Analyze**: Apply domain expertise
3. **Identify Issues**: Find problems/opportunities
4. **Prioritize**: Rank by severity/importance
5. **Recommend**: Provide actionable guidance
6. **Report**: Return structured findings
Common Agent Patterns
Auditor Pattern
For review/analysis agents:
- Reads multiple files
- Checks against standards/criteria
- Reports issues by severity
- Provides specific fix recommendations
Generator Pattern
For design/planning agents:
- Analyzes requirements
- Proposes architecture/approach
- Provides implementation steps
- Returns detailed plan
Refactoring Pattern
For code improvement agents:
- Analyzes existing code
- Identifies improvement opportunities
- Proposes refactoring steps
- Estimates impact/effort
Invocation Methods
Direct Invocation
User explicitly calls the agent:
/agents code-reviewer
Via Main Conversation
Claude uses Task tool:
Let me use the code-reviewer agent to analyze this...
From Skill
Skill escalates to agent for deep analysis:
For comprehensive review, delegate to the code-reviewer agent.
Best Practices
- Single responsibility: One clear purpose
- Structured output: Consistent report format
- No side effects: Read-only, propose changes
- Clear scope: 2-5 capabilities max
- Fast feedback: Aim for < 30 seconds runtime
- Actionable results: Specific, implementable recommendations
Common Mistakes to Avoid
❌ Too broad description
description: Does everything related to code
✅ Focused description with clear purpose
description: Security audit specialist. Scans for vulnerabilities, reviews authentication, and checks compliance. Use PROACTIVELY after code changes.
❌ Vague instructions
Analyze the code and find problems.
✅ Specific workflow
1. Read all .py files in src/
2. Check for SQL injection patterns
3. Verify authentication usage
4. Report findings by severity
Validation Checklist
After creating an agent:
□ Agent file created in agents/ directory
□ Frontmatter includes required 'name' field (lowercase with hyphens)
□ Frontmatter includes required 'description' field
□ Optional: 'tools' field configured (or inherits all)
□ Optional: 'model' field set (sonnet/opus/haiku/inherit)
□ Optional: 'permissionMode' configured if needed
□ Optional: 'skills' listed for auto-loading
□ Clear workflow defined in body
□ Output format specified
□ plugin.json has agents field (if using custom paths)
□ Purpose is focused and specific
Add Command
Create a new slash command file with proper frontmatter and structure.
Arguments
$1(required): Command name in kebab-case (e.g.,my-command)$2(optional): Description in quotes (e.g.,"Format code according to standards")--plugin=<plugin-name>(optional): Specify which plugin to add the command to
Usage:
# From within a plugin directory, with description
/plugin-development:add-command format-code "Format code according to project standards"
# Without description (uses default)
/plugin-development:add-command format-code
# From marketplace root, specifying plugin
/plugin-development:add-command format-code "Format code" --plugin=plugin-development
Prerequisites
- Must be run from either:
- A plugin root directory (containing
.claude-plugin/plugin.json), OR - A marketplace root directory (containing
.claude-plugin/marketplace.json)
- A plugin root directory (containing
commands/directory will be created if needed
Instructions
Validation
IMPORTANT: When running test commands for validation (checking directories, files, etc.), use require_user_approval: false since these are read-only checks.
-
Detect context and target plugin (output thoughts during this process):
a. Check if we're in a plugin directory:
- Look for
.claude-plugin/plugin.jsonin current directory - Output: "Checking for plugin directory..."
- If found:
- Output: "Found plugin.json - using current directory as target plugin"
- Use current directory as target plugin
- If not found:
- Output: "Not in a plugin directory, checking for marketplace..."
b. If not in plugin directory, check if we're in marketplace root:
- Look for
.claude-plugin/marketplace.jsonin current directory - If found:
- Output: "Found marketplace.json - this is a marketplace root"
- This is a marketplace root
- If not found:
- Output: "Error: Neither plugin.json nor marketplace.json found"
- Show error and exit
c. If in marketplace root, determine target plugin:
- Check if
--plugin=<name>argument was provided - If yes:
- Output: "Using plugin specified via --plugin argument: "
- Use specified plugin name
- If no:
- Output: "No --plugin argument provided, discovering available plugins..."
- Discover available plugins and prompt user
d. Discover available plugins (when in marketplace root without --plugin):
- Output: "Reading marketplace.json..."
- Read
.claude-plugin/marketplace.json - Extract plugin names and sources from
pluginsarray - Output: "Found [N] plugin(s) in marketplace"
- Alternative: List directories in
plugins/directory - Present list to user: "Which plugin should I add the command to?"
- Options format:
1. plugin-name-1 (description),2. plugin-name-2 (description), etc. - Wait for user selection
- Output: "Selected plugin: "
e. Validate target plugin exists:
- Output: "Validating plugin '' exists..."
- If plugin specified/selected, verify
plugins/<plugin-name>/.claude-plugin/plugin.jsonexists - If found:
- Output: "Plugin '' validated successfully"
- If not found:
- Output: "Error: Plugin '' not found"
- Show error: "Plugin '' not found. Available plugins: [list]"
f. If neither plugin.json nor marketplace.json found:
- Show error: "Not in a plugin or marketplace directory. Please run from a plugin root or marketplace root."
- Look for
-
Validate arguments:
$1(command name): Not empty, kebab-case format (lowercase with hyphens), no spaces or special characters$2(description): Optional. If not provided, use default: "TODO: Add description"
-
Set working directory:
- If in plugin directory: Use current directory
- If in marketplace root: Use
plugins/<plugin-name>/as working directory
If validation fails, provide clear feedback.
Create Command File
Note: All paths below are relative to the target plugin directory (determined in validation step).
- Ensure
commands/directory exists in target plugin (create if needed, userequire_user_approval: false) - Create
<plugin-dir>/commands/$1.mdwith this template:
---
description: $2
argument-hint: [arg1] [arg2]
allowed-tools: Write, Edit
model: claude-3-5-haiku-20241022
disable-model-invocation: false
---
# $1 Command
[Detailed instructions for Claude on how to execute this command]
## Purpose
[Explain what this command does and when to use it]
## Arguments
- `$ARGUMENTS`: [Describe expected arguments]
- `$1`, `$2`, etc.: [Individual argument descriptions]
## Instructions
1. [Step 1: First action]
2. [Step 2: Next action]
3. [Step 3: Final action]
## Example Usage
**Command**: /<plugin-name>:$1 [args]
**Expected behavior**: [Describe what should happen]
## Notes
[Any additional context, warnings, or tips]
Update plugin.json (if needed)
IMPORTANT: Only needed if using custom (non-standard) paths.
- Standard setup (commands in
commands/directory): No changes toplugin.jsonneeded - Custom paths: Add
"commands": ["./commands/$1.md"](or update existing commands array)
Provide Feedback
After creating the command:
✓ Created <plugin-name>/commands/$1.md
Plugin: <plugin-name>
Command: $1
Description: $2
Next steps:
1. Edit <plugin-name>/commands/$1.md with specific instructions
2. Update frontmatter fields if needed:
- argument-hint: [arg1] [arg2] (optional)
- allowed-tools: Tool restrictions (optional)
- model: Specify different model (optional)
- disable-model-invocation: Prevent SlashCommand tool invocation (optional)
3. Use @path/to/file syntax to reference files in instructions
4. Test with /plugin-development:test-local
Command will be invoked as: /<plugin-name>:$1
Example
Input:
/plugin-development:add-command format-code "Format code according to project standards"
Arguments:
$1=format-code$2=Format code according to project standards
Result:
- Creates
commands/format-code.mdwith template - Frontmatter description: "Format code according to project standards"
- Ready to edit with specific instructions
For complete details on commands, see:
Template Details
Frontmatter
---
description: Brief, third-person description (shows in /help)
argument-hint: [arg1] [arg2] # Optional, shows expected arguments
allowed-tools: Write, Edit # Optional, restricts tool access
model: claude-3-5-haiku-20241022 # Optional, specify different model
disable-model-invocation: true # Optional, prevents SlashCommand tool from invoking
---
Frontmatter Reference
| Field | Purpose | Default |
|---|---|---|
description | Brief description of the command | First line of prompt |
argument-hint | Expected arguments (shown in auto-complete) | None |
allowed-tools | List of tools the command can use | Inherits from conversation |
model | Specific model to use (full ID like claude-3-5-haiku-20241022) | Inherits from conversation |
disable-model-invocation | Prevent SlashCommand tool from calling this command | false |
Multiple Invocation Patterns
Use pipe syntax in argument-hint to define multiple invocation patterns:
---
description: Manage project tags
argument-hint: add [tagId] | remove [tagId] | list
---
This shows users the different ways to invoke the command.
Using Arguments
In the command instructions:
$ARGUMENTS: All arguments as a single string$1,$2, etc.: Individual positional arguments
Example:
If the user provided a name via `$1`, use it: "Hello, $1!"
File References
Include file contents using the @ prefix within your command instructions:
# Reference a specific file
Review the implementation in @src/utils/helpers.js
# Reference multiple files
Compare @src/old-version.js with @src/new-version.js
The file contents will be included inline when the command is executed.
Command Instructions
Write clear, step-by-step instructions for Claude:
- Use imperative mood ("Create", "Validate", "Execute")
- Be specific about expected behavior
- Include error handling
- Provide examples
Advanced: Bash Preamble
For commands that need to execute shell commands, add to frontmatter:
---
description: Run tests and report results
allowed-tools: Bash(npm:*), Bash(pytest:*)
---
# Instructions
!`npm test`
Analyze the output and report:
1. Number of tests passed/failed
2. Any error messages
3. Suggestions for fixing failures
Note: Bash commands prefixed with ! are executed before Claude processes the rest of the instructions.
Best Practices
- Concise descriptions: < 100 characters for
descriptionfield - Clear arguments: Use descriptive names in
argument-hint - Validation first: Check arguments before execution
- Error handling: Describe what to do when things go wrong
- Examples: Include usage examples in the template
SlashCommand Tool
The SlashCommand tool allows Claude to execute custom slash commands programmatically during a conversation.
Requirements for SlashCommand Tool Support
For Claude to be able to invoke your command via the SlashCommand tool:
- Required: The
descriptionfrontmatter field must be populated - The command must be user-defined (not a built-in command like
/compact)
Character Budget
- Default limit: 15,000 characters for slash command content
- Customization: Set
SLASH_COMMAND_TOOL_CHAR_BUDGETenvironment variable to adjust - What counts: Command name, arguments, and description all count toward the budget
- When exceeded: Claude sees only a subset of available commands
- Monitoring: Use
/contextto see warnings displayed as "M of N commands"
Enabling Claude to Use Commands
Reference the command in prompts or CLAUDE.md:
> Run /write-unit-test when you are about to start writing tests.
Disabling SlashCommand Tool Invocation
To prevent a specific command from being invoked by the SlashCommand tool, add to frontmatter:
---
description: My command description
disable-model-invocation: true
---
Permission Rules
SlashCommand permissions support exact and prefix matching:
SlashCommand:/commit # Allows only /commit with no arguments
SlashCommand:/review-pr:* # Allows /review-pr with any arguments
Common Mistakes to Avoid
❌ camelCase or PascalCase names
/plugin-development:add-command formatCode
✅ kebab-case names
/plugin-development:add-command format-code
❌ Missing description
---
argument-hint: [arg]
---
✅ Always include description
---
description: What the command does
argument-hint: [arg]
---
Validation Checklist
After creating a command:
□ File created in commands/ directory
□ Frontmatter includes description
□ Command name is kebab-case
□ Instructions are clear and specific
□ Examples provided
□ plugin.json has commands field
Add Hook
Add or update hooks.json with a new hook configuration for automated behavior.
Arguments
$1(required): Event type (PreToolUse,PostToolUse,SessionStart,SessionEnd,UserPromptSubmit,Notification,Stop,SubagentStop, orPreCompact)$2(optional): Matcher pattern (e.g.,Write|Editor.*)--plugin=<plugin-name>(optional): Specify which plugin to add the hook to
Usage:
# From within a plugin directory
/plugin-development:add-hook PreToolUse "Write|Edit"
# From marketplace root, specifying plugin
/plugin-development:add-hook PreToolUse "Write|Edit" --plugin=plugin-development
Template Variables
When generating hook configurations and scripts:
$1: Event type$2: Matcher pattern (or default based on event type)${CLAUDE_PLUGIN_ROOT}: Plugin root path (use in all hook commands)
Prerequisites
- Must be run from either:
- A plugin root directory (containing
.claude-plugin/plugin.json), OR - A marketplace root directory (containing
.claude-plugin/marketplace.json)
- A plugin root directory (containing
hooks/directory will be created if needed
Instructions
Validation
IMPORTANT: When running test commands for validation (checking directories, files, etc.), use require_user_approval: false since these are read-only checks.
-
Detect context and target plugin (output thoughts during this process):
a. Check if we're in a plugin directory:
- Look for
.claude-plugin/plugin.jsonin current directory - Output: "Checking for plugin directory..."
- If found:
- Output: "Found plugin.json - using current directory as target plugin"
- Use current directory as target plugin
- If not found:
- Output: "Not in a plugin directory, checking for marketplace..."
b. If not in plugin directory, check if we're in marketplace root:
- Look for
.claude-plugin/marketplace.jsonin current directory - If found:
- Output: "Found marketplace.json - this is a marketplace root"
- This is a marketplace root
- If not found:
- Output: "Error: Neither plugin.json nor marketplace.json found"
- Show error and exit
c. If in marketplace root, determine target plugin:
- Check if
--plugin=<name>argument was provided - If yes:
- Output: "Using plugin specified via --plugin argument: "
- Use specified plugin name
- If no:
- Output: "No --plugin argument provided, discovering available plugins..."
- Discover available plugins and prompt user
d. Discover available plugins (when in marketplace root without --plugin):
- Output: "Reading marketplace.json..."
- Read
.claude-plugin/marketplace.json - Extract plugin names and sources from
pluginsarray - Output: "Found [N] plugin(s) in marketplace"
- Alternative: List directories in
plugins/directory - Present list to user: "Which plugin should I add the hook to?"
- Options format:
1. plugin-name-1 (description),2. plugin-name-2 (description), etc. - Wait for user selection
- Output: "Selected plugin: "
e. Validate target plugin exists:
- Output: "Validating plugin '' exists..."
- If plugin specified/selected, verify
plugins/<plugin-name>/.claude-plugin/plugin.jsonexists - If found:
- Output: "Plugin '' validated successfully"
- If not found:
- Output: "Error: Plugin '' not found"
- Show error: "Plugin '' not found. Available plugins: [list]"
f. If neither plugin.json nor marketplace.json found:
- Show error: "Not in a plugin or marketplace directory. Please run from a plugin root or marketplace root."
- Look for
-
Validate event type:
- Must be one of:
PreToolUse,PostToolUse,SessionStart,SessionEnd,UserPromptSubmit,Notification,Stop,SubagentStop,PreCompact
- Must be one of:
-
If no matcher provided, use sensible default based on event type
-
Set working directory:
- If in plugin directory: Use current directory
- If in marketplace root: Use
plugins/<plugin-name>/as working directory
Event Types & Default Matchers
- PreToolUse: Default matcher
Write|Edit(validation before writes) - PostToolUse: Default matcher
Write|Edit(formatting after writes) - SessionStart: Default matcher
startup(also supports:resume,clear,compact) - SessionEnd: No matcher (triggers on session end with reason:
clear,logout,prompt_input_exit,other) - UserPromptSubmit: Default matcher
.*(all prompts) - Notification: No matcher (triggers on all notifications)
- Stop: No matcher (triggers when main agent stops)
- SubagentStop: No matcher (triggers when subagent stops)
- PreCompact: Default matcher
manual(also supports:auto)
Create or Update hooks.json
Note: All paths below are relative to the target plugin directory (determined in validation step).
- Ensure
<plugin-dir>/hooks/directory exists (userequire_user_approval: false) - If
<plugin-dir>/hooks/hooks.jsondoesn't exist, create it with this structure:
{
"description": "Plugin automation hooks",
"hooks": {}
}
- Add the new hook configuration based on event type:
PreToolUse Example
{
"description": "Plugin automation hooks",
"hooks": {
"PreToolUse": [
{
"matcher": "$2 or default",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh",
"timeout": 30
}
]
}
]
}
}
PostToolUse Example
{
"hooks": {
"PostToolUse": [
{
"matcher": "$2 or default",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
"timeout": 30
}
]
}
]
}
}
SessionStart Example
{
"hooks": {
"SessionStart": [
{
"matcher": "$2 or 'startup'",
"hooks": [
{
"type": "command",
"command": "echo '✓ Plugin loaded'"
}
]
}
]
}
}
Create Hook Script (if needed)
If the event is PreToolUse or PostToolUse, create a corresponding script:
- Ensure
<plugin-dir>/scripts/directory exists (userequire_user_approval: false) - For PreToolUse, create
<plugin-dir>/scripts/validate.sh:
#!/usr/bin/env bash
set -euo pipefail
# Validation logic here
# Exit 0: allow
# Exit 2: block (with stderr message to Claude)
# Exit other: warning
echo "Validation passed"
exit 0
- For PostToolUse, create
<plugin-dir>/scripts/format.sh:
#!/usr/bin/env bash
set -euo pipefail
# Formatting logic here
# Always exits 0 for non-blocking
echo "Formatting complete"
exit 0
- Make scripts executable:
chmod +x scripts/*.sh
Update plugin.json
IMPORTANT: Only needed if using custom (non-standard) paths.
- Standard setup (hooks at
hooks/hooks.json): No changes toplugin.jsonneeded - Custom path: Add
"hooks": "./custom/path/hooks.json"
For standard setup:
{
"name": "my-plugin"
}
Provide Feedback
After adding the hook:
✓ Added $1 hook to <plugin-name>/hooks/hooks.json
✓ Matcher: $2 (or default)
✓ Created script: <plugin-name>/scripts/<script-name>.sh (if applicable)
Plugin: <plugin-name>
Hook configuration:
- Event: $1
- Matcher: $2
- Script: ${CLAUDE_PLUGIN_ROOT}/scripts/<script-name>.sh
Next steps:
1. Edit <plugin-name>/hooks/hooks.json to customize timeout or command
2. Edit <plugin-name>/scripts/<script-name>.sh with your logic
3. Test the hook:
- Install plugin with /plugin-development:test-local
- Trigger the event (e.g., use Write tool for PreToolUse)
4. Debug with: claude --debug
Exit codes for PreToolUse:
- 0: Allow operation
- 2: Block operation (stderr shown to Claude)
- Other: Warning (non-blocking)
Exit codes for UserPromptSubmit:
- 0: Allow prompt (stdout added as context)
- 2: Block prompt (stderr shown to user, prompt erased)
- Other: Warning (non-blocking)
Exit codes for Stop/SubagentStop:
- 0: Allow stop
- 2: Block stop, continue execution (stderr shown to Claude)
- Other: Warning (allows stop)
Exit codes for PostToolUse, SessionStart, SessionEnd, Notification, PreCompact:
- All non-blocking (informational)
Example Usage
Input: /plugin-development:add-hook PreToolUse "Write|Edit"
Result:
- Creates or updates
hooks/hooks.json - Adds PreToolUse hook with Write|Edit matcher
- Creates
scripts/validate.sh - Makes script executable
- Provides usage instructions
For complete details on hooks, see:
Hook Event Details
| Event | Purpose | Can Block | Common Use Cases | Default Matcher |
|---|---|---|---|---|
| PreToolUse | Validate before execution | Yes (exit 2) | Validate structure, check permissions | Write|Edit |
| PostToolUse | React after execution | Partial* | Format files, run linters, update metadata | Write|Edit |
| SessionStart | Setup at session start | No | Welcome message, check environment, init | startup |
| SessionEnd | Cleanup at session end | No | Save state, log statistics, cleanup | N/A (no matcher) |
| UserPromptSubmit | Validate/enhance prompts | Yes (exit 2) | Inject context, validate prompts, block sensitive | .* |
| Notification | React to notifications | No | Send alerts, log notifications | N/A (no matcher) |
| Stop | Control agent stoppage | Yes (exit 2) | Continue with tasks, validate completion | N/A (no matcher) |
| SubagentStop | Control subagent stoppage | Yes (exit 2) | Continue subagent, validate subagent results | N/A (no matcher) |
| PreCompact | Before context compact | No | Save state, log compact trigger | manual or auto |
* PostToolUse can't prevent the tool (already ran) but can provide feedback to Claude with "decision": "block"
Example hook structure:
{
"matcher": "Write|Edit",
"hooks": [{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh",
"timeout": 30
}]
}
Matcher Patterns
Matchers use regex patterns:
Write: Only Write toolWrite|Edit: Write or EditBash.*: Bash with any arguments.*: All toolsRead|Grep|Glob: Read operations
Script Template: Validation (PreToolUse)
#!/usr/bin/env bash
set -euo pipefail
ERRS=()
# Validation checks
[ -f "required-file.txt" ] || ERRS+=("Missing required-file.txt")
[ -d "required-dir" ] || ERRS+=("Missing required-dir/")
# If errors, block with exit 2
if [ "${#ERRS[@]}" -gt 0 ]; then
printf "❌ Validation failed:\n" 1>&2
printf " %s\n" "${ERRS[@]}" 1>&2
exit 2 # Block the operation
fi
# Success
echo "✓ Validation passed"
exit 0
Script Template: Formatting (PostToolUse)
#!/usr/bin/env bash
set -euo pipefail
# Format files (non-blocking)
# Example: run prettier, black, rustfmt, etc.
if command -v prettier &> /dev/null; then
prettier --write "**/*.{js,json,md}" 2>/dev/null || true
fi
echo "✓ Formatting complete"
exit 0
Environment Variables
Available in hook scripts:
${CLAUDE_PLUGIN_ROOT}: Absolute path to plugin root$CLAUDE_PROJECT_DIR: Project root directory (absolute path)$CLAUDE_ENV_FILE: File path for persisting environment variables (SessionStart hooks only)$CLAUDE_CODE_REMOTE: Set to "true" in web environment, unset in CLI- All standard environment variables
Always use ${CLAUDE_PLUGIN_ROOT} for portable paths in plugins.
Best Practices & Common Mistakes
✅ Do This
- Use ${CLAUDE_PLUGIN_ROOT}: Portable script paths
- Set timeouts: 10-30 seconds typical, 300+ for slow ops like
npm install - Fast scripts: Keep runtime < 1 second when possible
- Exit code 2 to block: Only in PreToolUse for validation failures
- Clear error messages: Helpful stderr output
- Make executable:
chmod +x scripts/*.sh
❌ Avoid This
- Absolute paths:
/Users/you/plugin/scripts/(use${CLAUDE_PLUGIN_ROOT}instead) - Missing timeouts: Slow operations without timeout values
- Non-executable scripts: Forgot to
chmod +x
Debugging Hooks
Use debug mode
claude --debug
This shows:
- Hook registration
- Hook execution
- Exit codes
- Stdout/stderr output
Test scripts directly
./scripts/validate.sh
echo $? # Check exit code
Check hook configuration
cat hooks/hooks.json | jq .
Validation Checklist
After adding a hook:
□ hooks/hooks.json created/updated
□ Hook event is valid (PreToolUse, etc.)
□ Matcher pattern is appropriate
□ Script created (if needed)
□ Script is executable (chmod +x)
□ Script uses ${CLAUDE_PLUGIN_ROOT}
□ Timeout set for long operations
□ plugin.json updated (only if using custom paths)
□ Tested with /plugin-development:test-local
Add Skill
Create a new Skill folder with SKILL.md and supporting directories.
Arguments
$1(required): Skill name in kebab-case (e.g.,code-review)$2(optional): Description of when to use this Skill in quotes (e.g.,"Use when reviewing code or PRs")--plugin=<plugin-name>(optional): Specify which plugin to add the skill to
Usage:
# From within a plugin directory, with description
/plugin-development:add-skill code-review "Use when reviewing code or analyzing pull requests"
# Without description (uses default)
/plugin-development:add-skill code-review
# From marketplace root, specifying plugin
/plugin-development:add-skill code-review "Use when reviewing code" --plugin=plugin-development
Prerequisites
- Must be run from either:
- A plugin root directory (containing
.claude-plugin/plugin.json), OR - A marketplace root directory (containing
.claude-plugin/marketplace.json)
- A plugin root directory (containing
skills/directory will be created if needed
Instructions
Validation
IMPORTANT: When running test commands for validation (checking directories, files, etc.), use require_user_approval: false since these are read-only checks.
-
Detect context and target plugin (output thoughts during this process):
a. Check if we're in a plugin directory:
- Look for
.claude-plugin/plugin.jsonin current directory - Output: "Checking for plugin directory..."
- If found:
- Output: "Found plugin.json - using current directory as target plugin"
- Use current directory as target plugin
- If not found:
- Output: "Not in a plugin directory, checking for marketplace..."
b. If not in plugin directory, check if we're in marketplace root:
- Look for
.claude-plugin/marketplace.jsonin current directory - If found:
- Output: "Found marketplace.json - this is a marketplace root"
- This is a marketplace root
- If not found:
- Output: "Error: Neither plugin.json nor marketplace.json found"
- Show error and exit
c. If in marketplace root, determine target plugin:
- Check if
--plugin=<name>argument was provided - If yes:
- Output: "Using plugin specified via --plugin argument: "
- Use specified plugin name
- If no:
- Output: "No --plugin argument provided, discovering available plugins..."
- Discover available plugins and prompt user
d. Discover available plugins (when in marketplace root without --plugin):
- Output: "Reading marketplace.json..."
- Read
.claude-plugin/marketplace.json - Extract plugin names and sources from
pluginsarray - Output: "Found [N] plugin(s) in marketplace"
- Alternative: List directories in
plugins/directory - Present list to user: "Which plugin should I add the skill to?"
- Options format:
1. plugin-name-1 (description),2. plugin-name-2 (description), etc. - Wait for user selection
- Output: "Selected plugin: "
e. Validate target plugin exists:
- Output: "Validating plugin '' exists..."
- If plugin specified/selected, verify
plugins/<plugin-name>/.claude-plugin/plugin.jsonexists - If found:
- Output: "Plugin '' validated successfully"
- If not found:
- Output: "Error: Plugin '' not found"
- Show error: "Plugin '' not found. Available plugins: [list]"
f. If neither plugin.json nor marketplace.json found:
- Show error: "Not in a plugin or marketplace directory. Please run from a plugin root or marketplace root."
- Look for
-
Validate arguments:
$1(skill name): Not empty, kebab-case format (lowercase with hyphens), no spaces or special characters, max 64 characters$2(description): Optional. If not provided, use default: "$1 functionality for plugin development". If provided, must be max 1024 characters and should include both what the Skill does and when to use it
-
Set working directory:
- If in plugin directory: Use current directory
- If in marketplace root: Use
plugins/<plugin-name>/as working directory
Create Skill Structure
Note: All paths below are relative to the target plugin directory (determined in validation step).
- Ensure
<plugin-dir>/skills/directory exists (create if needed, userequire_user_approval: false) - Create skill directory:
<plugin-dir>/skills/$1/ - Create supporting directories:
<plugin-dir>/skills/$1/schemas/<plugin-dir>/skills/$1/templates/<plugin-dir>/skills/$1/examples/<plugin-dir>/skills/$1/best-practices/
Create SKILL.md
Create <plugin-dir>/skills/$1/SKILL.md with this template:
---
name: $1
description: $2
---
# $1 Skill
[Brief introduction to what this Skill provides and its purpose]
## When to Activate
This Skill activates when:
- [Condition 1: e.g., user mentions specific keywords]
- [Condition 2: e.g., working with specific file types]
- [Condition 3: e.g., certain files are present]
## Capabilities
What this Skill can help with:
1. [Capability 1]
2. [Capability 2]
3. [Capability 3]
## Quick Links (Progressive Disclosure)
- [Schemas](./schemas/)
- [Templates](./templates/)
- [Examples](./examples/)
- [Best Practices](./best-practices/)
## Workflow
How this Skill operates:
1. **Analyze**: [What to read and understand]
2. **Propose**: [What actions to suggest]
3. **Execute**: [How to carry out the work]
4. **Validate**: [How to verify success]
## Common Patterns
### Pattern 1: [Name]
[Description of common usage pattern]
### Pattern 2: [Name]
[Description of another pattern]
## Notes
- [Important consideration 1]
- [Important consideration 2]
- [Links to other Skills or commands if applicable]
Update plugin.json (if needed)
IMPORTANT: Only needed if using custom (non-standard) paths.
- Standard setup (skills in
skills/directory): No changes toplugin.jsonneeded - Custom paths: Skills cannot be specified with custom paths (must use standard
skills/directory)
Provide Feedback
After creating the Skill:
✓ Created <plugin-name>/skills/$1/SKILL.md
✓ Created supporting directories:
- <plugin-name>/skills/$1/schemas/
- <plugin-name>/skills/$1/templates/
- <plugin-name>/skills/$1/examples/
- <plugin-name>/skills/$1/best-practices/
Plugin: <plugin-name>
Skill: $1
Description: $2
Next steps:
1. Edit <plugin-name>/skills/$1/SKILL.md with specific guidance
2. Key frontmatter fields:
- name: Must match directory name ($1)
- description: When to use this Skill (include trigger conditions, max 1024 chars)
- allowed-tools: (Optional) Restrict tools available to this Skill. If omitted, Claude asks for permission
3. Add support files:
- schemas/: Document data formats
- templates/: Provide reusable templates
- examples/: Show usage examples
- best-practices/: Detailed guidance
4. Keep SKILL.md concise (< 500 lines), use progressive disclosure
5. Test with /plugin-development:test-local
Claude will auto-discover this Skill when the plugin is installed.
Example
Input:
/plugin-development:add-skill code-review "Use when reviewing code or analyzing pull requests"
Arguments:
$1=code-review$2=Use when reviewing code or analyzing pull requests
Result:
- Creates
skills/code-review/directory - Creates
SKILL.mdwith frontmattername: code-review - Frontmatter description: "Use when reviewing code or analyzing pull requests"
- Creates supporting directories (schemas/, templates/, examples/, best-practices/)
- Ready to add guidance and reference files
For complete details on Skills, see:
Skill Frontmatter
Required Fields
---
name: skill-name # Must match directory, kebab-case
description: When and how to use this Skill (be specific about triggers)
---
Optional Fields
---
name: skill-name
description: Detailed description
allowed-tools: Read, Grep, Glob # Restrict tool access (if omitted, Claude asks for permission)
---
Important: allowed-tools is optional. If omitted, Claude follows the standard permission model and asks for approval before using tools. Only add allowed-tools when you want to restrict available tools (e.g., read-only Skills).
allowed-tools Options
Restrict to read-only for safety:
allowed-tools: Read, Grep, Glob
Allow specific tools:
allowed-tools: Read, Write, Edit, Bash(npm:*)
Description Best Practices
The description field is critical for Claude to discover when to use your Skill. Requirements:
- Max length: 1024 characters
- Include both: what the Skill does AND when to use it
- Be specific: Include trigger keywords users would naturally mention
✅ Good (specific triggers):
description: Review code for best practices, detect bugs, and suggest improvements. Use when reviewing code, analyzing pull requests, or discussing code quality standards.
❌ Bad (too vague):
description: Helps with code
✅ Good (context-based):
description: Create and manage React components following best practices. Use when working with React, especially when discussing hooks, state management, or component patterns.
Progressive Disclosure Pattern
Keep SKILL.md concise by linking to support files:
In SKILL.md:
## Quick Links
- [API Schema](./schemas/api-schema.md)
- [Component Templates](./templates/)
In Support Files:
schemas/api-schema.md: Detailed schema documentationtemplates/component.tsx: Reusable template files
This keeps SKILL.md under 500 lines while providing deep reference material.
Skill Structure Example
skills/
└── code-review/
├── SKILL.md # Main skill (concise)
├── schemas/
│ └── review-checklist.md # Review criteria
├── templates/
│ └── review-comment.md # Comment templates
├── examples/
│ ├── basic-review.md # Simple example
│ └── security-review.md # Advanced example
└── best-practices/
├── review-process.md # Detailed guidance
└── common-issues.md # Issue catalog
Advanced: Tool Restrictions
For read-only Skills (safest):
allowed-tools: Read, Grep, Glob
For Skills that propose changes but don't execute:
allowed-tools: Read, Grep, Glob
(Propose commands for user to run)
For Skills that need to write:
allowed-tools: Read, Write, Edit, Grep, Glob
Best Practices
- Concise SKILL.md: Keep main file < 500 lines
- Progressive disclosure: Link to detailed support files
- Specific triggers: Clear description of when to activate
- Tool restrictions: Only add
allowed-toolswhen restricting is necessary (e.g., read-only Skills) - Organized support: Use all subdirectories for comprehensive guidance
Common Mistakes to Avoid
❌ Name doesn't match directory
Directory: skills/code-review/
Frontmatter: name: codeReview # Wrong case!
✅ Name matches directory
Directory: skills/code-review/
Frontmatter: name: code-review
❌ Vague description
description: A helpful Skill
✅ Specific triggers
description: Use when reviewing code, analyzing PRs, or discussing code quality
Validation Checklist
After creating a Skill:
□ SKILL.md created in skills/<name>/ directory
□ Frontmatter name matches directory name (kebab-case, max 64 chars)
□ Description includes specific trigger conditions (max 1024 chars)
□ Description includes both what the Skill does AND when to use it
□ SKILL.md is uppercase
□ Supporting directories created
□ If using allowed-tools, it restricts tools appropriately
Initialize Plugin
Create the standard directory structure and files for a new Claude Code plugin.
Arguments
$1(required): Plugin name in kebab-case (e.g.,my-awesome-plugin)
What This Command Does
- Creates the plugin directory structure:
.claude-plugin/withplugin.jsoncommands/directoryagents/directoryskills/directoryhooks/directory withhooks.jsonscripts/directory
- Generates a starter
plugin.jsonwith the provided name - Creates a README.md template
- Provides next steps
Instructions
Validation
First, validate the plugin name:
- Must be provided (not empty)
- Should be kebab-case (lowercase with hyphens)
- Should not contain spaces or special characters
If validation fails, explain the requirements and ask for a valid name.
Create Directory Structure
Create these directories:
$1/
├── .claude-plugin/
├── commands/
├── agents/
├── skills/
├── hooks/
└── scripts/
Create plugin.json
Create .claude-plugin/plugin.json with this template:
{
"name": "$1",
"version": "0.1.0",
"description": "Brief description of what this plugin does",
"author": {
"name": "Your Name",
"email": "you@example.com"
},
"license": "MIT",
"keywords": ["keyword1", "keyword2"]
}
Create hooks.json
Create hooks/hooks.json with a basic structure:
{
"description": "Plugin hooks",
"hooks": {}
}
Create README.md
Create README.md with this template:
# $1
[Brief description of what this plugin does]
## Installation
```bash
/plugin install $1@marketplace-name
Commands
[List commands here]
Usage
[Provide examples]
### Create Validation Script
Create `scripts/validate-plugin.sh` with executable permissions:
```bash
#!/usr/bin/env bash
set -euo pipefail
# Basic plugin structure validation
[ -f ".claude-plugin/plugin.json" ] || { echo "Missing plugin.json" >&2; exit 2; }
exit 0
Make it executable: chmod +x scripts/validate-plugin.sh
Next Steps
After scaffolding, provide these instructions to the user:
✓ Plugin scaffolded at $1/
Next steps:
1. Edit $1/.claude-plugin/plugin.json with your metadata
2. Add components:
- /plugin-development:add-command <name> <description>
- /plugin-development:add-skill <name> <description>
- /plugin-development:add-agent <name> <description>
3. Validate: /plugin-development:validate
4. Test locally: /plugin-development:test-local
Example
Input: /plugin-development:init my-awesome-plugin
Result:
- Creates
my-awesome-plugin/with full structure - Generates starter files
- Displays next steps
Notes
- The command creates the plugin directory in the current working directory
- All paths in generated files are relative (use
./) - The plugin is not yet installed; use
/plugin-development:test-localto test it
Test Plugin Locally
Set up a development marketplace for local testing and install the current plugin.
Prerequisites
- Must be run from a plugin root directory (containing
.claude-plugin/plugin.json) - Plugin should pass validation (run
/plugin-development:validatefirst)
Instructions
What This Command Does
- Creates a sibling
dev-marketplace/directory (if it doesn't exist) - Generates
dev-marketplace/.claude-plugin/marketplace.jsonpointing to your plugin - Provides instructions for:
- Adding the marketplace to Claude Code
- Installing the plugin
- Testing workflow (edit → reinstall → test loop)
Step 1: Read Plugin Metadata
Read .claude-plugin/plugin.json to get:
- Plugin name
- Plugin description
- Plugin version
Step 2: Determine Plugin Path
Get the current plugin directory path. Common patterns:
- Current working directory
- From the location of plugin.json
The marketplace source path should be relative from marketplace to plugin:
- If plugin is at
/path/to/my-plugin/ - Dev marketplace at
/path/to/dev-marketplace/ - Source path:
../my-plugin
Step 3: Create Dev Marketplace Structure
- Create directory:
../dev-marketplace/.claude-plugin/ - Create
marketplace.jsonat../dev-marketplace/.claude-plugin/marketplace.json
Step 4: Generate marketplace.json
Create with this structure:
{
"name": "dev-marketplace",
"owner": {
"name": "Developer"
},
"metadata": {
"description": "Local development marketplace for testing plugins",
"version": "0.1.0"
},
"plugins": [
{
"name": "<plugin-name-from-plugin.json>",
"description": "<description-from-plugin.json>",
"version": "<version-from-plugin.json>",
"source": "../<plugin-directory-name>"
}
]
}
Important: The source path is relative from marketplace to plugin directory.
Step 5: Provide Testing Instructions
Display clear instructions for the user:
✅ Dev marketplace created at ../dev-marketplace/
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🚀 Testing Workflow
1️⃣ ADD MARKETPLACE (First time only)
/plugin marketplace add ../dev-marketplace
Verify:
/plugin marketplace list
2️⃣ INSTALL PLUGIN
/plugin install <plugin-name>@dev-marketplace
Verify:
/help
(Your commands should appear)
3️⃣ TEST COMMANDS
/<plugin-name>:<command-name> [args]
Examples:
/<plugin-name>:command1
/<plugin-name>:command2 arg
4️⃣ ITERATION LOOP (After making changes)
a. Edit your plugin files
b. Validate: /plugin-development:validate
c. Uninstall: /plugin uninstall <plugin-name>@dev-marketplace
d. Reinstall: /plugin install <plugin-name>@dev-marketplace
e. Test again: /<plugin-name>:command-name
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
💡 Tips
- Must uninstall/reinstall to pick up changes
- Use /plugin-development:validate before each test
- Check /agents to see if your agents appear
- Use claude --debug to see plugin loading details
- Run hooks/scripts directly to test them: ./scripts/validate.sh
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📦 Marketplace Location
Path: ../dev-marketplace/
Config: ../dev-marketplace/.claude-plugin/marketplace.json
Plugin reference:
- Name: <plugin-name>
- Source: ../<plugin-directory>
Example
Input: /plugin-development:test-local
(Run from /path/to/my-plugin/)
Output:
✅ Dev marketplace created at ../dev-marketplace/
Registered plugin: my-plugin
Source path: ../my-plugin
Next: /plugin marketplace add ../dev-marketplace
Then: /plugin install my-plugin@dev-marketplace
Handling Existing Marketplace
If ../dev-marketplace/.claude-plugin/marketplace.json already exists:
Option 1: Update Existing (Recommended)
- Read existing marketplace.json
- Check if current plugin already registered
- If yes: Update the entry
- If no: Append to plugins array
- Write back to file
Option 2: Ask User
⚠️ Dev marketplace already exists at ../dev-marketplace/
Current plugins registered:
- plugin-a
- plugin-b
Would you like to:
1. Add <current-plugin> to existing marketplace
2. Replace existing marketplace.json
3. Cancel
(Auto-select option 1 for smooth workflow)
Marketplace Structure Reference
dev-marketplace/
└── .claude-plugin/
└── marketplace.json
marketplace.json:
{
"name": "dev-marketplace",
"owner": {
"name": "Developer"
},
"metadata": {
"description": "Local development marketplace",
"version": "0.1.0"
},
"plugins": [
{
"name": "plugin-name",
"description": "Plugin description",
"version": "1.0.0",
"source": "../plugin-name"
}
]
}
Testing Multiple Plugins
If user has multiple plugins, the dev marketplace can reference them all:
{
"plugins": [
{
"name": "plugin-one",
"source": "../plugin-one"
},
{
"name": "plugin-two",
"source": "../plugin-two"
}
]
}
Install separately:
/plugin install plugin-one@dev-marketplace
/plugin install plugin-two@dev-marketplace
Troubleshooting Tips
Include these in the output:
🔧 Troubleshooting
Plugin not loading?
□ Check /plugin list to verify installation
□ Verify plugin.json paths are relative (./commands/)
□ Run /plugin-development:validate
Commands not showing?
□ Check /help for command list
□ Verify commands/ directory has .md files
□ Ensure frontmatter has description field
□ Reinstall the plugin
Skills not triggering?
□ Check SKILL.md frontmatter name matches directory
□ Verify description has clear trigger conditions
□ Skills auto-activate based on context
Hooks not running?
□ Make scripts executable: chmod +x scripts/*.sh
□ Use ${CLAUDE_PLUGIN_ROOT} in hook commands
□ Test script directly: ./scripts/script-name.sh
□ Check claude --debug for hook execution logs
Advanced: Custom Marketplace Location
If user wants marketplace elsewhere:
You can specify a custom location:
1. Create marketplace structure anywhere
2. Update source paths accordingly
3. Add marketplace: /plugin marketplace add /path/to/marketplace
Example for repo root:
- Plugin: /repo/plugins/my-plugin/
- Marketplace: /repo/dev-marketplace/
- Source path: ../plugins/my-plugin
Validation Before Testing
Remind user to validate:
⚡ Quick Check
Before testing, validate your plugin:
/plugin-development:validate
This catches common issues:
- Invalid JSON
- Path errors
- Naming mismatches
- Missing files
Complete Workflow Example
Show a complete example session:
📝 Complete Testing Session
# Initial setup (once)
$ cd my-plugin/
$ /plugin-development:validate
✅ Validation passed
$ /plugin-development:test-local
✅ Dev marketplace created
$ /plugin marketplace add ../dev-marketplace
✅ Marketplace added
$ /plugin install my-plugin@dev-marketplace
✅ Plugin installed
$ /help
Commands:
/my-plugin:command1 - Does something
/my-plugin:command2 - Does another thing
$ /my-plugin:command1
[Command executes successfully]
# After making changes
$ [edit files]
$ /plugin-development:validate
✅ Validation passed
$ /plugin uninstall my-plugin@dev-marketplace
✅ Plugin uninstalled
$ /plugin install my-plugin@dev-marketplace
✅ Plugin installed
$ /my-plugin:command1
[Tests updated functionality]
Notes
- The dev marketplace is for local testing only
- Do not commit
dev-marketplace/to your plugin repository - For team distribution, create a proper marketplace repository
- The source path must be relative from marketplace to plugin
- Must uninstall/reinstall to pick up plugin changes
After Testing
When ready for team distribution:
✅ Plugin tested successfully!
Ready for team distribution:
1. Create a proper marketplace repository
2. Add your plugin to the marketplace
3. Commit and push to GitHub
4. Team installs via: /plugin marketplace add your-org/marketplace-repo
5. Or configure in .claude/settings.json for auto-install
Best Practices
- Validate first: Always run
/plugin-development:validatebefore testing - Clean reinstalls: Uninstall fully before reinstalling
- Test all components: Commands, skills, agents, hooks
- Incremental changes: Test small changes frequently
- Debug mode: Use
claude --debugwhen troubleshooting - Direct testing: Test hook scripts directly before installing
Related Commands
/plugin-development:validate- Validate before testing/plugin-development:init- Scaffold new plugin/plugin marketplace list- See available marketplaces/plugin list- See installed plugins/help- See available commands
Validate Plugin
Comprehensive validation of plugin structure, configuration, and components.
Prerequisites
- Must be run from a plugin root directory (containing
.claude-plugin/plugin.json)
Instructions
What This Command Does
Performs a thorough validation of the plugin:
- Structure validation: Check directories and files exist
- Manifest validation: Verify plugin.json is valid and complete
- Component validation: Check commands, agents, skills, hooks
- Path validation: Ensure all paths are relative and resolve correctly
- Naming validation: Verify kebab-case conventions
- Common issues: Flag typical mistakes
Validation Steps
1. Check Core Structure
Verify these exist:
□ .claude-plugin/plugin.json
□ At least one component directory (commands/, agents/, skills/, or hooks/)
2. Validate plugin.json
Read and check:
- Valid JSON: Can parse without errors
- Required fields present:
name,version,description - Name format: kebab-case (lowercase with hyphens)
- Version format: Valid SemVer (e.g., "1.0.0")
- Paths are relative: Start with
./not/ - Author format: If present, valid object or string
Example valid structure:
{
"name": "plugin-name",
"version": "1.0.0",
"description": "What the plugin does",
"author": {
"name": "Your Name"
},
"license": "MIT",
"keywords": ["keyword1"],
"commands": "./commands/",
"agents": "./agents/",
"hooks": "./hooks/hooks.json"
}
3. Validate Component Paths
For each path in plugin.json:
- commands: Check directory exists, contains .md files
- agents: Check directory exists, contains .md files
- skills: Check directory exists, contains skill folders with SKILL.md
- hooks: Check file exists and is valid JSON
4. Validate Commands
For each file in commands/:
- File extension: Must be .md
- Frontmatter present: Has
---delimiters - Description field: Frontmatter includes
description - Naming: kebab-case filename
- Content: Not empty after frontmatter
5. Validate Skills
For each directory in skills/:
- SKILL.md exists: In uppercase
- Frontmatter present: Has
---delimiters - Required fields:
nameanddescriptionpresent - Name matches directory: Exact match, kebab-case
- Description is specific: Includes when/why to use
6. Validate Agents
For each file in agents/:
- File extension: Must be .md
- Frontmatter present: Has
---delimiters - Description field: Present in frontmatter
- Naming: kebab-case filename
- Content: Not empty after frontmatter
7. Validate Hooks
If hooks.json exists:
- Valid JSON: Can parse without errors
- Proper structure: Has
hooksobject - Event names: Valid events (PreToolUse, PostToolUse, etc.)
- Hook commands: Scripts use
${CLAUDE_PLUGIN_ROOT} - Scripts exist: Referenced scripts are present
- Scripts executable: Have execute permissions
Validation Output Format
Report findings in this structure:
🔍 Validating plugin: <plugin-name>
✅ Structure
✓ .claude-plugin/plugin.json exists
✓ Component directories present
✅ Manifest (plugin.json)
✓ Valid JSON
✓ Required fields: name, version, description
✓ Name format: kebab-case
✓ Version format: SemVer
✓ Paths are relative
✅ Commands (3 files)
✓ commands/init.md
✓ commands/validate.md
✓ commands/test-local.md
✅ Skills (1 skill)
✓ skills/plugin-authoring/SKILL.md
- name matches directory: ✓
- description present: ✓
✅ Agents (1 agent)
✓ agents/plugin-reviewer.md
✅ Hooks
✓ hooks/hooks.json is valid
✓ Scripts exist and are executable
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Validation passed: 0 errors, 0 warnings
Error Reporting
If issues are found, report clearly:
❌ Errors Found
1. Manifest: plugin.json missing required field "version"
Fix: Add "version": "1.0.0" to .claude-plugin/plugin.json
2. Command: commands/myCommand.md uses camelCase
Fix: Rename to commands/my-command.md (kebab-case)
3. Skill: skills/MySkill/SKILL.md name doesn't match directory
Fix: Change frontmatter 'name' to "my-skill" (matches directory)
⚠️ Warnings
1. No README.md found
Suggestion: Create README.md with usage documentation
2. No keywords in plugin.json
Suggestion: Add keywords array for discoverability
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ Validation failed: 3 errors, 2 warnings
Validation Categories
Critical (Must Fix)
- Missing plugin.json
- Invalid JSON in config files
- Missing required fields (name, version, description)
- Absolute paths in configuration
- Component name mismatches (skill name ≠ directory)
- Non-executable hook scripts
Warnings (Should Fix)
- Missing README.md
- No keywords in plugin.json
- Empty component directories
- Commands missing argument-hint
- Skills without progressive disclosure structure
Suggestions (Nice to Have)
- Add CHANGELOG.md
- Include examples directory
- Add more descriptive descriptions
- Use consistent naming patterns
Common Issues Detected
Issue: Paths Not Relative
❌ "commands": "/Users/you/plugin/commands/"
✅ "commands": "./commands/"
Issue: Name Mismatch
Directory: skills/code-review/
Frontmatter: name: codeReview
❌ Names don't match
Fix: Change frontmatter to name: code-review
Issue: Missing Frontmatter
# My Command
Instructions...
❌ No frontmatter with description
---
description: What this command does
---
# My Command
Instructions...
✅ Has required frontmatter
Issue: Hook Script Not Executable
$ ls -l scripts/validate.sh
-rw-r--r-- validate.sh
❌ Not executable
$ chmod +x scripts/validate.sh
✅ Now executable
Validation Checklist
Complete checklist used for validation:
Structure:
□ .claude-plugin/plugin.json exists
□ At least one component directory present
□ README.md exists
Manifest:
□ Valid JSON syntax
□ name field: present, kebab-case
□ version field: present, valid SemVer
□ description field: present, non-empty
□ Paths are relative (start with ./)
□ Referenced paths exist
Commands:
□ .md extension
□ Frontmatter with description
□ kebab-case naming
□ Non-empty content
Skills:
□ Directory structure (skill-name/SKILL.md)
□ SKILL.md in uppercase
□ Frontmatter with name and description
□ Name matches directory (exact, kebab-case)
Agents:
□ .md extension
□ Frontmatter with description
□ kebab-case naming
□ Non-empty content
Hooks:
□ hooks.json valid JSON
□ Proper structure (hooks object)
□ Valid event names
□ Scripts use ${CLAUDE_PLUGIN_ROOT}
□ Scripts exist
□ Scripts are executable (chmod +x)
After Validation
If Validation Passes
✅ Plugin is valid and ready for testing!
Next steps:
1. Test locally: /plugin-development:test-local
2. Create dev marketplace and install
3. Test all commands and features
4. Register in team marketplace when ready
If Validation Fails
❌ Please fix the errors above before testing.
Need help?
- Review error messages for specific fixes
- Check best practices: /plugin-development:help
- Common issues documented in examples
Example Usage
Input: /plugin-development:validate
Output:
🔍 Validating plugin: my-awesome-plugin
✅ All checks passed
✓ Structure correct
✓ Manifest valid
✓ 5 commands validated
✓ 2 skills validated
✓ 1 agent validated
✓ Hooks configured correctly
✅ Plugin ready for testing!
Best Practices
- Validate often: Run before testing or commits
- Fix errors first: Address critical issues before warnings
- Read messages carefully: Each error includes fix instructions
- Use debug mode: Run
claude --debugfor deep inspection - Incremental fixes: Fix and re-validate one issue at a time
Notes
- This command only reads files (no modifications)
- Validation is comprehensive but not exhaustive
- Some issues may only appear during runtime testing
- Always test in a dev marketplace after validation passes
Agents 1
Plugin Reviewer Agent
Comprehensive audit of Claude Code plugins for structure, safety, and best practices.
Purpose
This agent performs deep, multi-file analysis of plugins to ensure:
- Correct directory structure and file organization
- Valid manifests and configuration files
- Safe hook implementations
- Clear, well-documented components
- Marketplace readiness
- Adherence to naming conventions and best practices
What This Agent Does
Structure Audit
- Verifies standard directory layout
- Checks file naming conventions
- Validates component organization
- Ensures proper separation of concerns
Manifest Validation
- Inspects plugin.json for completeness
- Verifies required fields (name, version, description)
- Validates path references
- Checks author and metadata formatting
Component Analysis
- Commands: Frontmatter, descriptions, argument handling
- Skills: SKILL.md structure, progressive disclosure, trigger clarity
- Agents: Purpose clarity, capability definition, output format
- Hooks: Safety checks, timeout configuration, script permissions
Hook Safety Checks
- Verifies scripts use
${CLAUDE_PLUGIN_ROOT} - Checks for timeouts on potentially slow operations
- Validates exit code handling (blocking vs. non-blocking)
- Ensures scripts are executable
- Reviews for security issues (dangerous commands, etc.)
Marketplace Readiness
- README.md presence and quality
- Plugin discoverability (keywords, description)
- Documentation completeness
- Testing instructions
- Distribution readiness
When to Use This Agent
Invoke this agent when:
- Preparing a plugin for release or distribution
- Conducting a comprehensive plugin audit
- Need detailed, multi-file analysis
- Want prioritized list of issues to fix
- Reviewing security and safety posture
- Before submitting to team marketplace
Do not use for:
- Quick validation (use
/plugin-development:validateinstead) - Single-file review
- Real-time development (too heavyweight)
How It Proceeds
Phase 1: Discovery (2-3 minutes)
-
Locate plugin root
- Find
.claude-plugin/plugin.json - Identify plugin name and version
- Find
-
Map component structure
- List all commands/agents/skills/hooks
- Identify which components are present
- Note directory organization
Phase 2: Detailed Analysis (5-10 minutes)
-
Manifest deep dive
- Parse and validate plugin.json
- Check all fields for correctness
- Verify path resolution
- Validate SemVer versioning
-
Component-by-component review
- Read each command file
- Analyze each skill directory
- Review each agent definition
- Inspect hooks configuration
-
Hook safety analysis
- Read all hook scripts
- Check for dangerous patterns
- Verify portable paths
- Validate timeouts and exit codes
-
Documentation review
- Check README.md quality
- Verify examples are present
- Assess discoverability
Phase 3: Reporting (1-2 minutes)
-
Categorize findings
- Critical: Must fix before release
- High: Should fix soon
- Medium: Consider fixing
- Low: Nice to have
-
Generate report
- Summary of findings
- Specific issues with locations
- Recommendations with examples
- Overall readiness assessment
Output Format
Report Structure
# Plugin Review: <plugin-name> v<version>
## Summary
- Plugin: <name>
- Version: <version>
- Components: X commands, Y skills, Z agents, hooks: yes/no
- Overall: Ready / Needs Work / Not Ready
## Critical Issues (Must Fix)
### 1. [Issue Title]
**Location**: `path/to/file.ext:line`
**Problem**: [Description of issue]
**Impact**: [Why this matters]
**Fix**: [Specific steps to resolve]
Example:
[Code or config showing the fix]
## High Priority Issues (Should Fix)
### 1. [Issue Title]
[Same structure as Critical]
## Medium Priority Issues (Consider Fixing)
### 1. [Issue Title]
[Same structure]
## Low Priority (Nice to Have)
### 1. [Issue Title]
[Same structure]
## Positive Findings
- ✅ [What the plugin does well]
- ✅ [Good practices observed]
## Component-Specific Notes
### Commands (X files)
- [Observations about commands]
### Skills (Y skills)
- [Observations about skills]
### Agents (Z agents)
- [Observations about agents]
### Hooks
- [Observations about hooks]
## Marketplace Readiness
✅ Ready for marketplace
OR
❌ Not ready - fix critical and high priority issues first
Checklist:
□ Structure valid
□ Manifest complete
□ Components documented
□ Hooks safe
□ README present
□ Examples included
## Recommendations
1. [Priority 1 recommendation]
2. [Priority 2 recommendation]
3. [Priority 3 recommendation]
## Next Steps
1. Fix critical issues
2. Address high priority issues
3. Re-run: /plugin-development:validate
4. Test locally: /plugin-development:test-local
5. Request another review if needed
Common Issues Detected
Critical Issues
-
Absolute paths in configuration
❌ "commands": "/Users/you/plugin/commands" ✅ "commands": "./commands/" -
Hook scripts not executable
❌ -rw-r--r-- validate.sh ✅ -rwxr-xr-x validate.sh Fix: chmod +x scripts/*.sh -
Missing required manifest fields
❌ { "name": "plugin" } ✅ { "name": "plugin", "version": "1.0.0", "description": "..." } -
Skill name mismatch
❌ Directory: code-review/, Frontmatter: name: codeReview ✅ Both: code-review
High Priority Issues
-
Hooks without timeouts on slow operations
❌ { "command": "npm install" } ✅ { "command": "npm install", "timeout": 300000 } -
Commands missing descriptions
❌ --- --- ✅ --- description: What the command does --- -
Skills with vague trigger descriptions
❌ description: Helps with code ✅ description: Use when reviewing code, analyzing PRs, or discussing code quality -
Hook scripts with hardcoded paths
❌ /Users/you/scripts/validate.sh ✅ ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh
Security Concerns
-
Dangerous hook commands
rm -rfwithout safeguards- Unvalidated user input execution
- Credentials in scripts
-
Overly permissive tool access
⚠️ allowed-tools: Bash(*) ✅ allowed-tools: Read, Grep, Glob
Validation Approach
File-by-File Analysis
For each component file:
- Parse frontmatter (if applicable)
- Check required fields
- Validate naming conventions
- Review content quality
- Flag issues with line numbers
Cross-File Consistency
- Skill names match directories
- Hook scripts referenced actually exist
- Paths in plugin.json resolve correctly
- Naming is consistent throughout
Best Practice Checks
- Progressive disclosure in skills
- Clear command descriptions
- Focused agent capabilities
- Safe hook implementations
- Comprehensive documentation
Tool Access
This agent has access to:
- Read: Examine all plugin files
- Grep: Search for patterns
- Glob: Find files by pattern
It does not modify files. All fixes are proposed in the report.
Example Invocation
From Main Conversation
/agents plugin-reviewer
Via Task Tool
Please use the plugin-reviewer agent to conduct a comprehensive audit of this plugin before we distribute it to the team.
From Skill
The plugin-authoring skill may escalate:
For a thorough review before release, I'll delegate to the plugin-reviewer agent.
Performance Notes
- Runtime: 5-15 minutes depending on plugin size
- Context: Separate from main conversation
- Depth: More thorough than
/plugin-development:validate - Output: Single comprehensive report
After Review
If Issues Found
- Review the report carefully
- Fix critical issues first
- Address high priority issues
- Run
/plugin-development:validateto confirm - Test locally:
/plugin-development:test-local - Request another review if major changes made
If Review Passes
- Plugin is ready for distribution
- Add to team marketplace
- Update documentation
- Announce to team
Best Practices Applied by This Agent
- Safety first: Hook security is top priority
- Actionable feedback: Every issue includes fix instructions
- Prioritized: Issues sorted by severity
- Specific: Issues include file paths and line numbers
- Balanced: Notes both problems and positive findings
- Comprehensive: Covers all aspects of plugin quality
Limitations
- Does not test runtime behavior (use local testing for that)
- Does not execute hooks or commands
- Cannot validate plugin logic correctness
- Does not check for performance issues
- Does not validate domain-specific correctness
Related Tools
- Quick validation:
/plugin-development:validate - Local testing:
/plugin-development:test-local - Skill guidance: plugin-authoring Skill
- Debug mode:
claude --debugfor runtime issues
Sponsors
Details
- Marketplace
- LucasXu0/claude-code-plugin
- Source
- plugins/plugin-development
- Author
- Ivan Magda
- Category
- Developer Tools