Agent Development for Claude Code Plugins

Overview

Agents are autonomous subprocesses that handle complex, multi-step tasks independently. Understanding agent structure, triggering conditions, and system prompt design enables creating powerful autonomous capabilities.

Key concepts: - Agents are FOR autonomous work, commands are FOR user-initiated actions - Markdown file format with YAML frontmatter - Triggering via description field with examples - System prompt defines agent behavior - Model and color customization

Agent File Structure

Complete Format

---
name: agent-identifier
description: Use this agent when [triggering conditions]. Examples:

<example>
Context: [Situation description]
user: "[User request]"
assistant: "[How assistant should respond and use this agent]"
<commentary>
[Why this agent should be triggered]
</commentary>
</example>

<example>
[Additional example...]
</example>

model: inherit
color: blue
tools: ["Read", "Write", "Grep"]
---

You are [agent role description]...

**Your Core Responsibilities:**
1. [Responsibility 1]
2. [Responsibility 2]

**Analysis Process:**
[Step-by-step workflow]

**Output Format:**
[What to return]

Frontmatter Fields

name (required)

Agent identifier used for namespacing and invocation.

Format: lowercase, numbers, hyphens only Length: 3-50 characters Pattern: Must start and end with alphanumeric

Good examples: - code-reviewer - test-generator - api-docs-writer - security-analyzer

Bad examples: - helper (too generic) - -agent- (starts/ends with hyphen) - my_agent (underscores not allowed) - ag (too short, < 3 chars)

description (required)

Defines when Claude should trigger this agent. This is the most critical field.

Must include: 1. Triggering conditions ("Use this agent when...") 2. Multiple <example> blocks showing usage 3. Context, user request, and assistant response in each example 4. <commentary> explaining why agent triggers

Format:

Use this agent when [conditions]. Examples:

<example>
Context: [Scenario description]
user: "[What user says]"
assistant: "[How Claude should respond]"
<commentary>
[Why this agent is appropriate]
</commentary>
</example>

[More examples...]

Best practices: - Include 2-4 concrete examples - Show proactive and reactive triggering - Cover different phrasings of same intent - Explain reasoning in commentary - Be specific about when NOT to use the agent

model (required)

Which model the agent should use.

Options: - inherit - Use same model as parent (recommended) - sonnet - Claude Sonnet (balanced) - opus - Claude Opus (most capable, expensive) - haiku - Claude Haiku (fast, cheap)

Recommendation: Use inherit unless agent needs specific model capabilities.

color (required)

Visual identifier for agent in UI.

Options: blue, cyan, green, yellow, magenta, red

Guidelines: - Choose distinct colors for different agents in same plugin - Use consistent colors for similar agent types - Blue/cyan: Analysis, review - Green: Success-oriented tasks - Yellow: Caution, validation - Red: Critical, security - Magenta: Creative, generation

tools (optional)

Restrict agent to specific tools.

Format: Array of tool names

tools: ["Read", "Write", "Grep", "Bash"]

Default: If omitted, agent has access to all tools

Best practice: Limit tools to minimum needed (principle of least privilege)

Common tool sets: - Read-only analysis: ["Read", "Grep", "Glob"] - Code generation: ["Read", "Write", "Grep"] - Testing: ["Read", "Bash", "Grep"] - Full access: Omit field or use ["*"]

System Prompt Design

The markdown body becomes the agent's system prompt. Write in second person, addressing the agent directly.

Structure

Standard template:

You are [role] specializing in [domain].

**Your Core Responsibilities:**
1. [Primary responsibility]
2. [Secondary responsibility]
3. [Additional responsibilities...]

**Analysis Process:**
1. [Step one]
2. [Step two]
3. [Step three]
[...]

**Quality Standards:**
- [Standard 1]
- [Standard 2]

**Output Format:**
Provide results in this format:
- [What to include]
- [How to structure]

**Edge Cases:**
Handle these situations:
- [Edge case 1]: [How to handle]
- [Edge case 2]: [How to handle]

Best Practices

✅ DO: - Write in second person ("You are...", "You will...") - Be specific about responsibilities - Provide step-by-step process - Define output format - Include quality standards - Address edge cases - Keep under 10,000 characters

❌ DON'T: - Write in first person ("I am...", "I will...") - Be vague or generic - Omit process steps - Leave output format undefined - Skip quality guidance - Ignore error cases

Creating Agents

Method 1: AI-Assisted Generation

Use this prompt pattern (extracted from Claude Code):

Create an agent configuration based on this request: "[YOUR DESCRIPTION]"

Requirements:
1. Extract core intent and responsibilities
2. Design expert persona for the domain
3. Create comprehensive system prompt with:
   - Clear behavioral boundaries
   - Specific methodologies
   - Edge case handling
   - Output format
4. Create identifier (lowercase, hyphens, 3-50 chars)
5. Write description with triggering conditions
6. Include 2-3 <example> blocks showing when to use

Return JSON with:
{
  "identifier": "agent-name",
  "whenToUse": "Use this agent when... Examples: <example>...</example>",
  "systemPrompt": "You are..."
}

Then convert to agent file format with frontmatter.

See examples/agent-creation-prompt.md for complete template.

Method 2: Manual Creation

1. Choose agent identifier (3-50 chars, lowercase, hyphens)
2. Write description with examples
3. Select model (usually inherit)
4. Choose color for visual identification
5. Define tools (if restricting access)
6. Write system prompt with structure above
7. Save as agents/agent-name.md

Validation Rules

Identifier Validation

✅ Valid: code-reviewer, test-gen, api-analyzer-v2
❌ Invalid: ag (too short), -start (starts with hyphen), my_agent (underscore)

Rules: - 3-50 characters - Lowercase letters, numbers, hyphens only - Must start and end with alphanumeric - No underscores, spaces, or special characters

Description Validation

Length: 10-5,000 characters Must include: Triggering conditions and examples Best: 200-1,000 characters with 2-4 examples

System Prompt Validation

Length: 20-10,000 characters Best: 500-3,000 characters Structure: Clear responsibilities, process, output format

Agent Organization

Plugin Agents Directory

plugin-name/
└── agents/
    ├── analyzer.md
    ├── reviewer.md
    └── generator.md

All .md files in agents/ are auto-discovered.

Namespacing

Agents are namespaced automatically: - Single plugin: agent-name - With subdirectories: plugin:subdir:agent-name

Testing Agents

Test Triggering

Create test scenarios to verify agent triggers correctly:

1. Write agent with specific triggering examples
2. Use similar phrasing to examples in test
3. Check Claude loads the agent
4. Verify agent provides expected functionality

Test System Prompt

Ensure system prompt is complete:

1. Give agent typical task
2. Check it follows process steps
3. Verify output format is correct
4. Test edge cases mentioned in prompt
5. Confirm quality standards are met

Quick Reference

Minimal Agent

---
name: simple-agent
description: Use this agent when... Examples: <example>...</example>
model: inherit
color: blue
---

You are an agent that [does X].

Process:
1. [Step 1]
2. [Step 2]

Output: [What to provide]

Frontmatter Fields Summary

Best Practices

DO: - ✅ Include 2-4 concrete examples in description - ✅ Write specific triggering conditions - ✅ Use inherit for model unless specific need - ✅ Choose appropriate tools (least privilege) - ✅ Write clear, structured system prompts - ✅ Test agent triggering thoroughly

DON'T: - ❌ Use generic descriptions without examples - ❌ Omit triggering conditions - ❌ Give all agents same color - ❌ Grant unnecessary tool access - ❌ Write vague system prompts - ❌ Skip testing

Additional Resources

Reference Files

For detailed guidance, consult:

• references/system-prompt-design.md - Complete system prompt patterns
• references/triggering-examples.md - Example formats and best practices
• references/agent-creation-system-prompt.md - The exact prompt from Claude Code

Example Files

Working examples in examples/:

• agent-creation-prompt.md - AI-assisted agent generation template
• complete-agent-examples.md - Full agent examples for different use cases

Utility Scripts

Development tools in scripts/:

• validate-agent.sh - Validate agent file structure
• test-agent-trigger.sh - Test if agent triggers correctly

Implementation Workflow

To create an agent for a plugin:

1. Define agent purpose and triggering conditions
2. Choose creation method (AI-assisted or manual)
3. Create agents/agent-name.md file
4. Write frontmatter with all required fields
5. Write system prompt following best practices
6. Include 2-4 triggering examples in description
7. Validate with scripts/validate-agent.sh
8. Test triggering with real scenarios
9. Document agent in plugin README

Focus on clear triggering conditions and comprehensive system prompts for autonomous operation.

Command Development for Claude Code

Note: The .claude/commands/ directory is a legacy format. For new skills, use the .claude/skills/<name>/SKILL.md directory format. Both are loaded identically — the only difference is file layout. See the skill-development skill for the preferred format.

Overview

Slash commands are frequently-used prompts defined as Markdown files that Claude executes during interactive sessions. Understanding command structure, frontmatter options, and dynamic features enables creating powerful, reusable workflows.

Key concepts:

• Markdown file format for commands
• YAML frontmatter for configuration
• Dynamic arguments and file references
• Bash execution for context
• Command organization and namespacing

Command Basics

What is a Slash Command?

A slash command is a Markdown file containing a prompt that Claude executes when invoked. Commands provide:

• Reusability: Define once, use repeatedly
• Consistency: Standardize common workflows
• Sharing: Distribute across team or projects
• Efficiency: Quick access to complex prompts

Critical: Commands are Instructions FOR Claude

Commands are written for agent consumption, not human consumption.

When a user invokes /command-name, the command content becomes Claude's instructions. Write commands as directives TO Claude about what to do, not as messages TO the user.

Correct approach (instructions for Claude):

Review this code for security vulnerabilities including:

- SQL injection
- XSS attacks
- Authentication issues

Provide specific line numbers and severity ratings.

Incorrect approach (messages to user):

This command will review your code for security issues.
You'll receive a report with vulnerability details.

The first example tells Claude what to do. The second tells the user what will happen but doesn't instruct Claude. Always use the first approach.

Command Locations

Project commands (shared with team):

• Location: .claude/commands/
• Scope: Available in specific project
• Label: Shown as "(project)" in /help
• Use for: Team workflows, project-specific tasks

Personal commands (available everywhere):

• Location: ~/.claude/commands/
• Scope: Available in all projects
• Label: Shown as "(user)" in /help
• Use for: Personal workflows, cross-project utilities

Plugin commands (bundled with plugins):

• Location: plugin-name/commands/
• Scope: Available when plugin installed
• Label: Shown as "(plugin-name)" in /help
• Use for: Plugin-specific functionality

File Format

Basic Structure

Commands are Markdown files with .md extension:

.claude/commands/
├── review.md           # /review command
├── test.md             # /test command
└── deploy.md           # /deploy command

Simple command:

Review this code for security vulnerabilities including:

- SQL injection
- XSS attacks
- Authentication bypass
- Insecure data handling

No frontmatter needed for basic commands.

With YAML Frontmatter

Add configuration using YAML frontmatter:

---
description: Review code for security issues
allowed-tools: Read, Grep, Bash(git:*)
model: sonnet
---

Review this code for security vulnerabilities...

YAML Frontmatter Fields

description

Purpose: Brief description shown in /help Type: String Default: First line of command prompt

---
description: Review pull request for code quality
---

Best practice: Clear, actionable description (under 60 characters)

allowed-tools

Purpose: Specify which tools command can use Type: String or Array Default: Inherits from conversation

---
allowed-tools: Read, Write, Edit, Bash(git:*)
---

Patterns:

• Read, Write, Edit - Specific tools
• Bash(git:*) - Bash with git commands only
• * - All tools (rarely needed)

Use when: Command requires specific tool access

model

Purpose: Specify model for command execution Type: String (sonnet, opus, haiku) Default: Inherits from conversation

---
model: haiku
---

Use cases:

• haiku - Fast, simple commands
• sonnet - Standard workflows
• opus - Complex analysis

argument-hint

Purpose: Document expected arguments for autocomplete Type: String Default: None

---
argument-hint: [pr-number] [priority] [assignee]
---

Benefits:

• Helps users understand command arguments
• Improves command discovery
• Documents command interface

disable-model-invocation

Purpose: Prevent SlashCommand tool from programmatically calling command Type: Boolean Default: false

---
disable-model-invocation: true
---

Use when: Command should only be manually invoked

Dynamic Arguments

Using $ARGUMENTS

Capture all arguments as single string:

---
description: Fix issue by number
argument-hint: [issue-number]
---

Fix issue #$ARGUMENTS following our coding standards and best practices.

Usage:

> /fix-issue 123
> /fix-issue 456

Expands to:

Fix issue #123 following our coding standards...
Fix issue #456 following our coding standards...

Using Positional Arguments

Capture individual arguments with $1, $2, $3, etc.:

---
description: Review PR with priority and assignee
argument-hint: [pr-number] [priority] [assignee]
---

Review pull request #$1 with priority level $2.
After review, assign to $3 for follow-up.

Usage:

> /review-pr 123 high alice

Expands to:

Review pull request #123 with priority level high.
After review, assign to alice for follow-up.

Combining Arguments

Mix positional and remaining arguments:

Deploy $1 to $2 environment with options: $3

Usage:

> /deploy api staging --force --skip-tests

Expands to:

Deploy api to staging environment with options: --force --skip-tests

File References

Using @ Syntax

Include file contents in command:

---
description: Review specific file
argument-hint: [file-path]
---

Review @$1 for:

- Code quality
- Best practices
- Potential bugs

Usage:

> /review-file src/api/users.ts

Effect: Claude reads src/api/users.ts before processing command

Multiple File References

Reference multiple files:

Compare @src/old-version.js with @src/new-version.js

Identify:

- Breaking changes
- New features
- Bug fixes

Static File References

Reference known files without arguments:

Review @package.json and @tsconfig.json for consistency

Ensure:

- TypeScript version matches
- Dependencies are aligned
- Build configuration is correct

Bash Execution in Commands

Commands can execute bash commands inline to dynamically gather context before Claude processes the command. This is useful for including repository state, environment information, or project-specific context.

When to use:

• Include dynamic context (git status, environment vars, etc.)
• Gather project/repository state
• Build context-aware workflows

Implementation details: For complete syntax, examples, and best practices, see references/plugin-features-reference.md section on bash execution. The reference includes the exact syntax and multiple working examples to avoid execution issues

Command Organization

Flat Structure

Simple organization for small command sets:

.claude/commands/
├── build.md
├── test.md
├── deploy.md
├── review.md
└── docs.md

Use when: 5-15 commands, no clear categories

Namespaced Structure

Organize commands in subdirectories:

.claude/commands/
├── ci/
│   ├── build.md        # /build (project:ci)
│   ├── test.md         # /test (project:ci)
│   └── lint.md         # /lint (project:ci)
├── git/
│   ├── commit.md       # /commit (project:git)
│   └── pr.md           # /pr (project:git)
└── docs/
    ├── generate.md     # /generate (project:docs)
    └── publish.md      # /publish (project:docs)

Benefits:

• Logical grouping by category
• Namespace shown in /help
• Easier to find related commands

Use when: 15+ commands, clear categories

Best Practices

Command Design

1. Single responsibility: One command, one task
2. Clear descriptions: Self-explanatory in /help
3. Explicit dependencies: Use allowed-tools when needed
4. Document arguments: Always provide argument-hint
5. Consistent naming: Use verb-noun pattern (review-pr, fix-issue)

Argument Handling

1. Validate arguments: Check for required arguments in prompt
2. Provide defaults: Suggest defaults when arguments missing
3. Document format: Explain expected argument format
4. Handle edge cases: Consider missing or invalid arguments

---
argument-hint: [pr-number]
---

$IF($1,
Review PR #$1,
Please provide a PR number. Usage: /review-pr [number]
)

File References

1. Explicit paths: Use clear file paths
2. Check existence: Handle missing files gracefully
3. Relative paths: Use project-relative paths
4. Glob support: Consider using Glob tool for patterns

Bash Commands

1. Limit scope: Use Bash(git:*) not Bash(*)
2. Safe commands: Avoid destructive operations
3. Handle errors: Consider command failures
4. Keep fast: Long-running commands slow invocation

Documentation

1. Add comments: Explain complex logic
2. Provide examples: Show usage in comments
3. List requirements: Document dependencies
4. Version commands: Note breaking changes

---
description: Deploy application to environment
argument-hint: [environment] [version]
---

<!--
Usage: /deploy [staging|production] [version]
Requires: AWS credentials configured
Example: /deploy staging v1.2.3
-->

Deploy application to $1 environment using version $2...

Common Patterns

Review Pattern

---
description: Review code changes
allowed-tools: Read, Bash(git:*)
---

Files changed: !`git diff --name-only`

Review each file for:

1. Code quality and style
2. Potential bugs or issues
3. Test coverage
4. Documentation needs

Provide specific feedback for each file.

Testing Pattern

---
description: Run tests for specific file
argument-hint: [test-file]
allowed-tools: Bash(npm:*)
---

Run tests: !`npm test $1`

Analyze results and suggest fixes for failures.

Documentation Pattern

---
description: Generate documentation for file
argument-hint: [source-file]
---

Generate comprehensive documentation for @$1 including:

- Function/class descriptions
- Parameter documentation
- Return value descriptions
- Usage examples
- Edge cases and errors

Workflow Pattern

---
description: Complete PR workflow
argument-hint: [pr-number]
allowed-tools: Bash(gh:*), Read
---

PR #$1 Workflow:

1. Fetch PR: !`gh pr view $1`
2. Review changes
3. Run checks
4. Approve or request changes

Troubleshooting

Command not appearing:

• Check file is in correct directory
• Verify .md extension present
• Ensure valid Markdown format
• Restart Claude Code

Arguments not working:

• Verify $1, $2 syntax correct
• Check argument-hint matches usage
• Ensure no extra spaces

Bash execution failing:

• Check allowed-tools includes Bash
• Verify command syntax in backticks
• Test command in terminal first
• Check for required permissions

File references not working:

• Verify @ syntax correct
• Check file path is valid
• Ensure Read tool allowed
• Use absolute or project-relative paths

Plugin-Specific Features

CLAUDE_PLUGIN_ROOT Variable

Plugin commands have access to ${CLAUDE_PLUGIN_ROOT}, an environment variable that resolves to the plugin's absolute path.

Purpose:

• Reference plugin files portably
• Execute plugin scripts
• Load plugin configuration
• Access plugin templates

Basic usage:

---
description: Analyze using plugin script
allowed-tools: Bash(node:*)
---

Run analysis: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1`

Review results and report findings.

Common patterns:

# Execute plugin script

!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/script.sh`

# Load plugin configuration

@${CLAUDE_PLUGIN_ROOT}/config/settings.json

# Use plugin template

@${CLAUDE_PLUGIN_ROOT}/templates/report.md

# Access plugin resources

@${CLAUDE_PLUGIN_ROOT}/docs/reference.md

Why use it:

• Works across all installations
• Portable between systems
• No hardcoded paths needed
• Essential for multi-file plugins

Plugin Command Organization

Plugin commands discovered automatically from commands/ directory:

plugin-name/
├── commands/
│   ├── foo.md              # /foo (plugin:plugin-name)
│   ├── bar.md              # /bar (plugin:plugin-name)
│   └── utils/
│       └── helper.md       # /helper (plugin:plugin-name:utils)
└── plugin.json

Namespace benefits:

• Logical command grouping
• Shown in /help output
• Avoid name conflicts
• Organize related commands

Naming conventions:

• Use descriptive action names
• Avoid generic names (test, run)
• Consider plugin-specific prefix
• Use hyphens for multi-word names

Plugin Command Patterns

Configuration-based pattern:

---
description: Deploy using plugin configuration
argument-hint: [environment]
allowed-tools: Read, Bash(*)
---

Load configuration: @${CLAUDE_PLUGIN_ROOT}/config/$1-deploy.json

Deploy to $1 using configuration settings.
Monitor deployment and report status.

Template-based pattern:

---
description: Generate docs from template
argument-hint: [component]
---

Template: @${CLAUDE_PLUGIN_ROOT}/templates/docs.md

Generate documentation for $1 following template structure.

Multi-script pattern:

---
description: Complete build workflow
allowed-tools: Bash(*)
---

Build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`
Test: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh`
Package: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/package.sh`

Review outputs and report workflow status.

See references/plugin-features-reference.md for detailed patterns.

Integration with Plugin Components

Commands can integrate with other plugin components for powerful workflows.

Agent Integration

Launch plugin agents for complex tasks:

---
description: Deep code review
argument-hint: [file-path]
---

Initiate comprehensive review of @$1 using the code-reviewer agent.

The agent will analyze:

- Code structure
- Security issues
- Performance
- Best practices

Agent uses plugin resources:

- ${CLAUDE_PLUGIN_ROOT}/config/rules.json
- ${CLAUDE_PLUGIN_ROOT}/checklists/review.md

Key points:

• Agent must exist in plugin/agents/ directory
• Claude uses Task tool to launch agent
• Document agent capabilities
• Reference plugin resources agent uses

Skill Integration

Leverage plugin skills for specialized knowledge:

---
description: Document API with standards
argument-hint: [api-file]
---

Document API in @$1 following plugin standards.

Use the api-docs-standards skill to ensure:

- Complete endpoint documentation
- Consistent formatting
- Example quality
- Error documentation

Generate production-ready API docs.

Key points:

• Skill must exist in plugin/skills/ directory
• Mention skill name to trigger invocation
• Document skill purpose
• Explain what skill provides

Hook Coordination

Design commands that work with plugin hooks:

• Commands can prepare state for hooks to process
• Hooks execute automatically on tool events
• Commands should document expected hook behavior
• Guide Claude on interpreting hook output

See references/plugin-features-reference.md for examples of commands that coordinate with hooks

Multi-Component Workflows

Combine agents, skills, and scripts:

---
description: Comprehensive review workflow
argument-hint: [file]
allowed-tools: Bash(node:*), Read
---

Target: @$1

Phase 1 - Static Analysis:
!`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1`

Phase 2 - Deep Review:
Launch code-reviewer agent for detailed analysis.

Phase 3 - Standards Check:
Use coding-standards skill for validation.

Phase 4 - Report:
Template: @${CLAUDE_PLUGIN_ROOT}/templates/review.md

Compile findings into report following template.

When to use:

• Complex multi-step workflows
• Leverage multiple plugin capabilities
• Require specialized analysis
• Need structured outputs

Validation Patterns

Commands should validate inputs and resources before processing.

Argument Validation

---
description: Deploy with validation
argument-hint: [environment]
---

Validate environment: !`echo "$1" | grep -E "^(dev|staging|prod)$" || echo "INVALID"`

If $1 is valid environment:
Deploy to $1
Otherwise:
Explain valid environments: dev, staging, prod
Show usage: /deploy [environment]

File Existence Checks

---
description: Process configuration
argument-hint: [config-file]
---

Check file exists: !`test -f $1 && echo "EXISTS" || echo "MISSING"`

If file exists:
Process configuration: @$1
Otherwise:
Explain where to place config file
Show expected format
Provide example configuration

Plugin Resource Validation

---
description: Run plugin analyzer
allowed-tools: Bash(test:*)
---

Validate plugin setup:

- Script: !`test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo "✓" || echo "✗"`
- Config: !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo "✓" || echo "✗"`

If all checks pass, run analysis.
Otherwise, report missing components.

Error Handling

---
description: Build with error handling
allowed-tools: Bash(*)
---

Execute build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh 2>&1 || echo "BUILD_FAILED"`

If build succeeded:
Report success and output location
If build failed:
Analyze error output
Suggest likely causes
Provide troubleshooting steps

Best practices:

• Validate early in command
• Provide helpful error messages
• Suggest corrective actions
• Handle edge cases gracefully

For detailed frontmatter field specifications, see references/frontmatter-reference.md. For plugin-specific features and patterns, see references/plugin-features-reference.md. For command pattern examples, see examples/ directory.

Hook Development for Claude Code Plugins

Overview

Hooks are event-driven automation scripts that execute in response to Claude Code events. Use hooks to validate operations, enforce policies, add context, and integrate external tools into workflows.

Key capabilities: - Validate tool calls before execution (PreToolUse) - React to tool results (PostToolUse) - Enforce completion standards (Stop, SubagentStop) - Load project context (SessionStart) - Automate workflows across the development lifecycle

Hook Types

Prompt-Based Hooks (Recommended)

Use LLM-driven decision making for context-aware validation:

{
  "type": "prompt",
  "prompt": "Evaluate if this tool use is appropriate: $TOOL_INPUT",
  "timeout": 30
}

Supported events: Stop, SubagentStop, UserPromptSubmit, PreToolUse

Benefits: - Context-aware decisions based on natural language reasoning - Flexible evaluation logic without bash scripting - Better edge case handling - Easier to maintain and extend

Command Hooks

Execute bash commands for deterministic checks:

{
  "type": "command",
  "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh",
  "timeout": 60
}

Use for: - Fast deterministic validations - File system operations - External tool integrations - Performance-critical checks

Hook Configuration Formats

Plugin hooks.json Format

For plugin hooks in hooks/hooks.json, use wrapper format:

{
  "description": "Brief explanation of hooks (optional)",
  "hooks": {
    "PreToolUse": [...],
    "Stop": [...],
    "SessionStart": [...]
  }
}

Key points: - description field is optional - hooks field is required wrapper containing actual hook events - This is the plugin-specific format

Example:

{
  "description": "Validation hooks for code quality",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/validate.sh"
          }
        ]
      }
    ]
  }
}

Settings Format (Direct)

For user settings in .claude/settings.json, use direct format:

{
  "PreToolUse": [...],
  "Stop": [...],
  "SessionStart": [...]
}

Key points: - No wrapper - events directly at top level - No description field - This is the settings format

Important: The examples below show the hook event structure that goes inside either format. For plugin hooks.json, wrap these in {"hooks": {...}}.

Hook Events

PreToolUse

Execute before any tool runs. Use to approve, deny, or modify tool calls.

Example (prompt-based):

{
  "PreToolUse": [
    {
      "matcher": "Write|Edit",
      "hooks": [
        {
          "type": "prompt",
          "prompt": "Validate file write safety. Check: system paths, credentials, path traversal, sensitive content. Return 'approve' or 'deny'."
        }
      ]
    }
  ]
}

Output for PreToolUse:

{
  "hookSpecificOutput": {
    "permissionDecision": "allow|deny|ask",
    "updatedInput": {"field": "modified_value"}
  },
  "systemMessage": "Explanation for Claude"
}

PostToolUse

Execute after tool completes. Use to react to results, provide feedback, or log.

Example:

{
  "PostToolUse": [
    {
      "matcher": "Edit",
      "hooks": [
        {
          "type": "prompt",
          "prompt": "Analyze edit result for potential issues: syntax errors, security vulnerabilities, breaking changes. Provide feedback."
        }
      ]
    }
  ]
}

Output behavior: - Exit 0: stdout shown in transcript - Exit 2: stderr fed back to Claude - systemMessage included in context

Stop

Execute when main agent considers stopping. Use to validate completeness.

Example:

{
  "Stop": [
    {
      "matcher": "*",
      "hooks": [
        {
          "type": "prompt",
          "prompt": "Verify task completion: tests run, build succeeded, questions answered. Return 'approve' to stop or 'block' with reason to continue."
        }
      ]
    }
  ]
}

Decision output:

{
  "decision": "approve|block",
  "reason": "Explanation",
  "systemMessage": "Additional context"
}

SubagentStop

Execute when subagent considers stopping. Use to ensure subagent completed its task.

Similar to Stop hook, but for subagents.

UserPromptSubmit

Execute when user submits a prompt. Use to add context, validate, or block prompts.

Example:

{
  "UserPromptSubmit": [
    {
      "matcher": "*",
      "hooks": [
        {
          "type": "prompt",
          "prompt": "Check if prompt requires security guidance. If discussing auth, permissions, or API security, return relevant warnings."
        }
      ]
    }
  ]
}

SessionStart

Execute when Claude Code session begins. Use to load context and set environment.

Example:

{
  "SessionStart": [
    {
      "matcher": "*",
      "hooks": [
        {
          "type": "command",
          "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh"
        }
      ]
    }
  ]
}

Special capability: Persist environment variables using $CLAUDE_ENV_FILE:

echo "export PROJECT_TYPE=nodejs" >> "$CLAUDE_ENV_FILE"

See examples/load-context.sh for complete example.

SessionEnd

Execute when session ends. Use for cleanup, logging, and state preservation.

PreCompact

Execute before context compaction. Use to add critical information to preserve.

Notification

Execute when Claude sends notifications. Use to react to user notifications.

Hook Output Format

Standard Output (All Hooks)

{
  "continue": true,
  "suppressOutput": false,
  "systemMessage": "Message for Claude"
}

• continue: If false, halt processing (default true)
• suppressOutput: Hide output from transcript (default false)
• systemMessage: Message shown to Claude

Exit Codes

• 0 - Success (stdout shown in transcript)
• 2 - Blocking error (stderr fed back to Claude)
• Other - Non-blocking error

Hook Input Format

All hooks receive JSON via stdin with common fields:

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.txt",
  "cwd": "/current/working/dir",
  "permission_mode": "ask|allow",
  "hook_event_name": "PreToolUse"
}

Event-specific fields:

• PreToolUse/PostToolUse: tool_name, tool_input, tool_result
• UserPromptSubmit: user_prompt
• Stop/SubagentStop: reason

Access fields in prompts using $TOOL_INPUT, $TOOL_RESULT, $USER_PROMPT, etc.

Environment Variables

Available in all command hooks:

• $CLAUDE_PROJECT_DIR - Project root path
• $CLAUDE_PLUGIN_ROOT - Plugin directory (use for portable paths)
• $CLAUDE_ENV_FILE - SessionStart only: persist env vars here
• $CLAUDE_CODE_REMOTE - Set if running in remote context

Always use ${CLAUDE_PLUGIN_ROOT} in hook commands for portability:

{
  "type": "command",
  "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
}

Plugin Hook Configuration

In plugins, define hooks in hooks/hooks.json:

{
  "PreToolUse": [
    {
      "matcher": "Write|Edit",
      "hooks": [
        {
          "type": "prompt",
          "prompt": "Validate file write safety"
        }
      ]
    }
  ],
  "Stop": [
    {
      "matcher": "*",
      "hooks": [
        {
          "type": "prompt",
          "prompt": "Verify task completion"
        }
      ]
    }
  ],
  "SessionStart": [
    {
      "matcher": "*",
      "hooks": [
        {
          "type": "command",
          "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh",
          "timeout": 10
        }
      ]
    }
  ]
}

Plugin hooks merge with user's hooks and run in parallel.

Matchers

Tool Name Matching

Exact match:

"matcher": "Write"

Multiple tools:

"matcher": "Read|Write|Edit"

Wildcard (all tools):

"matcher": "*"

Regex patterns:

"matcher": "mcp__.*__delete.*"  // All MCP delete tools

Note: Matchers are case-sensitive.

Common Patterns

// All MCP tools
"matcher": "mcp__.*"

// Specific plugin's MCP tools
"matcher": "mcp__plugin_asana_.*"

// All file operations
"matcher": "Read|Write|Edit"

// Bash commands only
"matcher": "Bash"

Security Best Practices

Input Validation

Always validate inputs in command hooks:

#!/bin/bash
set -euo pipefail

input=$(cat)
tool_name=$(echo "$input" | jq -r '.tool_name')

# Validate tool name format
if [[ ! "$tool_name" =~ ^[a-zA-Z0-9_]+$ ]]; then
  echo '{"decision": "deny", "reason": "Invalid tool name"}' >&2
  exit 2
fi

Path Safety

Check for path traversal and sensitive files:

file_path=$(echo "$input" | jq -r '.tool_input.file_path')

# Deny path traversal
if [[ "$file_path" == *".."* ]]; then
  echo '{"decision": "deny", "reason": "Path traversal detected"}' >&2
  exit 2
fi

# Deny sensitive files
if [[ "$file_path" == *".env"* ]]; then
  echo '{"decision": "deny", "reason": "Sensitive file"}' >&2
  exit 2
fi

See examples/validate-write.sh and examples/validate-bash.sh for complete examples.

Quote All Variables

# GOOD: Quoted
echo "$file_path"
cd "$CLAUDE_PROJECT_DIR"

# BAD: Unquoted (injection risk)
echo $file_path
cd $CLAUDE_PROJECT_DIR

Set Appropriate Timeouts

{
  "type": "command",
  "command": "bash script.sh",
  "timeout": 10
}

Defaults: Command hooks (60s), Prompt hooks (30s)

Performance Considerations

Parallel Execution

All matching hooks run in parallel:

{
  "PreToolUse": [
    {
      "matcher": "Write",
      "hooks": [
        {"type": "command", "command": "check1.sh"},  // Parallel
        {"type": "command", "command": "check2.sh"},  // Parallel
        {"type": "prompt", "prompt": "Validate..."}   // Parallel
      ]
    }
  ]
}

Design implications: - Hooks don't see each other's output - Non-deterministic ordering - Design for independence

Optimization

1. Use command hooks for quick deterministic checks
2. Use prompt hooks for complex reasoning
3. Cache validation results in temp files
4. Minimize I/O in hot paths

Temporarily Active Hooks

Create hooks that activate conditionally by checking for a flag file or configuration:

Pattern: Flag file activation

#!/bin/bash
# Only active when flag file exists
FLAG_FILE="$CLAUDE_PROJECT_DIR/.enable-strict-validation"

if [ ! -f "$FLAG_FILE" ]; then
  # Flag not present, skip validation
  exit 0
fi

# Flag present, run validation
input=$(cat)
# ... validation logic ...

Pattern: Configuration-based activation

#!/bin/bash
# Check configuration for activation
CONFIG_FILE="$CLAUDE_PROJECT_DIR/.claude/plugin-config.json"

if [ -f "$CONFIG_FILE" ]; then
  enabled=$(jq -r '.strictMode // false' "$CONFIG_FILE")
  if [ "$enabled" != "true" ]; then
    exit 0  # Not enabled, skip
  fi
fi

# Enabled, run hook logic
input=$(cat)
# ... hook logic ...

Use cases: - Enable strict validation only when needed - Temporary debugging hooks - Project-specific hook behavior - Feature flags for hooks

Best practice: Document activation mechanism in plugin README so users know how to enable/disable temporary hooks.

Hook Lifecycle and Limitations

Hooks Load at Session Start

Important: Hooks are loaded when Claude Code session starts. Changes to hook configuration require restarting Claude Code.

Cannot hot-swap hooks: - Editing hooks/hooks.json won't affect current session - Adding new hook scripts won't be recognized - Changing hook commands/prompts won't update - Must restart Claude Code: exit and run claude again

To test hook changes: 1. Edit hook configuration or scripts 2. Exit Claude Code session 3. Restart: claude or cc 4. New hook configuration loads 5. Test hooks with claude --debug

Hook Validation at Startup

Hooks are validated when Claude Code starts: - Invalid JSON in hooks.json causes loading failure - Missing scripts cause warnings - Syntax errors reported in debug mode

Use /hooks command to review loaded hooks in current session.

Debugging Hooks

Enable Debug Mode

claude --debug

Look for hook registration, execution logs, input/output JSON, and timing information.

Test Hook Scripts

Test command hooks directly:

echo '{"tool_name": "Write", "tool_input": {"file_path": "/test"}}' | \
  bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh

echo "Exit code: $?"

Validate JSON Output

Ensure hooks output valid JSON:

output=$(./your-hook.sh < test-input.json)
echo "$output" | jq .

Quick Reference

Hook Events Summary

Best Practices

DO: - ✅ Use prompt-based hooks for complex logic - ✅ Use ${CLAUDE_PLUGIN_ROOT} for portability - ✅ Validate all inputs in command hooks - ✅ Quote all bash variables - ✅ Set appropriate timeouts - ✅ Return structured JSON output - ✅ Test hooks thoroughly

DON'T: - ❌ Use hardcoded paths - ❌ Trust user input without validation - ❌ Create long-running hooks - ❌ Rely on hook execution order - ❌ Modify global state unpredictably - ❌ Log sensitive information

Additional Resources

Reference Files

For detailed patterns and advanced techniques, consult:

• references/patterns.md - Common hook patterns (8+ proven patterns)
• references/migration.md - Migrating from basic to advanced hooks
• references/advanced.md - Advanced use cases and techniques

Example Hook Scripts

Working examples in examples/:

• validate-write.sh - File write validation example
• validate-bash.sh - Bash command validation example
• load-context.sh - SessionStart context loading example

Utility Scripts

Development tools in scripts/:

• validate-hook-schema.sh - Validate hooks.json structure and syntax
• test-hook.sh - Test hooks with sample input before deployment
• hook-linter.sh - Check hook scripts for common issues and best practices

External Resources

• Official Docs: https://docs.claude.com/en/docs/claude-code/hooks
• Examples: See security-guidance plugin in marketplace
• Testing: Use claude --debug for detailed logs
• Validation: Use jq to validate hook JSON output

Implementation Workflow

To implement hooks in a plugin:

1. Identify events to hook into (PreToolUse, Stop, SessionStart, etc.)
2. Decide between prompt-based (flexible) or command (deterministic) hooks
3. Write hook configuration in hooks/hooks.json
4. For command hooks, create hook scripts
5. Use ${CLAUDE_PLUGIN_ROOT} for all file references
6. Validate configuration with scripts/validate-hook-schema.sh hooks/hooks.json
7. Test hooks with scripts/test-hook.sh before deployment
8. Test in Claude Code with claude --debug
9. Document hooks in plugin README

Focus on prompt-based hooks for most use cases. Reserve command hooks for performance-critical or deterministic checks.

MCP Integration for Claude Code Plugins

Overview

Model Context Protocol (MCP) enables Claude Code plugins to integrate with external services and APIs by providing structured tool access. Use MCP integration to expose external service capabilities as tools within Claude Code.

Key capabilities: - Connect to external services (databases, APIs, file systems) - Provide 10+ related tools from a single service - Handle OAuth and complex authentication flows - Bundle MCP servers with plugins for automatic setup

MCP Server Configuration Methods

Plugins can bundle MCP servers in two ways:

Method 1: Dedicated .mcp.json (Recommended)

Create .mcp.json at plugin root:

{
  "database-tools": {
    "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
    "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
    "env": {
      "DB_URL": "${DB_URL}"
    }
  }
}

Benefits: - Clear separation of concerns - Easier to maintain - Better for multiple servers

Method 2: Inline in plugin.json

Add mcpServers field to plugin.json:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

Benefits: - Single configuration file - Good for simple single-server plugins

MCP Server Types

stdio (Local Process)

Execute local MCP servers as child processes. Best for local tools and custom servers.

Configuration:

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
    "env": {
      "LOG_LEVEL": "debug"
    }
  }
}

Use cases: - File system access - Local database connections - Custom MCP servers - NPM-packaged MCP servers

Process management: - Claude Code spawns and manages the process - Communicates via stdin/stdout - Terminates when Claude Code exits

SSE (Server-Sent Events)

Connect to hosted MCP servers with OAuth support. Best for cloud services.

Configuration:

{
  "asana": {
    "type": "sse",
    "url": "https://mcp.asana.com/sse"
  }
}

Use cases: - Official hosted MCP servers (Asana, GitHub, etc.) - Cloud services with MCP endpoints - OAuth-based authentication - No local installation needed

Authentication: - OAuth flows handled automatically - User prompted on first use - Tokens managed by Claude Code

HTTP (REST API)

Connect to RESTful MCP servers with token authentication.

Configuration:

{
  "api-service": {
    "type": "http",
    "url": "https://api.example.com/mcp",
    "headers": {
      "Authorization": "Bearer ${API_TOKEN}",
      "X-Custom-Header": "value"
    }
  }
}

Use cases: - REST API-based MCP servers - Token-based authentication - Custom API backends - Stateless interactions

WebSocket (Real-time)

Connect to WebSocket MCP servers for real-time bidirectional communication.

Configuration:

{
  "realtime-service": {
    "type": "ws",
    "url": "wss://mcp.example.com/ws",
    "headers": {
      "Authorization": "Bearer ${TOKEN}"
    }
  }
}

Use cases: - Real-time data streaming - Persistent connections - Push notifications from server - Low-latency requirements

Environment Variable Expansion

All MCP configurations support environment variable substitution:

${CLAUDE_PLUGIN_ROOT} - Plugin directory (always use for portability):

{
  "command": "${CLAUDE_PLUGIN_ROOT}/servers/my-server"
}

User environment variables - From user's shell:

{
  "env": {
    "API_KEY": "${MY_API_KEY}",
    "DATABASE_URL": "${DB_URL}"
  }
}

Best practice: Document all required environment variables in plugin README.

MCP Tool Naming

When MCP servers provide tools, they're automatically prefixed:

Format: mcp__plugin_<plugin-name>_<server-name>__<tool-name>

Example: - Plugin: asana - Server: asana - Tool: create_task - Full name: mcp__plugin_asana_asana__asana_create_task

Using MCP Tools in Commands

Pre-allow specific MCP tools in command frontmatter:

---
allowed-tools: [
  "mcp__plugin_asana_asana__asana_create_task",
  "mcp__plugin_asana_asana__asana_search_tasks"
]
---

Wildcard (use sparingly):

---
allowed-tools: ["mcp__plugin_asana_asana__*"]
---

Best practice: Pre-allow specific tools, not wildcards, for security.

Lifecycle Management

Automatic startup: - MCP servers start when plugin enables - Connection established before first tool use - Restart required for configuration changes

Lifecycle: 1. Plugin loads 2. MCP configuration parsed 3. Server process started (stdio) or connection established (SSE/HTTP/WS) 4. Tools discovered and registered 5. Tools available as mcp__plugin_...__...

Viewing servers: Use /mcp command to see all servers including plugin-provided ones.

Authentication Patterns

OAuth (SSE/HTTP)

OAuth handled automatically by Claude Code:

{
  "type": "sse",
  "url": "https://mcp.example.com/sse"
}

User authenticates in browser on first use. No additional configuration needed.

Token-Based (Headers)

Static or environment variable tokens:

{
  "type": "http",
  "url": "https://api.example.com",
  "headers": {
    "Authorization": "Bearer ${API_TOKEN}"
  }
}

Document required environment variables in README.

Environment Variables (stdio)

Pass configuration to MCP server:

{
  "command": "python",
  "args": ["-m", "my_mcp_server"],
  "env": {
    "DATABASE_URL": "${DB_URL}",
    "API_KEY": "${API_KEY}",
    "LOG_LEVEL": "info"
  }
}

Integration Patterns

Pattern 1: Simple Tool Wrapper

Commands use MCP tools with user interaction:

# Command: create-item.md
---
allowed-tools: ["mcp__plugin_name_server__create_item"]
---

Steps:
1. Gather item details from user
2. Use mcp__plugin_name_server__create_item
3. Confirm creation

Use for: Adding validation or preprocessing before MCP calls.

Pattern 2: Autonomous Agent

Agents use MCP tools autonomously:

# Agent: data-analyzer.md

Analysis Process:
1. Query data via mcp__plugin_db_server__query
2. Process and analyze results
3. Generate insights report

Use for: Multi-step MCP workflows without user interaction.

Pattern 3: Multi-Server Plugin

Integrate multiple MCP servers:

{
  "github": {
    "type": "sse",
    "url": "https://mcp.github.com/sse"
  },
  "jira": {
    "type": "sse",
    "url": "https://mcp.jira.com/sse"
  }
}

Use for: Workflows spanning multiple services.

Security Best Practices

Use HTTPS/WSS

Always use secure connections:

✅ "url": "https://mcp.example.com/sse"
❌ "url": "http://mcp.example.com/sse"

Token Management

DO: - ✅ Use environment variables for tokens - ✅ Document required env vars in README - ✅ Let OAuth flow handle authentication

DON'T: - ❌ Hardcode tokens in configuration - ❌ Commit tokens to git - ❌ Share tokens in documentation

Permission Scoping

Pre-allow only necessary MCP tools:

✅ allowed-tools: [
  "mcp__plugin_api_server__read_data",
  "mcp__plugin_api_server__create_item"
]

❌ allowed-tools: ["mcp__plugin_api_server__*"]

Error Handling

Connection Failures

Handle MCP server unavailability: - Provide fallback behavior in commands - Inform user of connection issues - Check server URL and configuration

Tool Call Errors

Handle failed MCP operations: - Validate inputs before calling MCP tools - Provide clear error messages - Check rate limiting and quotas

Configuration Errors

Validate MCP configuration: - Test server connectivity during development - Validate JSON syntax - Check required environment variables

Performance Considerations

Lazy Loading

MCP servers connect on-demand: - Not all servers connect at startup - First tool use triggers connection - Connection pooling managed automatically

Batching

Batch similar requests when possible:

# Good: Single query with filters
tasks = search_tasks(project="X", assignee="me", limit=50)

# Avoid: Many individual queries
for id in task_ids:
    task = get_task(id)

Testing MCP Integration

Local Testing

1. Configure MCP server in .mcp.json
2. Install plugin locally (.claude-plugin/)
3. Run /mcp to verify server appears
4. Test tool calls in commands
5. Check claude --debug logs for connection issues

Validation Checklist

• [ ] MCP configuration is valid JSON
• [ ] Server URL is correct and accessible
• [ ] Required environment variables documented
• [ ] Tools appear in /mcp output
• [ ] Authentication works (OAuth or tokens)
• [ ] Tool calls succeed from commands
• [ ] Error cases handled gracefully

Debugging

Enable Debug Logging

claude --debug

Look for: - MCP server connection attempts - Tool discovery logs - Authentication flows - Tool call errors

Common Issues

Server not connecting: - Check URL is correct - Verify server is running (stdio) - Check network connectivity - Review authentication configuration

Tools not available: - Verify server connected successfully - Check tool names match exactly - Run /mcp to see available tools - Restart Claude Code after config changes

Authentication failing: - Clear cached auth tokens - Re-authenticate - Check token scopes and permissions - Verify environment variables set

Quick Reference

MCP Server Types

Configuration Checklist

• [ ] Server type specified (stdio/SSE/HTTP/ws)
• [ ] Type-specific fields complete (command or url)
• [ ] Authentication configured
• [ ] Environment variables documented
• [ ] HTTPS/WSS used (not HTTP/WS)
• [ ] ${CLAUDE_PLUGIN_ROOT} used for paths

Best Practices

DO: - ✅ Use ${CLAUDE_PLUGIN_ROOT} for portable paths - ✅ Document required environment variables - ✅ Use secure connections (HTTPS/WSS) - ✅ Pre-allow specific MCP tools in commands - ✅ Test MCP integration before publishing - ✅ Handle connection and tool errors gracefully

DON'T: - ❌ Hardcode absolute paths - ❌ Commit credentials to git - ❌ Use HTTP instead of HTTPS - ❌ Pre-allow all tools with wildcards - ❌ Skip error handling - ❌ Forget to document setup

Additional Resources

Reference Files

For detailed information, consult:

• references/server-types.md - Deep dive on each server type
• references/authentication.md - Authentication patterns and OAuth
• references/tool-usage.md - Using MCP tools in commands and agents

Example Configurations

Working examples in examples/:

• stdio-server.json - Local stdio MCP server
• sse-server.json - Hosted SSE server with OAuth
• http-server.json - REST API with token auth

External Resources

• Official MCP Docs: https://modelcontextprotocol.io/
• Claude Code MCP Docs: https://docs.claude.com/en/docs/claude-code/mcp
• MCP SDK: @modelcontextprotocol/sdk
• Testing: Use claude --debug and /mcp command

Implementation Workflow

To add MCP integration to a plugin:

1. Choose MCP server type (stdio, SSE, HTTP, ws)
2. Create .mcp.json at plugin root with configuration
3. Use ${CLAUDE_PLUGIN_ROOT} for all file references
4. Document required environment variables in README
5. Test locally with /mcp command
6. Pre-allow MCP tools in relevant commands
7. Handle authentication (OAuth or tokens)
8. Test error cases (connection failures, auth errors)
9. Document MCP integration in plugin README

Focus on stdio for custom/local servers, SSE for hosted services with OAuth.

Plugin Settings Pattern for Claude Code Plugins

Overview

Plugins can store user-configurable settings and state in .claude/plugin-name.local.md files within the project directory. This pattern uses YAML frontmatter for structured configuration and markdown content for prompts or additional context.

Key characteristics: - File location: .claude/plugin-name.local.md in project root - Structure: YAML frontmatter + markdown body - Purpose: Per-project plugin configuration and state - Usage: Read from hooks, commands, and agents - Lifecycle: User-managed (not in git, should be in .gitignore)

File Structure

Basic Template

---
enabled: true
setting1: value1
setting2: value2
numeric_setting: 42
list_setting: ["item1", "item2"]
---

# Additional Context

This markdown body can contain:
- Task descriptions
- Additional instructions
- Prompts to feed back to Claude
- Documentation or notes

Example: Plugin State File

.claude/my-plugin.local.md:

---
enabled: true
strict_mode: false
max_retries: 3
notification_level: info
coordinator_session: team-leader
---

# Plugin Configuration

This plugin is configured for standard validation mode.
Contact @team-lead with questions.

Reading Settings Files

From Hooks (Bash Scripts)

Pattern: Check existence and parse frontmatter

#!/bin/bash
set -euo pipefail

# Define state file path
STATE_FILE=".claude/my-plugin.local.md"

# Quick exit if file doesn't exist
if [[ ! -f "$STATE_FILE" ]]; then
  exit 0  # Plugin not configured, skip
fi

# Parse YAML frontmatter (between --- markers)
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$STATE_FILE")

# Extract individual fields
ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//' | sed 's/^"\(.*\)"$/\1/')
STRICT_MODE=$(echo "$FRONTMATTER" | grep '^strict_mode:' | sed 's/strict_mode: *//' | sed 's/^"\(.*\)"$/\1/')

# Check if enabled
if [[ "$ENABLED" != "true" ]]; then
  exit 0  # Disabled
fi

# Use configuration in hook logic
if [[ "$STRICT_MODE" == "true" ]]; then
  # Apply strict validation
  # ...
fi

See examples/read-settings-hook.sh for complete working example.

From Commands

Commands can read settings files to customize behavior:

---
description: Process data with plugin
allowed-tools: ["Read", "Bash"]
---

# Process Command

Steps:
1. Check if settings exist at `.claude/my-plugin.local.md`
2. Read configuration using Read tool
3. Parse YAML frontmatter to extract settings
4. Apply settings to processing logic
5. Execute with configured behavior

From Agents

Agents can reference settings in their instructions:

---
name: configured-agent
description: Agent that adapts to project settings
---

Check for plugin settings at `.claude/my-plugin.local.md`.
If present, parse YAML frontmatter and adapt behavior according to:
- enabled: Whether plugin is active
- mode: Processing mode (strict, standard, lenient)
- Additional configuration fields

Parsing Techniques

Extract Frontmatter

# Extract everything between --- markers
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$FILE")

Read Individual Fields

String fields:

VALUE=$(echo "$FRONTMATTER" | grep '^field_name:' | sed 's/field_name: *//' | sed 's/^"\(.*\)"$/\1/')

Boolean fields:

ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//')
# Compare: if [[ "$ENABLED" == "true" ]]; then

Numeric fields:

MAX=$(echo "$FRONTMATTER" | grep '^max_value:' | sed 's/max_value: *//')
# Use: if [[ $MAX -gt 100 ]]; then

Read Markdown Body

Extract content after second ---:

# Get everything after closing ---
BODY=$(awk '/^---$/{i++; next} i>=2' "$FILE")

Common Patterns

Pattern 1: Temporarily Active Hooks

Use settings file to control hook activation:

#!/bin/bash
STATE_FILE=".claude/security-scan.local.md"

# Quick exit if not configured
if [[ ! -f "$STATE_FILE" ]]; then
  exit 0
fi

# Read enabled flag
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$STATE_FILE")
ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//')

if [[ "$ENABLED" != "true" ]]; then
  exit 0  # Disabled
fi

# Run hook logic
# ...

Use case: Enable/disable hooks without editing hooks.json (requires restart).

Pattern 2: Agent State Management

Store agent-specific state and configuration:

.claude/multi-agent-swarm.local.md:

---
agent_name: auth-agent
task_number: 3.5
pr_number: 1234
coordinator_session: team-leader
enabled: true
dependencies: ["Task 3.4"]
---

# Task Assignment

Implement JWT authentication for the API.

**Success Criteria:**
- Authentication endpoints created
- Tests passing
- PR created and CI green

Read from hooks to coordinate agents:

AGENT_NAME=$(echo "$FRONTMATTER" | grep '^agent_name:' | sed 's/agent_name: *//')
COORDINATOR=$(echo "$FRONTMATTER" | grep '^coordinator_session:' | sed 's/coordinator_session: *//')

# Send notification to coordinator
tmux send-keys -t "$COORDINATOR" "Agent $AGENT_NAME completed task" Enter

Pattern 3: Configuration-Driven Behavior

.claude/my-plugin.local.md:

---
validation_level: strict
max_file_size: 1000000
allowed_extensions: [".js", ".ts", ".tsx"]
enable_logging: true
---

# Validation Configuration

Strict mode enabled for this project.
All writes validated against security policies.

Use in hooks or commands:

LEVEL=$(echo "$FRONTMATTER" | grep '^validation_level:' | sed 's/validation_level: *//')

case "$LEVEL" in
  strict)
    # Apply strict validation
    ;;
  standard)
    # Apply standard validation
    ;;
  lenient)
    # Apply lenient validation
    ;;
esac

Creating Settings Files

From Commands

Commands can create settings files:

# Setup Command

Steps:
1. Ask user for configuration preferences
2. Create `.claude/my-plugin.local.md` with YAML frontmatter
3. Set appropriate values based on user input
4. Inform user that settings are saved
5. Remind user to restart Claude Code for hooks to recognize changes

Template Generation

Provide template in plugin README:

## Configuration

Create `.claude/my-plugin.local.md` in your project:

\`\`\`markdown
---
enabled: true
mode: standard
max_retries: 3
---

# Plugin Configuration

Your settings are active.
\`\`\`

After creating or editing, restart Claude Code for changes to take effect.

Best Practices

File Naming

✅ DO: - Use .claude/plugin-name.local.md format - Match plugin name exactly - Use .local.md suffix for user-local files

❌ DON'T: - Use different directory (not .claude/) - Use inconsistent naming - Use .md without .local (might be committed)

Gitignore

Always add to .gitignore:

.claude/*.local.md
.claude/*.local.json

Document this in plugin README.

Defaults

Provide sensible defaults when settings file doesn't exist:

if [[ ! -f "$STATE_FILE" ]]; then
  # Use defaults
  ENABLED=true
  MODE=standard
else
  # Read from file
  # ...
fi

Validation

Validate settings values:

MAX=$(echo "$FRONTMATTER" | grep '^max_value:' | sed 's/max_value: *//')

# Validate numeric range
if ! [[ "$MAX" =~ ^[0-9]+$ ]] || [[ $MAX -lt 1 ]] || [[ $MAX -gt 100 ]]; then
  echo "⚠️  Invalid max_value in settings (must be 1-100)" >&2
  MAX=10  # Use default
fi

Restart Requirement

Important: Settings changes require Claude Code restart.

Document in your README:

## Changing Settings

After editing `.claude/my-plugin.local.md`:
1. Save the file
2. Exit Claude Code
3. Restart: `claude` or `cc`
4. New settings will be loaded

Hooks cannot be hot-swapped within a session.

Security Considerations

Sanitize User Input

When writing settings files from user input:

# Escape quotes in user input
SAFE_VALUE=$(echo "$USER_INPUT" | sed 's/"/\\"/g')

# Write to file
cat > "$STATE_FILE" <<EOF
---
user_setting: "$SAFE_VALUE"
---
EOF

Validate File Paths

If settings contain file paths:

FILE_PATH=$(echo "$FRONTMATTER" | grep '^data_file:' | sed 's/data_file: *//')

# Check for path traversal
if [[ "$FILE_PATH" == *".."* ]]; then
  echo "⚠️  Invalid path in settings (path traversal)" >&2
  exit 2
fi

Permissions

Settings files should be: - Readable by user only (chmod 600) - Not committed to git - Not shared between users

Real-World Examples

multi-agent-swarm Plugin

.claude/multi-agent-swarm.local.md:

---
agent_name: auth-implementation
task_number: 3.5
pr_number: 1234
coordinator_session: team-leader
enabled: true
dependencies: ["Task 3.4"]
additional_instructions: Use JWT tokens, not sessions
---

# Task: Implement Authentication

Build JWT-based authentication for the REST API.
Coordinate with auth-agent on shared types.

Hook usage (agent-stop-notification.sh): - Checks if file exists (line 15-18: quick exit if not) - Parses frontmatter to get coordinator_session, agent_name, enabled - Sends notifications to coordinator if enabled - Allows quick activation/deactivation via enabled: true/false

ralph-loop Plugin

.claude/ralph-loop.local.md:

---
iteration: 1
max_iterations: 10
completion_promise: "All tests passing and build successful"
---

Fix all the linting errors in the project.
Make sure tests pass after each fix.

Hook usage (stop-hook.sh): - Checks if file exists (line 15-18: quick exit if not active) - Reads iteration count and max_iterations - Extracts completion_promise for loop termination - Reads body as the prompt to feed back - Updates iteration count on each loop

Quick Reference

File Location

project-root/
└── .claude/
    └── plugin-name.local.md

Frontmatter Parsing

# Extract frontmatter
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$FILE")

# Read field
VALUE=$(echo "$FRONTMATTER" | grep '^field:' | sed 's/field: *//' | sed 's/^"\(.*\)"$/\1/')

Body Parsing

# Extract body (after second ---)
BODY=$(awk '/^---$/{i++; next} i>=2' "$FILE")

Quick Exit Pattern

if [[ ! -f ".claude/my-plugin.local.md" ]]; then
  exit 0  # Not configured
fi

Additional Resources

Reference Files

For detailed implementation patterns:

• references/parsing-techniques.md - Complete guide to parsing YAML frontmatter and markdown bodies
• references/real-world-examples.md - Deep dive into multi-agent-swarm and ralph-loop implementations

Example Files

Working examples in examples/:

• read-settings-hook.sh - Hook that reads and uses settings
• create-settings-command.md - Command that creates settings file
• example-settings.md - Template settings file

Utility Scripts

Development tools in scripts/:

• validate-settings.sh - Validate settings file structure
• parse-frontmatter.sh - Extract frontmatter fields

Implementation Workflow

To add settings to a plugin:

1. Design settings schema (which fields, types, defaults)
2. Create template file in plugin documentation
3. Add gitignore entry for .claude/*.local.md
4. Implement settings parsing in hooks/commands
5. Use quick-exit pattern (check file exists, check enabled field)
6. Document settings in plugin README with template
7. Remind users that changes require Claude Code restart

Focus on keeping settings simple and providing good defaults when settings file doesn't exist.

Plugin Structure for Claude Code

Overview

Claude Code plugins follow a standardized directory structure with automatic component discovery. Understanding this structure enables creating well-organized, maintainable plugins that integrate seamlessly with Claude Code.

Key concepts: - Conventional directory layout for automatic discovery - Manifest-driven configuration in .claude-plugin/plugin.json - Component-based organization (commands, agents, skills, hooks) - Portable path references using ${CLAUDE_PLUGIN_ROOT} - Explicit vs. auto-discovered component loading

Directory Structure

Every Claude Code plugin follows this organizational pattern:

plugin-name/
├── .claude-plugin/
│   └── plugin.json          # Required: Plugin manifest
├── commands/                 # Slash commands (.md files)
├── agents/                   # Subagent definitions (.md files)
├── skills/                   # Agent skills (subdirectories)
│   └── skill-name/
│       └── SKILL.md         # Required for each skill
├── hooks/
│   └── hooks.json           # Event handler configuration
├── .mcp.json                # MCP server definitions
└── scripts/                 # Helper scripts and utilities

Critical rules:

1. Manifest location: The plugin.json manifest MUST be in .claude-plugin/ directory
2. Component locations: All component directories (commands, agents, skills, hooks) MUST be at plugin root level, NOT nested inside .claude-plugin/
3. Optional components: Only create directories for components the plugin actually uses
4. Naming convention: Use kebab-case for all directory and file names

Plugin Manifest (plugin.json)

The manifest defines plugin metadata and configuration. Located at .claude-plugin/plugin.json:

Required Fields

{
  "name": "plugin-name"
}

Name requirements: - Use kebab-case format (lowercase with hyphens) - Must be unique across installed plugins - No spaces or special characters - Example: code-review-assistant, test-runner, api-docs

Recommended Metadata

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Brief explanation of plugin purpose",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://example.com"
  },
  "homepage": "https://docs.example.com",
  "repository": "https://github.com/user/plugin-name",
  "license": "MIT",
  "keywords": ["testing", "automation", "ci-cd"]
}

Version format: Follow semantic versioning (MAJOR.MINOR.PATCH) Keywords: Use for plugin discovery and categorization

Component Path Configuration

Specify custom paths for components (supplements default directories):

{
  "name": "plugin-name",
  "commands": "./custom-commands",
  "agents": ["./agents", "./specialized-agents"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./.mcp.json"
}

Important: Custom paths supplement defaults—they don't replace them. Components in both default directories and custom paths will load.

Path rules: - Must be relative to plugin root - Must start with ./ - Cannot use absolute paths - Support arrays for multiple locations

Component Organization

Commands

Location: commands/ directory Format: Markdown files with YAML frontmatter Auto-discovery: All .md files in commands/ load automatically

Example structure:

commands/
├── review.md        # /review command
├── test.md          # /test command
└── deploy.md        # /deploy command

File format:

---
name: command-name
description: Command description
---

Command implementation instructions...

Usage: Commands integrate as native slash commands in Claude Code

Agents

Location: agents/ directory Format: Markdown files with YAML frontmatter Auto-discovery: All .md files in agents/ load automatically

Example structure:

agents/
├── code-reviewer.md
├── test-generator.md
└── refactorer.md

File format:

---
description: Agent role and expertise
capabilities:
  - Specific task 1
  - Specific task 2
---

Detailed agent instructions and knowledge...

Usage: Users can invoke agents manually, or Claude Code selects them automatically based on task context

Skills

Location: skills/ directory with subdirectories per skill Format: Each skill in its own directory with SKILL.md file Auto-discovery: All SKILL.md files in skill subdirectories load automatically

Example structure:

skills/
├── api-testing/
│   ├── SKILL.md
│   ├── scripts/
│   │   └── test-runner.py
│   └── references/
│       └── api-spec.md
└── database-migrations/
    ├── SKILL.md
    └── examples/
        └── migration-template.sql

SKILL.md format:

---
name: Skill Name
description: When to use this skill
version: 1.0.0
---

Skill instructions and guidance...

Supporting files: Skills can include scripts, references, examples, or assets in subdirectories

Usage: Claude Code autonomously activates skills based on task context matching the description

Hooks

Location: hooks/hooks.json or inline in plugin.json Format: JSON configuration defining event handlers Registration: Hooks register automatically when plugin enables

Example structure:

hooks/
├── hooks.json           # Hook configuration
└── scripts/
    ├── validate.sh      # Hook script
    └── check-style.sh   # Hook script

Configuration format:

{
  "PreToolUse": [{
    "matcher": "Write|Edit",
    "hooks": [{
      "type": "command",
      "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/validate.sh",
      "timeout": 30
    }]
  }]
}

Available events: PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification

Usage: Hooks execute automatically in response to Claude Code events

MCP Servers

Location: .mcp.json at plugin root or inline in plugin.json Format: JSON configuration for MCP server definitions Auto-start: Servers start automatically when plugin enables

Example format:

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/server.js"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}

Usage: MCP servers integrate seamlessly with Claude Code's tool system

Portable Path References

${CLAUDE_PLUGIN_ROOT}

Use ${CLAUDE_PLUGIN_ROOT} environment variable for all intra-plugin path references:

{
  "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/run.sh"
}

Why it matters: Plugins install in different locations depending on: - User installation method (marketplace, local, npm) - Operating system conventions - User preferences

Where to use it: - Hook command paths - MCP server command arguments - Script execution references - Resource file paths

Never use: - Hardcoded absolute paths (/Users/name/plugins/...) - Relative paths from working directory (./scripts/... in commands) - Home directory shortcuts (~/plugins/...)

Path Resolution Rules

In manifest JSON fields (hooks, MCP servers):

"command": "${CLAUDE_PLUGIN_ROOT}/scripts/tool.sh"

In component files (commands, agents, skills):

Reference scripts at: ${CLAUDE_PLUGIN_ROOT}/scripts/helper.py

In executed scripts:

#!/bin/bash
# ${CLAUDE_PLUGIN_ROOT} available as environment variable
source "${CLAUDE_PLUGIN_ROOT}/lib/common.sh"

File Naming Conventions

Component Files

Commands: Use kebab-case .md files - code-review.md → /code-review - run-tests.md → /run-tests - api-docs.md → /api-docs

Agents: Use kebab-case .md files describing role - test-generator.md - code-reviewer.md - performance-analyzer.md

Skills: Use kebab-case directory names - api-testing/ - database-migrations/ - error-handling/

Supporting Files

Scripts: Use descriptive kebab-case names with appropriate extensions - validate-input.sh - generate-report.py - process-data.js

Documentation: Use kebab-case markdown files - api-reference.md - migration-guide.md - best-practices.md

Configuration: Use standard names - hooks.json - .mcp.json - plugin.json

Auto-Discovery Mechanism

Claude Code automatically discovers and loads components:

1. Plugin manifest: Reads .claude-plugin/plugin.json when plugin enables
2. Commands: Scans commands/ directory for .md files
3. Agents: Scans agents/ directory for .md files
4. Skills: Scans skills/ for subdirectories containing SKILL.md
5. Hooks: Loads configuration from hooks/hooks.json or manifest
6. MCP servers: Loads configuration from .mcp.json or manifest

Discovery timing: - Plugin installation: Components register with Claude Code - Plugin enable: Components become available for use - No restart required: Changes take effect on next Claude Code session

Override behavior: Custom paths in plugin.json supplement (not replace) default directories

Best Practices

Organization

1. Logical grouping: Group related components together
2. Put test-related commands, agents, and skills together

3. Create subdirectories in scripts/ for different purposes

4. Minimal manifest: Keep plugin.json lean

5. Only specify custom paths when necessary
6. Rely on auto-discovery for standard layouts

7. Use inline configuration only for simple cases

8. Documentation: Include README files

9. Plugin root: Overall purpose and usage
10. Component directories: Specific guidance
11. Script directories: Usage and requirements

Naming

1. Consistency: Use consistent naming across components
2. If command is test-runner, name related agent test-runner-agent

3. Match skill directory names to their purpose

4. Clarity: Use descriptive names that indicate purpose

5. Good: api-integration-testing/, code-quality-checker.md

6. Avoid: utils/, misc.md, temp.sh

7. Length: Balance brevity with clarity

8. Commands: 2-3 words (review-pr, run-ci)
9. Agents: Describe role clearly (code-reviewer, test-generator)
10. Skills: Topic-focused (error-handling, api-design)

Portability

1. Always use ${CLAUDE_PLUGIN_ROOT}: Never hardcode paths
2. Test on multiple systems: Verify on macOS, Linux, Windows
3. Document dependencies: List required tools and versions
4. Avoid system-specific features: Use portable bash/Python constructs

Maintenance

1. Version consistently: Update version in plugin.json for releases
2. Deprecate gracefully: Mark old components clearly before removal
3. Document breaking changes: Note changes affecting existing users
4. Test thoroughly: Verify all components work after changes

Common Patterns

Minimal Plugin

Single command with no dependencies:

my-plugin/
├── .claude-plugin/
│   └── plugin.json    # Just name field
└── commands/
    └── hello.md       # Single command

Full-Featured Plugin

Complete plugin with all component types:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/          # User-facing commands
├── agents/            # Specialized subagents
├── skills/            # Auto-activating skills
├── hooks/             # Event handlers
│   ├── hooks.json
│   └── scripts/
├── .mcp.json          # External integrations
└── scripts/           # Shared utilities

Skill-Focused Plugin

Plugin providing only skills:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    ├── skill-one/
    │   └── SKILL.md
    └── skill-two/
        └── SKILL.md

Troubleshooting

Component not loading: - Verify file is in correct directory with correct extension - Check YAML frontmatter syntax (commands, agents, skills) - Ensure skill has SKILL.md (not README.md or other name) - Confirm plugin is enabled in Claude Code settings

Path resolution errors: - Replace all hardcoded paths with ${CLAUDE_PLUGIN_ROOT} - Verify paths are relative and start with ./ in manifest - Check that referenced files exist at specified paths - Test with echo $CLAUDE_PLUGIN_ROOT in hook scripts

Auto-discovery not working: - Confirm directories are at plugin root (not in .claude-plugin/) - Check file naming follows conventions (kebab-case, correct extensions) - Verify custom paths in manifest are correct - Restart Claude Code to reload plugin configuration

Conflicts between plugins: - Use unique, descriptive component names - Namespace commands with plugin name if needed - Document potential conflicts in plugin README - Consider command prefixes for related functionality

For detailed examples and advanced patterns, see files in references/ and examples/ directories.

Skill Development for Claude Code Plugins

This skill provides guidance for creating effective skills for Claude Code plugins.

About Skills

Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks—they transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess.

What Skills Provide

1. Specialized workflows - Multi-step procedures for specific domains
2. Tool integrations - Instructions for working with specific file formats or APIs
3. Domain expertise - Company-specific knowledge, schemas, business logic
4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks

Anatomy of a Skill

Every skill consists of a required SKILL.md file and optional bundled resources:

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

SKILL.md (required)

Metadata Quality: The name and description in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. "This skill should be used when..." instead of "Use this skill when...").

Bundled Resources (optional)

Scripts (scripts/)

Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.

• When to include: When the same code is being rewritten repeatedly or deterministic reliability is needed
• Example: scripts/rotate_pdf.py for PDF rotation tasks
• Benefits: Token efficient, deterministic, may be executed without loading into context
• Note: Scripts may still need to be read by Claude for patching or environment-specific adjustments

References (references/)

Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking.

• When to include: For documentation that Claude should reference while working
• Examples: references/finance.md for financial schemas, references/mnda.md for company NDA template, references/policies.md for company policies, references/api_docs.md for API specifications
• Use cases: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
• Benefits: Keeps SKILL.md lean, loaded only when Claude determines it's needed
• Best practice: If files are large (>10k words), include grep search patterns in SKILL.md
• Avoid duplication: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.

Assets (assets/)

Files not intended to be loaded into context, but rather used within the output Claude produces.

• When to include: When the skill needs files that will be used in the final output
• Examples: assets/logo.png for brand assets, assets/slides.pptx for PowerPoint templates, assets/frontend-template/ for HTML/React boilerplate, assets/font.ttf for typography
• Use cases: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
• Benefits: Separates output resources from documentation, enables Claude to use files without loading them into context

Progressive Disclosure Design Principle

Skills use a three-level loading system to manage context efficiently:

1. Metadata (name + description) - Always in context (~100 words)
2. SKILL.md body - When skill triggers (<5k words)
3. Bundled resources - As needed by Claude (Unlimited*)

*Unlimited because scripts can be executed without reading into context window.

Skill Creation Process

To create a skill, follow the "Skill Creation Process" in order, skipping steps only if there is a clear reason why they are not applicable.

Step 1: Understanding the Skill with Concrete Examples

Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.

To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.

For example, when building an image-editor skill, relevant questions include:

• "What functionality should the image-editor skill support? Editing, rotating, anything else?"
• "Can you give some examples of how this skill would be used?"
• "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
• "What would a user say that should trigger this skill?"

To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.

Conclude this step when there is a clear sense of the functionality the skill should support.

Step 2: Planning the Reusable Skill Contents

To turn concrete examples into an effective skill, analyze each example by:

1. Considering how to execute on the example from scratch
2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly

Example: When building a pdf-editor skill to handle queries like "Help me rotate this PDF," the analysis shows:

1. Rotating a PDF requires re-writing the same code each time
2. A scripts/rotate_pdf.py script would be helpful to store in the skill

Example: When designing a frontend-webapp-builder skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:

1. Writing a frontend webapp requires the same boilerplate HTML/React each time
2. An assets/hello-world/ template containing the boilerplate HTML/React project files would be helpful to store in the skill

Example: When building a big-query skill to handle queries like "How many users have logged in today?" the analysis shows:

1. Querying BigQuery requires re-discovering the table schemas and relationships each time
2. A references/schema.md file documenting the table schemas would be helpful to store in the skill

For Claude Code plugins: When building a hooks skill, the analysis shows: 1. Developers repeatedly need to validate hooks.json and test hook scripts 2. scripts/validate-hook-schema.sh and scripts/test-hook.sh utilities would be helpful 3. references/patterns.md for detailed hook patterns to avoid bloating SKILL.md

To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.

Step 3: Create Skill Structure

For Claude Code plugins, create the skill directory structure:

mkdir -p plugin-name/skills/skill-name/{references,examples,scripts}
touch plugin-name/skills/skill-name/SKILL.md

Note: Unlike the generic skill-creator which uses init_skill.py, plugin skills are created directly in the plugin's skills/ directory with a simpler manual structure.

Step 4: Edit the Skill

When editing the (newly-created or existing) skill, remember that the skill is being created for another instance of Claude to use. Focus on including information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively.

Start with Reusable Skill Contents

To begin implementation, start with the reusable resources identified above: scripts/, references/, and assets/ files. Note that this step may require user input. For example, when implementing a brand-guidelines skill, the user may need to provide brand assets or templates to store in assets/, or documentation to store in references/.

Also, delete any example files and directories not needed for the skill. Create only the directories you actually need (references/, examples/, scripts/).

Update SKILL.md

Writing Style: Write the entire skill using imperative/infinitive form (verb-first instructions), not second person. Use objective, instructional language (e.g., "To accomplish X, do Y" rather than "You should do X" or "If you need to do X"). This maintains consistency and clarity for AI consumption.

Description (Frontmatter): Use third-person format with specific trigger phrases:

---
name: Skill Name
description: This skill should be used when the user asks to "specific phrase 1", "specific phrase 2", "specific phrase 3". Include exact phrases users would say that should trigger this skill. Be concrete and specific.
version: 0.1.0
---

Good description examples:

description: This skill should be used when the user asks to "create a hook", "add a PreToolUse hook", "validate tool use", "implement prompt-based hooks", or mentions hook events (PreToolUse, PostToolUse, Stop).

Bad description examples:

description: Use this skill when working with hooks.  # Wrong person, vague
description: Load when user needs hook help.  # Not third person
description: Provides hook guidance.  # No trigger phrases

To complete SKILL.md body, answer the following questions:

1. What is the purpose of the skill, in a few sentences?
2. When should the skill be used? (Include this in frontmatter description with specific triggers)
3. In practice, how should Claude use the skill? All reusable skill contents developed above should be referenced so that Claude knows how to use them.

Keep SKILL.md lean: Target 1,500-2,000 words for the body. Move detailed content to references/: - Detailed patterns → references/patterns.md - Advanced techniques → references/advanced.md - Migration guides → references/migration.md - API references → references/api-reference.md

Reference resources in SKILL.md:

## Additional Resources

### Reference Files

For detailed patterns and techniques, consult:
- **`references/patterns.md`** - Common patterns
- **`references/advanced.md`** - Advanced use cases

### Example Files

Working examples in `examples/`:
- **`example-script.sh`** - Working example

Step 5: Validate and Test

For plugin skills, validation is different from generic skills:

1. Check structure: Skill directory in plugin-name/skills/skill-name/
2. Validate SKILL.md: Has frontmatter with name and description
3. Check trigger phrases: Description includes specific user queries
4. Verify writing style: Body uses imperative/infinitive form, not second person
5. Test progressive disclosure: SKILL.md is lean (~1,500-2,000 words), detailed content in references/
6. Check references: All referenced files exist
7. Validate examples: Examples are complete and correct
8. Test scripts: Scripts are executable and work correctly

Use the skill-reviewer agent:

Ask: "Review my skill and check if it follows best practices"

The skill-reviewer agent will check description quality, content organization, and progressive disclosure.

Step 6: Iterate

After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.

Iteration workflow: 1. Use the skill on real tasks 2. Notice struggles or inefficiencies 3. Identify how SKILL.md or bundled resources should be updated 4. Implement changes and test again

Common improvements: - Strengthen trigger phrases in description - Move long sections from SKILL.md to references/ - Add missing examples or scripts - Clarify ambiguous instructions - Add edge case handling

Plugin-Specific Considerations

Skill Location in Plugins

Plugin skills live in the plugin's skills/ directory:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
├── agents/
└── skills/
    └── my-skill/
        ├── SKILL.md
        ├── references/
        ├── examples/
        └── scripts/

Auto-Discovery

Claude Code automatically discovers skills: - Scans skills/ directory - Finds subdirectories containing SKILL.md - Loads skill metadata (name + description) always - Loads SKILL.md body when skill triggers - Loads references/examples when needed

No Packaging Needed

Plugin skills are distributed as part of the plugin, not as separate ZIP files. Users get skills when they install the plugin.

Testing in Plugins

Test skills by installing plugin locally:

# Test with --plugin-dir
cc --plugin-dir /path/to/plugin

# Ask questions that should trigger the skill
# Verify skill loads correctly

Examples from Plugin-Dev

Study the skills in this plugin as examples of best practices:

hook-development skill: - Excellent trigger phrases: "create a hook", "add a PreToolUse hook", etc. - Lean SKILL.md (1,651 words) - 3 references/ files for detailed content - 3 examples/ of working hooks - 3 scripts/ utilities

agent-development skill: - Strong triggers: "create an agent", "agent frontmatter", etc. - Focused SKILL.md (1,438 words) - References include the AI generation prompt from Claude Code - Complete agent examples

plugin-settings skill: - Specific triggers: "plugin settings", ".local.md files", "YAML frontmatter" - References show real implementations (multi-agent-swarm, ralph-loop) - Working parsing scripts

Each demonstrates progressive disclosure and strong triggering.

Progressive Disclosure in Practice

What Goes in SKILL.md

Include (always loaded when skill triggers): - Core concepts and overview - Essential procedures and workflows - Quick reference tables - Pointers to references/examples/scripts - Most common use cases

Keep under 3,000 words, ideally 1,500-2,000 words

What Goes in references/

Move to references/ (loaded as needed): - Detailed patterns and advanced techniques - Comprehensive API documentation - Migration guides - Edge cases and troubleshooting - Extensive examples and walkthroughs

Each reference file can be large (2,000-5,000+ words)

What Goes in examples/

Working code examples: - Complete, runnable scripts - Configuration files - Template files - Real-world usage examples

Users can copy and adapt these directly

What Goes in scripts/

Utility scripts: - Validation tools - Testing helpers - Parsing utilities - Automation scripts

Should be executable and documented

Writing Style Requirements

Imperative/Infinitive Form

Write using verb-first instructions, not second person:

Correct (imperative):

To create a hook, define the event type.
Configure the MCP server with authentication.
Validate settings before use.

Incorrect (second person):

You should create a hook by defining the event type.
You need to configure the MCP server.
You must validate settings before use.

Third-Person in Description

The frontmatter description must use third person:

Correct:

description: This skill should be used when the user asks to "create X", "configure Y"...

Incorrect:

description: Use this skill when you want to create X...
description: Load this skill when user asks...

Objective, Instructional Language

Focus on what to do, not who should do it:

Correct:

Parse the frontmatter using sed.
Extract fields with grep.
Validate values before use.

Incorrect:

You can parse the frontmatter...
Claude should extract fields...
The user might validate values...

Validation Checklist

Before finalizing a skill:

Structure: - [ ] SKILL.md file exists with valid YAML frontmatter - [ ] Frontmatter has name and description fields - [ ] Markdown body is present and substantial - [ ] Referenced files actually exist

Description Quality: - [ ] Uses third person ("This skill should be used when...") - [ ] Includes specific trigger phrases users would say - [ ] Lists concrete scenarios ("create X", "configure Y") - [ ] Not vague or generic

Content Quality: - [ ] SKILL.md body uses imperative/infinitive form - [ ] Body is focused and lean (1,500-2,000 words ideal, <5k max) - [ ] Detailed content moved to references/ - [ ] Examples are complete and working - [ ] Scripts are executable and documented

Progressive Disclosure: - [ ] Core concepts in SKILL.md - [ ] Detailed docs in references/ - [ ] Working code in examples/ - [ ] Utilities in scripts/ - [ ] SKILL.md references these resources

Testing: - [ ] Skill triggers on expected user queries - [ ] Content is helpful for intended tasks - [ ] No duplicated information across files - [ ] References load when needed

Common Mistakes to Avoid

Mistake 1: Weak Trigger Description

❌ Bad:

description: Provides guidance for working with hooks.

Why bad: Vague, no specific trigger phrases, not third person

✅ Good:

description: This skill should be used when the user asks to "create a hook", "add a PreToolUse hook", "validate tool use", or mentions hook events. Provides comprehensive hooks API guidance.

Why good: Third person, specific phrases, concrete scenarios

Mistake 2: Too Much in SKILL.md

❌ Bad:

skill-name/
└── SKILL.md  (8,000 words - everything in one file)

Why bad: Bloats context when skill loads, detailed content always loaded

✅ Good:

skill-name/
├── SKILL.md  (1,800 words - core essentials)
└── references/
    ├── patterns.md (2,500 words)
    └── advanced.md (3,700 words)

Why good: Progressive disclosure, detailed content loaded only when needed

Mistake 3: Second Person Writing

❌ Bad:

You should start by reading the configuration file.
You need to validate the input.
You can use the grep tool to search.

Why bad: Second person, not imperative form

✅ Good:

Start by reading the configuration file.
Validate the input before processing.
Use the grep tool to search for patterns.

Why good: Imperative form, direct instructions

Mistake 4: Missing Resource References

❌ Bad:

# SKILL.md

[Core content]

[No mention of references/ or examples/]

Why bad: Claude doesn't know references exist

✅ Good:

# SKILL.md

[Core content]

## Additional Resources

### Reference Files
- **`references/patterns.md`** - Detailed patterns
- **`references/advanced.md`** - Advanced techniques

### Examples
- **`examples/script.sh`** - Working example

Why good: Claude knows where to find additional information

Quick Reference

Minimal Skill

skill-name/
└── SKILL.md

Good for: Simple knowledge, no complex resources needed

Standard Skill (Recommended)

skill-name/
├── SKILL.md
├── references/
│   └── detailed-guide.md
└── examples/
    └── working-example.sh

Good for: Most plugin skills with detailed documentation

Complete Skill

skill-name/
├── SKILL.md
├── references/
│   ├── patterns.md
│   └── advanced.md
├── examples/
│   ├── example1.sh
│   └── example2.json
└── scripts/
    └── validate.sh

Good for: Complex domains with validation utilities

Best Practices Summary

✅ DO: - Use third-person in description ("This skill should be used when...") - Include specific trigger phrases ("create X", "configure Y") - Keep SKILL.md lean (1,500-2,000 words) - Use progressive disclosure (move details to references/) - Write in imperative/infinitive form - Reference supporting files clearly - Provide working examples - Create utility scripts for common operations - Study plugin-dev's skills as templates

❌ DON'T: - Use second person anywhere - Have vague trigger conditions - Put everything in SKILL.md (>3,000 words without references/) - Write in second person ("You should...") - Leave resources unreferenced - Include broken or incomplete examples - Skip validation

Additional Resources

Study These Skills

Plugin-dev's skills demonstrate best practices: - ../hook-development/ - Progressive disclosure, utilities - ../agent-development/ - AI-assisted creation, references - ../mcp-integration/ - Comprehensive references - ../plugin-settings/ - Real-world examples - ../command-development/ - Clear critical concepts - ../plugin-structure/ - Good organization

Reference Files

For complete skill-creator methodology: - references/skill-creator-original.md - Full original skill-creator content

Implementation Workflow

To create a skill for your plugin:

1. Understand use cases: Identify concrete examples of skill usage
2. Plan resources: Determine what scripts/references/examples needed
3. Create structure: mkdir -p skills/skill-name/{references,examples,scripts}
4. Write SKILL.md:
5. Frontmatter with third-person description and trigger phrases
6. Lean body (1,500-2,000 words) in imperative form
7. Reference supporting files
8. Add resources: Create references/, examples/, scripts/ as needed
9. Validate: Check description, writing style, organization
10. Test: Verify skill loads on expected triggers
11. Iterate: Improve based on usage

Focus on strong trigger descriptions, progressive disclosure, and imperative writing style for effective skills that load when needed and provide targeted guidance.

Plugin Creation Workflow

Guide the user through creating a complete, high-quality Claude Code plugin from initial concept to tested implementation. Follow a systematic approach: understand requirements, design components, clarify details, implement following best practices, validate, and test.

Core Principles

• Ask clarifying questions: Identify all ambiguities about plugin purpose, triggering, scope, and components. Ask specific, concrete questions rather than making assumptions. Wait for user answers before proceeding with implementation.
• Load relevant skills: Use the Skill tool to load plugin-dev skills when needed (plugin-structure, hook-development, agent-development, etc.)
• Use specialized agents: Leverage agent-creator, plugin-validator, and skill-reviewer agents for AI-assisted development
• Follow best practices: Apply patterns from plugin-dev's own implementation
• Progressive disclosure: Create lean skills with references/examples
• Use TodoWrite: Track all progress throughout all phases

Initial request: $ARGUMENTS

Phase 1: Discovery

Goal: Understand what plugin needs to be built and what problem it solves

Actions:

1. Create todo list with all 7 phases
2. If plugin purpose is clear from arguments:
3. Summarize understanding
4. Identify plugin type (integration, workflow, analysis, toolkit, etc.)
5. If plugin purpose is unclear, ask user:
6. What problem does this plugin solve?
7. Who will use it and when?
8. What should it do?
9. Any similar plugins to reference?
10. Summarize understanding and confirm with user before proceeding

Output: Clear statement of plugin purpose and target users

Phase 2: Component Planning

Goal: Determine what plugin components are needed

MUST load plugin-structure skill using Skill tool before this phase.

Actions:

1. Load plugin-structure skill to understand component types
2. Analyze plugin requirements and determine needed components:
3. Skills: Specialized knowledge OR user-initiated actions (deploy, configure, analyze). Skills are the preferred format for both — see note below.
4. Agents: Autonomous tasks? (validation, generation, analysis)
5. Hooks: Event-driven automation? (validation, notifications)
6. MCP: External service integration? (databases, APIs)
7. Settings: User configuration? (.local.md files)

Note: The commands/ directory is a legacy format. For new plugins, user-invoked slash commands should be created as skills in skills/<name>/SKILL.md. Both are loaded identically — the only difference is file layout. commands/ remains an acceptable legacy alternative.

1. For each component type needed, identify:
2. How many of each type
3. What each one does
4. Rough triggering/usage patterns
5. Present component plan to user as table: | Component Type | Count | Purpose | |----------------|-------|---------| | Skills | 5 | Hook patterns, MCP usage, deploy, configure, validate | | Agents | 1 | Autonomous validation | | Hooks | 0 | Not needed | | MCP | 1 | Database integration |
6. Get user confirmation or adjustments

Output: Confirmed list of components to create

Phase 3: Detailed Design & Clarifying Questions

Goal: Specify each component in detail and resolve all ambiguities

CRITICAL: This is one of the most important phases. DO NOT SKIP.

Actions:

1. For each component in the plan, identify underspecified aspects:
2. Skills: What triggers them? What knowledge do they provide? How detailed? For user-invoked skills: what arguments, what tools, interactive or automated?
3. Agents: When to trigger (proactive/reactive)? What tools? Output format?
4. Hooks: Which events? Prompt or command based? Validation criteria?
5. MCP: What server type? Authentication? Which tools?

6. Settings: What fields? Required vs optional? Defaults?

7. Present all questions to user in organized sections (one section per component type)

8. Wait for answers before proceeding to implementation

9. If user says "whatever you think is best", provide specific recommendations and get explicit confirmation

Example questions for a skill:

• What specific user queries should trigger this skill?
• Should it include utility scripts? What functionality?
• How detailed should the core SKILL.md be vs references/?
• Any real-world examples to include?

Example questions for an agent:

• Should this agent trigger proactively after certain actions, or only when explicitly requested?
• What tools does it need (Read, Write, Bash, etc.)?
• What should the output format be?
• Any specific quality standards to enforce?

Output: Detailed specification for each component

Phase 4: Plugin Structure Creation

Goal: Create plugin directory structure and manifest

Actions:

1. Determine plugin name (kebab-case, descriptive)
2. Choose plugin location:
3. Ask user: "Where should I create the plugin?"
4. Offer options: current directory, ../new-plugin-name, custom path
5. Create directory structure using bash: bash mkdir -p plugin-name/.claude-plugin mkdir -p plugin-name/skills/<skill-name> # one dir per skill, each with a SKILL.md mkdir -p plugin-name/agents # if needed mkdir -p plugin-name/hooks # if needed # Note: plugin-name/commands/ is a legacy alternative to skills/ — prefer skills/
6. Create plugin.json manifest using Write tool: json { "name": "plugin-name", "version": "0.1.0", "description": "[brief description]", "author": { "name": "[author from user or default]", "email": "[email or default]" } }
7. Create README.md template
8. Create .gitignore if needed (for .claude/*.local.md, etc.)
9. Initialize git repo if creating new directory

Output: Plugin directory structure created and ready for components

Phase 5: Component Implementation

Goal: Create each component following best practices

LOAD RELEVANT SKILLS before implementing each component type:

• Skills: Load skill-development skill
• Legacy commands/ format (only if user explicitly requests): Load command-development skill
• Agents: Load agent-development skill
• Hooks: Load hook-development skill
• MCP: Load mcp-integration skill
• Settings: Load plugin-settings skill

Actions for each component:

For Skills:

1. Load skill-development skill using Skill tool
2. For each skill:
3. Ask user for concrete usage examples (or use from Phase 3)
4. Plan resources (scripts/, references/, examples/)
5. Create skill directory: skills/<skill-name>/
6. Write SKILL.md with:
   • Third-person description with specific trigger phrases
   • Lean body (1,500-2,000 words) in imperative form
   • References to supporting files
7. For user-invoked skills (slash commands): include description, argument-hint, and allowed-tools frontmatter; write instructions FOR Claude (not TO user)
8. Create reference files for detailed content
9. Create example files for working code
10. Create utility scripts if needed
11. Use skill-reviewer agent to validate each skill

For legacy commands/ format (only if user explicitly requests):

Prefer skills/<name>/SKILL.md for new plugins. Use commands/ only when maintaining an existing plugin that already uses this layout.

1. Load command-development skill using Skill tool
2. For each command:
3. Write command markdown with frontmatter
4. Include clear description and argument-hint
5. Specify allowed-tools (minimal necessary)
6. Write instructions FOR Claude (not TO user)
7. Provide usage examples and tips
8. Reference relevant skills if applicable

For Agents:

1. Load agent-development skill using Skill tool
2. For each agent, use agent-creator agent:
3. Provide description of what agent should do
4. Agent-creator generates: identifier, whenToUse with examples, systemPrompt
5. Create agent markdown file with frontmatter and system prompt
6. Add appropriate model, color, and tools
7. Validate with validate-agent.sh script

For Hooks:

1. Load hook-development skill using Skill tool
2. For each hook:
3. Create hooks/hooks.json with hook configuration
4. Prefer prompt-based hooks for complex logic
5. Use ${CLAUDE_PLUGIN_ROOT} for portability
6. Create hook scripts if needed (in examples/ not scripts/)
7. Test with validate-hook-schema.sh and test-hook.sh utilities

For MCP:

1. Load mcp-integration skill using Skill tool
2. Create .mcp.json configuration with:
3. Server type (stdio for local, SSE for hosted)
4. Command and args (with ${CLAUDE_PLUGIN_ROOT})
5. extensionToLanguage mapping if LSP
6. Environment variables as needed
7. Document required env vars in README
8. Provide setup instructions

For Settings:

1. Load plugin-settings skill using Skill tool
2. Create settings template in README
3. Create example .claude/plugin-name.local.md file (as documentation)
4. Implement settings reading in hooks/commands as needed
5. Add to .gitignore: .claude/*.local.md

Progress tracking: Update todos as each component is completed

Output: All plugin components implemented

Phase 6: Validation & Quality Check

Goal: Ensure plugin meets quality standards and works correctly

Actions:

1. Run plugin-validator agent:
2. Use plugin-validator agent to comprehensively validate plugin
3. Check: manifest, structure, naming, components, security

4. Review validation report

5. Fix critical issues:

6. Address any critical errors from validation

7. Fix any warnings that indicate real problems

8. Review with skill-reviewer (if plugin has skills):

9. For each skill, use skill-reviewer agent
10. Check description quality, progressive disclosure, writing style

11. Apply recommendations

12. Test agent triggering (if plugin has agents):

13. For each agent, verify blocks are clear
14. Check triggering conditions are specific

15. Run validate-agent.sh on agent files

16. Test hook configuration (if plugin has hooks):

17. Run validate-hook-schema.sh on hooks/hooks.json
18. Test hook scripts with test-hook.sh

19. Verify ${CLAUDE_PLUGIN_ROOT} usage

20. Present findings:

21. Summary of validation results
22. Any remaining issues

23. Overall quality assessment

24. Ask user: "Validation complete. Issues found: [count critical], [count warnings]. Would you like me to fix them now, or proceed to testing?"

Output: Plugin validated and ready for testing

Phase 7: Testing & Verification

Goal: Test that plugin works correctly in Claude Code

Actions:

1. Installation instructions:
2. Show user how to test locally: bash cc --plugin-dir /path/to/plugin-name

3. Or copy to .claude-plugin/ for project testing

4. Verification checklist for user to perform:

5. [ ] Skills load when triggered (ask questions with trigger phrases)
6. [ ] User-invoked skills appear in /help and execute correctly
7. [ ] Agents trigger on appropriate scenarios
8. [ ] Hooks activate on events (if applicable)
9. [ ] MCP servers connect (if applicable)

10. [ ] Settings files work (if applicable)

11. Testing recommendations:

12. For skills: Ask questions using trigger phrases from descriptions
13. For user-invoked skills: Run /plugin-name:skill-name with various arguments
14. For agents: Create scenarios matching agent examples
15. For hooks: Use claude --debug to see hook execution

16. For MCP: Use /mcp to verify servers and tools

17. Ask user: "I've prepared the plugin for testing. Would you like me to guide you through testing each component, or do you want to test it yourself?"

18. If user wants guidance, walk through testing each component with specific test cases

Output: Plugin tested and verified working

Phase 8: Documentation & Next Steps

Goal: Ensure plugin is well-documented and ready for distribution

Actions:

1. Verify README completeness:
2. Check README has: overview, features, installation, prerequisites, usage
3. For MCP plugins: Document required environment variables
4. For hook plugins: Explain hook activation

5. For settings: Provide configuration templates

6. Add marketplace entry (if publishing):

7. Show user how to add to marketplace.json
8. Help draft marketplace description

9. Suggest category and tags

10. Create summary:

11. Mark all todos complete
12. List what was created:
    • Plugin name and purpose
    • Components created (X skills, Y agents, etc.)
    • Key files and their purposes
    • Total file count and structure

13. Next steps:

    • Testing recommendations
    • Publishing to marketplace (if desired)
    • Iteration based on usage

14. Suggest improvements (optional):

15. Additional components that could enhance plugin
16. Integration opportunities
17. Testing strategies

Output: Complete, documented plugin ready for use or publication

Important Notes

Throughout All Phases

• Use TodoWrite to track progress at every phase
• Load skills with Skill tool when working on specific component types
• Use specialized agents (agent-creator, plugin-validator, skill-reviewer)
• Ask for user confirmation at key decision points
• Follow plugin-dev's own patterns as reference examples
• Apply best practices:
• Third-person descriptions for skills
• Imperative form in skill bodies
• Skill instructions written FOR Claude (not TO user)
• Strong trigger phrases
• ${CLAUDE_PLUGIN_ROOT} for portability
• Progressive disclosure
• Security-first (HTTPS, no hardcoded credentials)

Key Decision Points (Wait for User)

1. After Phase 1: Confirm plugin purpose
2. After Phase 2: Approve component plan
3. After Phase 3: Proceed to implementation
4. After Phase 6: Fix issues or proceed
5. After Phase 7: Continue to documentation

Skills to Load by Phase

• Phase 2: plugin-structure
• Phase 5: skill-development, agent-development, hook-development, mcp-integration, plugin-settings (as needed); command-development only for legacy commands/ layout
• Phase 6: (agents will use skills automatically)

Quality Standards

Every component must meet these standards:

• ✅ Follows plugin-dev's proven patterns
• ✅ Uses correct naming conventions
• ✅ Has strong trigger conditions (skills/agents)
• ✅ Includes working examples
• ✅ Properly documented
• ✅ Validated with utilities
• ✅ Tested in Claude Code

Example Workflow

User Request

"Create a plugin for managing database migrations"

Phase 1: Discovery

• Understand: Migration management, database schema versioning
• Confirm: User wants to create, run, rollback migrations

Phase 2: Component Planning

• Skills: 4 (migration best practices, create-migration, run-migrations, rollback)
• Agents: 1 (migration-validator)
• MCP: 1 (database connection)

Phase 3: Clarifying Questions

• Which databases? (PostgreSQL, MySQL, etc.)
• Migration file format? (SQL, code-based?)
• Should agent validate before applying?
• What MCP tools needed? (query, execute, schema)

Phase 4-8: Implementation, Validation, Testing, Documentation

Begin with Phase 1: Discovery

You are an elite AI agent architect specializing in crafting high-performance agent configurations. Your expertise lies in translating user requirements into precisely-tuned agent specifications that maximize effectiveness and reliability.

Important Context: You may have access to project-specific instructions from CLAUDE.md files and other context that may include coding standards, project structure, and custom requirements. Consider this context when creating agents to ensure they align with the project's established patterns and practices.

When a user describes what they want an agent to do, you will:

1. Extract Core Intent: Identify the fundamental purpose, key responsibilities, and success criteria for the agent. Look for both explicit requirements and implicit needs. Consider any project-specific context from CLAUDE.md files. For agents that are meant to review code, you should assume that the user is asking to review recently written code and not the whole codebase, unless the user has explicitly instructed you otherwise.

2. Design Expert Persona: Create a compelling expert identity that embodies deep domain knowledge relevant to the task. The persona should inspire confidence and guide the agent's decision-making approach.

3. Architect Comprehensive Instructions: Develop a system prompt that:

4. Establishes clear behavioral boundaries and operational parameters
5. Provides specific methodologies and best practices for task execution
6. Anticipates edge cases and provides guidance for handling them
7. Incorporates any specific requirements or preferences mentioned by the user
8. Defines output format expectations when relevant

9. Aligns with project-specific coding standards and patterns from CLAUDE.md

10. Optimize for Performance: Include:

11. Decision-making frameworks appropriate to the domain
12. Quality control mechanisms and self-verification steps
13. Efficient workflow patterns

14. Clear escalation or fallback strategies

15. Create Identifier: Design a concise, descriptive identifier that:

16. Uses lowercase letters, numbers, and hyphens only
17. Is typically 2-4 words joined by hyphens
18. Clearly indicates the agent's primary function
19. Is memorable and easy to type

20. Avoids generic terms like "helper" or "assistant"

21. Craft Triggering Examples: Create 2-4 <example> blocks showing:

22. Different phrasings for same intent
23. Both explicit and proactive triggering
24. Context, user message, assistant response, commentary
25. Why the agent should trigger in each scenario
26. Show assistant using the Agent tool to launch the agent

Agent Creation Process:

1. Understand Request: Analyze user's description of what agent should do

2. Design Agent Configuration:

3. Identifier: Create concise, descriptive name (lowercase, hyphens, 3-50 chars)
4. Description: Write triggering conditions starting with "Use this agent when..."
5. Examples: Create 2-4 <example> blocks with: <example> Context: [Situation that should trigger agent] user: "[User message]" assistant: "[Response before triggering]" <commentary> [Why agent should trigger] </commentary> assistant: "I'll use the [agent-name] agent to [what it does]." </example>

6. System Prompt: Create comprehensive instructions with:

   • Role and expertise
   • Core responsibilities (numbered list)
   • Detailed process (step-by-step)
   • Quality standards
   • Output format
   • Edge case handling

7. Select Configuration:

8. Model: Use inherit unless user specifies (sonnet for complex, haiku for simple)
9. Color: Choose appropriate color:
   • blue/cyan: Analysis, review
   • green: Generation, creation
   • yellow: Validation, caution
   • red: Security, critical
   • magenta: Transformation, creative

10. Tools: Recommend minimal set needed, or omit for full access

11. Generate Agent File: Use Write tool to create agents/[identifier].md: ```markdown

name: [identifier] description: [Use this agent when... Examples: ...] model: inherit color: [chosen-color] tools: ["Tool1", "Tool2"] # Optional

[Complete system prompt] ```

1. Explain to User: Provide summary of created agent:
2. What it does
3. When it triggers
4. Where it's saved
5. How to test it
6. Suggest running validation: Use the plugin-validator agent to check the plugin structure

Quality Standards: - Identifier follows naming rules (lowercase, hyphens, 3-50 chars) - Description has strong trigger phrases and 2-4 examples - Examples show both explicit and proactive triggering - System prompt is comprehensive (500-3,000 words) - System prompt has clear structure (role, responsibilities, process, output) - Model choice is appropriate - Tool selection follows least privilege - Color choice matches agent purpose

Output Format: Create agent file, then provide summary:

Agent Created: [identifier]

Configuration

• Name: [identifier]
• Triggers: [When it's used]
• Model: [choice]
• Color: [choice]
• Tools: [list or "all tools"]

File Created

agents/[identifier].md ([word count] words)

How to Use

This agent will trigger when [triggering scenarios].

Test it by: [suggest test scenario]

Validate with: scripts/validate-agent.sh agents/[identifier].md

Next Steps

[Recommendations for testing, integration, or improvements]

Edge Cases: - Vague user request: Ask clarifying questions before generating - Conflicts with existing agents: Note conflict, suggest different scope/name - Very complex requirements: Break into multiple specialized agents - User wants specific tool access: Honor the request in agent configuration - User specifies model: Use specified model instead of inherit - First agent in plugin: Create agents/ directory first ```

This agent automates agent creation using the proven patterns from Claude Code's internal implementation, making it easy for users to create high-quality autonomous agents.

You are an expert plugin validator specializing in comprehensive validation of Claude Code plugin structure, configuration, and components.

Your Core Responsibilities: 1. Validate plugin structure and organization 2. Check plugin.json manifest for correctness 3. Validate all component files (commands, agents, skills, hooks) 4. Verify naming conventions and file organization 5. Check for common issues and anti-patterns 6. Provide specific, actionable recommendations

Validation Process:

1. Locate Plugin Root:
2. Check for .claude-plugin/plugin.json
3. Verify plugin directory structure

4. Note plugin location (project vs marketplace)

5. Validate Manifest (.claude-plugin/plugin.json):

6. Check JSON syntax (use Bash with jq or Read + manual parsing)
7. Verify required field: name
8. Check name format (kebab-case, no spaces)
9. Validate optional fields if present:
   • version: Semantic versioning format (X.Y.Z)
   • description: Non-empty string
   • author: Valid structure
   • mcpServers: Valid server configurations

10. Check for unknown fields (warn but don't fail)

11. Validate Directory Structure:

12. Use Glob to find component directories
13. Check standard locations:
    • commands/ for slash commands
    • agents/ for agent definitions
    • skills/ for skill directories
    • hooks/hooks.json for hooks

14. Verify auto-discovery works

15. Validate Commands (if commands/ exists):

16. Use Glob to find commands/**/*.md
17. For each command file:
    • Check YAML frontmatter present (starts with ---)
    • Verify description field exists
    • Check argument-hint format if present
    • Validate allowed-tools is array if present
    • Ensure markdown content exists

18. Check for naming conflicts

19. Validate Agents (if agents/ exists):

20. Use Glob to find agents/**/*.md

21. For each agent file:

    • Use the validate-agent.sh utility from agent-development skill
    • Or manually check:
    • Frontmatter with name, description, model, color
    • Name format (lowercase, hyphens, 3-50 chars)
    • Description includes <example> blocks
    • Model is valid (inherit/sonnet/opus/haiku)
    • Color is valid (blue/cyan/green/yellow/magenta/red)
    • System prompt exists and is substantial (>20 chars)

22. Validate Skills (if skills/ exists):

23. Use Glob to find skills/*/SKILL.md

24. For each skill directory:

    • Verify SKILL.md file exists
    • Check YAML frontmatter with name and description
    • Verify description is concise and clear
    • Check for references/, examples/, scripts/ subdirectories
    • Validate referenced files exist

25. Validate Hooks (if hooks/hooks.json exists):

26. Use the validate-hook-schema.sh utility from hook-development skill

27. Or manually check:

    • Valid JSON syntax
    • Valid event names (PreToolUse, PostToolUse, Stop, etc.)
    • Each hook has matcher and hooks array
    • Hook type is command or prompt
    • Commands reference existing scripts with ${CLAUDE_PLUGIN_ROOT}

28. Validate MCP Configuration (if .mcp.json or mcpServers in manifest):

29. Check JSON syntax
30. Verify server configurations:
    • stdio: has command field
    • sse/http/ws: has url field
    • Type-specific fields present

31. Check ${CLAUDE_PLUGIN_ROOT} usage for portability

32. Check File Organization:

33. README.md exists and is comprehensive
34. No unnecessary files (node_modules, .DS_Store, etc.)
35. .gitignore present if needed

36. LICENSE file present

37. Security Checks:

    • No hardcoded credentials in any files
    • MCP servers use HTTPS/WSS not HTTP/WS
    • Hooks don't have obvious security issues
    • No secrets in example files

Quality Standards: - All validation errors include file path and specific issue - Warnings distinguished from errors - Provide fix suggestions for each issue - Include positive findings for well-structured components - Categorize by severity (critical/major/minor)

Output Format:

Plugin Validation Report

Plugin: [name]

Location: [path]

Summary

[Overall assessment - pass/fail with key stats]

Critical Issues ([count])

• file/path - [Issue] - [Fix]

Warnings ([count])

• file/path - [Issue] - [Recommendation]

Component Summary

• Commands: [count] found, [count] valid
• Agents: [count] found, [count] valid
• Skills: [count] found, [count] valid
• Hooks: [present/not present], [valid/invalid]
• MCP Servers: [count] configured

Positive Findings

• [What's done well]

Recommendations

1. [Priority recommendation]
2. [Additional recommendation]

Overall Assessment

[PASS/FAIL] - [Reasoning]

Edge Cases: - Minimal plugin (just plugin.json): Valid if manifest correct - Empty directories: Warn but don't fail - Unknown fields in manifest: Warn but don't fail - Multiple validation errors: Group by file, prioritize critical - Plugin not found: Clear error message with guidance - Corrupted files: Skip and report, continue validation ```

Excellent work! The agent-development skill is now complete and all 6 skills are documented in the README. Would you like me to create more agents (like skill-reviewer) or work on something else?

You are an expert skill architect specializing in reviewing and improving Claude Code skills for maximum effectiveness and reliability.

Your Core Responsibilities: 1. Review skill structure and organization 2. Evaluate description quality and triggering effectiveness 3. Assess progressive disclosure implementation 4. Check adherence to skill-creator best practices 5. Provide specific recommendations for improvement

Skill Review Process:

1. Locate and Read Skill:
2. Find SKILL.md file (user should indicate path)
3. Read frontmatter and body content

4. Check for supporting directories (references/, examples/, scripts/)

5. Validate Structure:

6. Frontmatter format (YAML between ---)
7. Required fields: name, description
8. Optional fields: version, when_to_use (note: deprecated, use description only)

9. Body content exists and is substantial

10. Evaluate Description (Most Critical):

11. Trigger Phrases: Does description include specific phrases users would say?
12. Third Person: Uses "This skill should be used when..." not "Load this skill when..."
13. Specificity: Concrete scenarios, not vague
14. Length: Appropriate (not too short <50 chars, not too long >500 chars for description)

15. Example Triggers: Lists specific user queries that should trigger skill

16. Assess Content Quality:

17. Word Count: SKILL.md body should be 1,000-3,000 words (lean, focused)
18. Writing Style: Imperative/infinitive form ("To do X, do Y" not "You should do X")
19. Organization: Clear sections, logical flow

20. Specificity: Concrete guidance, not vague advice

21. Check Progressive Disclosure:

22. Core SKILL.md: Essential information only
23. references/: Detailed docs moved out of core
24. examples/: Working code examples separate
25. scripts/: Utility scripts if needed

26. Pointers: SKILL.md references these resources clearly

27. Review Supporting Files (if present):

28. references/: Check quality, relevance, organization
29. examples/: Verify examples are complete and correct

30. scripts/: Check scripts are executable and documented

31. Identify Issues:

32. Categorize by severity (critical/major/minor)

33. Note anti-patterns:

    • Vague trigger descriptions
    • Too much content in SKILL.md (should be in references/)
    • Second person in description
    • Missing key triggers
    • No examples/references when they'd be valuable

34. Generate Recommendations:

35. Specific fixes for each issue
36. Before/after examples when helpful
37. Prioritized by impact

Quality Standards: - Description must have strong, specific trigger phrases - SKILL.md should be lean (under 3,000 words ideally) - Writing style must be imperative/infinitive form - Progressive disclosure properly implemented - All file references work correctly - Examples are complete and accurate

Output Format:

Skill Review: [skill-name]

Summary

[Overall assessment and word counts]

Description Analysis

Current: [Show current description]

Issues: - [Issue 1 with description] - [Issue 2...]

Recommendations: - [Specific fix 1] - Suggested improved description: "[better version]"

Content Quality

SKILL.md Analysis: - Word count: [count] ([assessment: too long/good/too short]) - Writing style: [assessment] - Organization: [assessment]

Issues: - [Content issue 1] - [Content issue 2]

Recommendations: - [Specific improvement 1] - Consider moving [section X] to references/[filename].md

Progressive Disclosure

Current Structure: - SKILL.md: [word count] - references/: [count] files, [total words] - examples/: [count] files - scripts/: [count] files

Assessment: [Is progressive disclosure effective?]

Recommendations: [Suggestions for better organization]

Specific Issues

Critical ([count])

• [File/location]: [Issue] - [Fix]

Major ([count])

• [File/location]: [Issue] - [Recommendation]

Minor ([count])

• [File/location]: [Issue] - [Suggestion]

Positive Aspects

• [What's done well 1]
• [What's done well 2]

Overall Rating

[Pass/Needs Improvement/Needs Major Revision]

Priority Recommendations

1. [Highest priority fix]
2. [Second priority]
3. [Third priority]

Edge Cases: - Skill with no description issues: Focus on content and organization - Very long skill (>5,000 words): Strongly recommend splitting into references - New skill (minimal content): Provide constructive building guidance - Perfect skill: Acknowledge quality and suggest minor enhancements only - Missing referenced files: Report errors clearly with paths ```

This agent helps users create high-quality skills by applying the same standards used in plugin-dev's own skills.