Plugins and Hooks

Skills are single markdown files. Plugins are full packages — bundling skills, agents, hooks, and MCP servers into one installable unit. If skills are functions, plugins are libraries.

Hooks sit at the other end of the spectrum: low-level interception points that let you run code before or after Claude takes any action. Together, plugins and hooks give you complete control over what Claude can do and how it behaves.

What Are Plugins?

A plugin packages multiple Claude Code extensions into a single installable unit. Where a skill is a single SKILL.md file, a plugin can contain:

• Skills — reusable workflows and background knowledge
• Agents — subagent definitions for specialized tasks
• Hooks — lifecycle interceptors that run before/after Claude actions
• MCP servers — tool servers that give Claude new capabilities
• Default settings — preconfigured permissions and preferences

Plugins launched in public beta in October 2025 and reached stable status in early 2026. The ecosystem now includes over 400 plugins spanning development tools, testing frameworks, documentation generators, deployment pipelines, and productivity utilities.

Finding Plugins

Official and Community Sources

Evaluating a Plugin

Before installing a third-party plugin, check these signals:

• Maintenance status — When was the last commit? Are issues being triaged?
• Download count — Higher adoption usually means more eyes on the code and fewer bugs
• Reviews and ratings — Read the negative reviews first; they reveal real limitations
• Permissions requested — Does the plugin need Bash(*) (full shell access) or just Read, Grep? Prefer the narrowest scope
• Source code — Skim the hooks and skills. A plugin's plugin.json manifest tells you exactly what it installs

Plugin Categories

The ecosystem organizes around these common categories:

Installing Plugins

Basic Installation

Add the plugin name to enabledPlugins in your settings file. Plugins can be enabled at the project, user, or enterprise level.

1{
2  "enabledPlugins": [
3    "claude-plugin-terraform",
4    "claude-plugin-docker",
5    "@myorg/claude-plugin-internal"
6  ]
7}

Version Pinning

Pin plugin versions to avoid breaking changes:

1{
2  "enabledPlugins": [
3    "claude-plugin-terraform@2.1.0",
4    "claude-plugin-docker@^1.4.0",
5    "@myorg/claude-plugin-internal@latest"
6  ]
7}

• Exact (@2.1.0) — locks to a specific version
• Caret (@^1.4.0) — allows patch and minor updates within the major version
• Latest (@latest) — always uses the newest version (use with caution)

Custom Registries

For private or internal plugins, point to a custom npm registry:

1{
2  "pluginRegistries": [
3    "https://npm.internal.mycompany.com"
4  ],
5  "enabledPlugins": [
6    "@myorg/claude-plugin-internal"
7  ]
8}

Activating Changes

After editing your settings, reload plugins without restarting Claude Code:

/reload-plugins

Claude confirms which plugins were loaded, skipped, or failed.

Plugin Structure

Every plugin is a directory with a plugin.json manifest at the root. Here is the standard layout:

The plugin.json Manifest

The manifest declares the plugin's identity and components:

1{
2  "name": "my-plugin",
3  "description": "Linting, testing, and code review automation",
4  "version": "1.2.0",
5  "author": "Your Name",
6  "license": "MIT",
7  "components": {
8    "skills": ["skills/lint-check", "skills/test-runner"],
9    "agents": ["agents/code-reviewer.md"],
10    "hooks": {
11      "PreToolUse": [
12        {
13          "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-commit-check.sh",
14          "if": "Tool(Bash) && args.command matches 'git commit'"
15        }
16      ],
17      "PostToolUse": [
18        {
19          "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-edit-format.sh",
20          "if": "Tool(Edit)"
21        }
22      ]
23    },
24    "mcpServers": ".mcp.json"
25  }
26}

Key Manifest Fields

Path Variables

Two built-in variables resolve paths inside plugin code:

Use ${CLAUDE_PLUGIN_ROOT} in hook commands and skill paths so they work regardless of where the plugin is installed. Use ${CLAUDE_PLUGIN_DATA} for anything that should persist across version upgrades.

Plugin Default Settings

A plugin can ship a settings.json file that provides default permissions and preferences:

1{
2  "permissions": {
3    "allow": [
4      "Bash(npx eslint *)",
5      "Bash(npx prettier *)",
6      "Read",
7      "Grep"
8    ]
9  }
10}

Users can override these defaults in their own settings.

Hooks Deep Dive

Hooks are the lowest-level extension mechanism in Claude Code. They intercept specific points in Claude's lifecycle and run your code — a shell command or an HTTP request — before or after the action proceeds.

Unlike skills (which Claude reads and follows) and MCP servers (which expose tools), hooks run your code outside Claude's reasoning. The hook script receives structured JSON, does its work, and returns a JSON response telling Claude what to do.

Hook Types

Shell Command Hooks

The most common hook type. Claude runs your command, pipes JSON to stdin, and reads JSON from stdout.

Configure hooks in settings.json or in a plugin's plugin.json:

1{
2  "hooks": {
3    "PreToolUse": [
4      {
5        "command": "/path/to/my-hook.sh"
6      }
7    ]
8  }
9}

The hook script receives a JSON payload on stdin with context about the event. It must return a JSON response on stdout.

Input format (piped to stdin):

1{
2  "hook": "PreToolUse",
3  "tool": "Bash",
4  "args": {
5    "command": "git push --force origin main"
6  },
7  "session_id": "abc123",
8  "cwd": "/Users/you/project"
9}

Output format (printed to stdout):

{
  "action": "block",
  "message": "Force-pushing to main is not allowed. Use a feature branch."
}

The action field controls what happens next:

HTTP Hooks

Instead of running a local command, send a POST request to a URL endpoint. This is useful for cloud functions, logging services, or centralized team servers.

1{
2  "hooks": {
3    "Stop": [
4      {
5        "url": "https://hooks.myteam.com/claude-session-complete",
6        "headers": {
7          "Authorization": "Bearer ${HOOKS_API_KEY}"
8        }
9      }
10    ]
11  }
12}

The POST body is the same JSON payload a shell hook receives on stdin. The response body follows the same action format.

Conditional Hooks

Use the if field to restrict when a hook fires. The syntax mirrors Claude Code's permission rule format:

1{
2  "hooks": {
3    "PreToolUse": [
4      {
5        "command": "./hooks/block-force-push.sh",
6        "if": "Tool(Bash) && args.command matches 'git push.*--force'"
7      },
8      {
9        "command": "./hooks/lint-on-edit.sh",
10        "if": "Tool(Edit) && args.file_path matches '\\.(ts|tsx|js|jsx)$'"
11      }
12    ],
13    "PostToolUse": [
14      {
15        "command": "./hooks/format-python.sh",
16        "if": "Tool(Edit) && args.file_path matches '\\.py$'"
17      }
18    ]
19  }
20}

Without an if field, the hook fires on every occurrence of that event. The conditional syntax supports:

• Tool(ToolName) — match a specific tool
• args.field matches 'regex' — match against tool arguments
• && / || — combine conditions
• ! — negate a condition

Practical Hook Examples

Block Dangerous Git Commands

Prevent force-pushes and hard resets on protected branches:

1#!/bin/bash
2# hooks/block-dangerous-git.sh
3 
4# Read JSON from stdin
5INPUT=$(cat)
6 
7COMMAND=$(echo "$INPUT" | jq -r '.args.command // ""')
8 
9# Check for dangerous patterns
10if echo "$COMMAND" | grep -qE 'git (push.*--force|reset --hard|clean -fd)'; then
11  BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
12 
13  if [[ "$BRANCH" == "main" || "$BRANCH" == "master" ]]; then
14    echo '{"action": "block", "message": "Blocked: destructive git operation on protected branch '"$BRANCH"'. Switch to a feature branch first."}'
15    exit 0
16  fi
17fi
18 
19# Allow everything else
20echo '{"action": "proceed"}'

Settings configuration:

1{
2  "hooks": {
3    "PreToolUse": [
4      {
5        "command": "./.claude/hooks/block-dangerous-git.sh",
6        "if": "Tool(Bash) && args.command matches '^git '"
7      }
8    ]
9  }
10}

Auto-Format Code After Edits

Run Prettier on any TypeScript or JavaScript file Claude edits:

1#!/bin/bash
2# hooks/auto-format.sh
3 
4INPUT=$(cat)
5 
6FILE_PATH=$(echo "$INPUT" | jq -r '.args.file_path // ""')
7 
8if [[ -n "$FILE_PATH" && -f "$FILE_PATH" ]]; then
9  npx prettier --write "$FILE_PATH" 2>/dev/null
10fi
11 
12echo '{"action": "proceed"}'

1{
2  "hooks": {
3    "PostToolUse": [
4      {
5        "command": "./.claude/hooks/auto-format.sh",
6        "if": "Tool(Edit) && args.file_path matches '\\.(ts|tsx|js|jsx|css)$'"
7      }
8    ]
9  }
10}

Notify Slack When a Session Completes

Send a summary to a Slack channel when Claude finishes working:

1#!/bin/bash
2# hooks/notify-slack.sh
3 
4INPUT=$(cat)
5 
6SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"')
7CWD=$(echo "$INPUT" | jq -r '.cwd // "unknown"')
8PROJECT=$(basename "$CWD")
9 
10curl -s -X POST "$SLACK_WEBHOOK_URL" \
11  -H "Content-Type: application/json" \
12  -d "{
13    \"text\": \"Claude Code session complete in *${PROJECT}* (session: ${SESSION_ID})\"
14  }" > /dev/null 2>&1
15 
16echo '{"action": "proceed"}'

1{
2  "hooks": {
3    "Stop": [
4      {
5        "command": "./.claude/hooks/notify-slack.sh"
6      }
7    ]
8  }
9}

Inject Context on Session Start

Automatically load project-specific context when a session begins:

1#!/bin/bash
2# hooks/load-context.sh
3 
4INPUT=$(cat)
5CWD=$(echo "$INPUT" | jq -r '.cwd // "."')
6 
7CONTEXT=""
8 
9# Add recent git activity
10if [ -d "$CWD/.git" ]; then
11  RECENT=$(cd "$CWD" && git log --oneline -5 2>/dev/null)
12  CONTEXT="Recent commits:\n$RECENT\n\n"
13fi
14 
15# Add open issues count
16if command -v gh &> /dev/null; then
17  ISSUES=$(cd "$CWD" && gh issue list --limit 5 --json title,number 2>/dev/null)
18  if [ -n "$ISSUES" ]; then
19    CONTEXT="${CONTEXT}Open issues:\n$ISSUES"
20  fi
21fi
22 
23if [ -n "$CONTEXT" ]; then
24  echo "{\"action\": \"inject\", \"message\": \"$CONTEXT\"}"
25else
26  echo '{"action": "proceed"}'
27fi

Creating a Simple Plugin

Walk through building a plugin from scratch that validates commit messages and enforces conventional commit format.

Popular Plugins to Try

These well-established plugins cover common workflows. Install any of them by adding the name to enabledPlugins in your settings:

Install example:

1{
2  "enabledPlugins": [
3    "claude-plugin-git-guardian",
4    "claude-plugin-test-runner@^2.0.0"
5  ]
6}

Hooks vs. Skills vs. MCP Servers

These three extension mechanisms serve different purposes. Choosing the right one matters:

Use a skill when you want Claude to understand and follow a process. Skills guide behavior through instructions.

Use a hook when you need deterministic enforcement — blocking bad commands, running formatters, sending notifications. Hooks don't rely on Claude choosing to follow advice; they run unconditionally.

Use an MCP server when Claude needs to interact with an external system — query a database, call an API, search the web. MCP servers give Claude new tools.

A well-designed plugin often combines all three: a skill teaches Claude how to work with a framework, hooks enforce safety constraints, and an MCP server connects to the framework's CLI or API.

Troubleshooting

Plugin Not Loading

1. Verify the plugin name in enabledPlugins matches the name field in plugin.json
2. Run /reload-plugins and check the output for errors
3. Ensure plugin.json is valid JSON (use jq . plugin.json to check)
4. For local plugins, confirm the path is correct and accessible

Hook Not Firing

1. Check that the if condition matches the actual tool and arguments. Test with a simple hook that always logs to a file first
2. Verify the hook script is executable (chmod +x)
3. Make sure the script outputs valid JSON to stdout. Any non-JSON output (warnings, debug prints to stdout) breaks parsing
4. Test the script manually: echo '{"hook":"PreToolUse","tool":"Bash","args":{"command":"git commit"}}' | ./hooks/my-hook.sh

Hook Blocks Everything

If a hook returns invalid JSON or exits with a non-zero code, Claude may treat the action as blocked. Add error handling to your scripts:

1#!/bin/bash
2INPUT=$(cat)
3 
4# Wrap logic in a function for clean error handling
5run_hook() {
6  # ... your logic here ...
7  echo '{"action": "proceed"}'
8}
9 
10# Default to proceed if anything fails
11run_hook || echo '{"action": "proceed"}'

Skills From Plugin Not Appearing

Plugin skills use namespaced names: plugin-name:skill-name. Try invoking with the full name:

/my-commit-plugin:commit-helper

Next Steps

1. Start with hooks — add a single PreToolUse hook to enforce a team convention
2. Browse the official directory — find a plugin that matches a workflow you do manually
3. Bundle your skills into a plugin — if you have multiple related skills, packaging them makes sharing easier

Related Topics:

• Claude Code Skills — The foundation plugins build on
• Essential MCP Servers — Extend Claude with external tool servers
• Building Agents — Create specialized agent definitions to include in plugins
• Best Practices — Workflows that pair well with plugins and hooks