Documentation

Plugins extend AI agents with new capabilities. A plugin is a package that can contain skills, subagents, commands, and hooks - giving agents specialized knowledge, delegation capabilities, user-invocable actions, and lifecycle automation.

Standalone vs Plugins

There are two ways to add custom functionality:

Plugin Structure

my-plugin/
├── .claude-plugin/
│   └── plugin.json      # Required: Plugin manifest
├── commands/            # Slash commands as Markdown files
│   └── hello.md
├── agents/              # Custom agent definitions
│   └── code-reviewer.md
├── skills/              # Agent Skills with SKILL.md files
│   └── code-review/
│       └── SKILL.md
├── hooks/               # Event handlers
│   └── hooks.json
├── .mcp.json            # MCP server configurations
└── README.md            # Documentation

Plugin Manifest

Every plugin requires a .claude-plugin/plugin.json manifest:

{
  "name": "my-plugin",
  "description": "A helpful plugin for code workflows",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

Quick Start

Example: A Complete Plugin

Here's what a "GitHub Integration" plugin might include:

A plugin is a package that can contain one or more of the following components. When you publish to the marketplace, you're publishing a plugin.

A Skill is a markdown file that teaches the agent how to do something specific: reviewing PRs using your team's standards, generating commit messages in your preferred format, or querying your company's database schema. Skills are model-invoked - the agent decides which Skills to use based on your request.

How Skills Work

Where Skills Live

Skill Frontmatter Fields

Example Skill with Supporting Files

pdf-processing/
├── SKILL.md              # Overview and quick start
├── FORMS.md              # Form field mappings and filling instructions
├── REFERENCE.md          # API details for pypdf and pdfplumber
└── scripts/
    ├── fill_form.py      # Utility to populate form fields
    └── validate.py       # Checks PDFs for required fields

---
name: pdf-processing
description: Extract text, fill forms, merge PDFs. Use when working with PDF files.
allowed-tools: Read, Bash(python:*)
---

# PDF Processing

## Quick start

Extract text:
```python
import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

For form filling, see [FORMS.md](FORMS.md).
For detailed API reference, see [REFERENCE.md](REFERENCE.md).

Subagents are specialized AI assistants that handle specific types of tasks. Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions. When the agent encounters a task that matches a subagent's description, it delegates to that subagent.

Why Use Subagents?

Where Subagents Live

Subagent Frontmatter Fields

Example Subagent

---
name: code-reviewer
description: Reviews code for quality and best practices. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer. When invoked:

1. Analyze the code for quality, security, and best practices
2. Provide specific, actionable feedback
3. Highlight both issues and strengths
4. Suggest concrete improvements with code examples

Focus on:
- Code organization and readability
- Error handling and edge cases
- Security vulnerabilities
- Performance considerations

Commands are user-invocable actions triggered by typing /command-name. Unlike Skills (which the agent chooses automatically), Commands require explicit user invocation. They're ideal for common workflows users want quick access to.

Skills vs Commands

Where Commands Live

Command Arguments

Commands can accept user input through special placeholders:

Example Command

.claude/commands/deploy.md

---
name: deploy
description: Deploy the current branch to staging or production
allowed-tools: Bash, Read
---

# Deploy Command

Deploy the current branch to the "$ARGUMENTS" environment using our deployment pipeline.

## Steps

1. Run tests to ensure everything passes
2. Build the production bundle
3. Deploy to the specified environment

## Usage

- `/deploy staging` - Deploy to staging environment
- `/deploy production` - Deploy to production (requires approval)

Hooks are user-defined shell commands that execute at various points in the agent's lifecycle. They provide deterministic control over behavior, ensuring certain actions always happen rather than relying on the LLM to choose to run them.

Hook Events

Common Use Cases

Hook Configuration

Hooks are configured in ~/.claude/settings.json (user) or .claude/settings.json (project).

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"import json, sys; data=json.load(sys.stdin); path=data.get('tool_input',{}).get('file_path',''); sys.exit(2 if any(p in path for p in ['.env', 'package-lock.json', '.git/']) else 0)\""
          }
        ]
      }
    ]
  }
}

Matcher Patterns

Use matchers to run hooks only for specific tools:

• Bash - Match only Bash tool calls
• Edit|Write - Match Edit or Write tool calls
• * - Match all tools
• "" (empty) - Match all tools

Exit Codes

For PreToolUse hooks, exit codes control behavior:

• 0 - Allow the tool call to proceed
• 2 - Block the tool call and provide feedback to the agent
• Other non-zero - Hook error (tool call proceeds)

Choose the right extensibility mechanism for your use case: