Anthropic · Claude Code · Extension architecture

Teach Claude Code new superpowers.

A plugin is a self-contained, installable bundle of capabilities (skills, agents, hooks, MCP servers and more) that Claude can load, understand, and act on. This is the field guide, drawn out in full.

claude code

$ /plugin install @official/code-review
✓ manifest registered · skills mounted · hooks armed
Claude can now review PRs, audit diffs & enforce standards.

10 chapters 9 building blocks 1 mental model

start reading

What is a Claude Code plugin?

A reusable “capability bundle” Claude can load, understand, and invoke on your behalf. It’s a lot more than a prompt wrapper.

animated · one plugin, many capabilities

Claude
Code

skills agents hooks mcp lsp monitors

Install a plugin and Claude Code lights up with new powers. Each pulsing node is a component the plugin can carry. One bundle, six kinds of capability.

the platform Claude Code

is the operating system

the extensions Plugins

are the applications

They extend what Claude can perceive, decide, and act on, so you don’t have to re-explain your context every session.

A single plugin can compose any of these:

Skills

Reusable instruction sets Claude invokes automatically or on demand.

Agents

Custom sub-agents with their own system prompts and tool access.

Hooks

Event-driven shell scripts that fire on lifecycle events.

MCP servers

External tool integrations via the Model Context Protocol.

LSP servers

Real-time code intelligence for specific languages.

Background monitors

Persistent watchers that stream context to Claude as events arrive.

Plugin vs. standalone config

Standalone.claude/

Skill syntax /hello
Fast to set up
Personal workflows, single project, quick experiments

Plugin.claude-plugin/plugin.json

Skill syntax /my-plugin:hello
Built for scale
Team sharing, multi-project reuse, versioned distribution, marketplace

The building blocks

Every plugin is just a directory. Its power comes from what you put inside it: nine components, each with a home.

animated · nine parts, one directory

plugin.json skills agents hooks .mcp .lsp monitors settings bin

A power-on sweep shows each block taking its place at the plugin root. Only plugin.json lives under .claude-plugin/.

2.1

The manifest

.claude-plugin/plugin.json

The single required file. It declares your plugin’s identity: name (your skill namespace prefix), version, and description.

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Automates code review"
}

2.2

Skills

skills/<name>/SKILL.md

The lightest-weight primitive: a markdown file with YAML frontmatter giving Claude a reusable instruction set. The description tells Claude when to invoke it.

2.3

Agents

agents/<name>.md

Specialized Claude instances with their own system prompt and restricted tools. For security, hooks, mcpServers and permissionMode are deliberately unsupported inside agents.

2.4

Hooks

hooks/hooks.json

They react to lifecycle events by running shell commands automatically. This is the backbone for enforcing policy and running checks.

2.5

MCP servers

.mcp.json

Tools backed by external APIs or local processes. Bundle them so users get the integration automatically on install.

2.6

LSP servers

.lsp.json

Real-time code intelligence for specific languages: completions, diagnostics, and go-to-definition.

2.7

Monitors

monitors/monitors.json

Persistent background processes that stream context to Claude as events arrive. Started automatically when the plugin is active.

2.8

Default settings

settings.json

Ship default Claude Code settings. The supported keys are agent and subagentStatusLine, which let you activate a named agent as the main thread.

2.9

Executables

bin/

Added to the Bash tool’s PATH while the plugin is active, so Claude gets your CLI utilities without anyone touching their PATH.

my-plugin/

.claude-plugin/
  plugin.json          ← manifest (only file here)
skills/
  code-review/
    SKILL.md
    reference.md
agents/security-reviewer.md
hooks/hooks.json
.mcp.json                  ← MCP server configs
.lsp.json                  ← LSP server configs
monitors/monitors.json
bin/                        ← executables added to PATH
settings.json
README.md

How plugins work, end to end

From a marketplace install to a hot reload. Understanding the lifecycle helps you build plugins that behave predictably.

animated · activation at load

manifest skills agents hooks mcp lsp monitors

A scanning loader registers each subsystem in order, and all of it happens before Claude’s first response.

Loading and activation, all before Claude’s first response

1
The manifest is read; the plugin’s identity is registered.
2
Skills are discovered and added to Claude’s command list.
3
Agents are loaded into the agent registry.
4
Hooks are registered for lifecycle events.
5
MCP servers start as child processes.
6
LSP servers are initialized.
7
Monitors begin streaming.

Skill invocation: two paths

explicit

You type the command

/plugin-name:skill-name [args]

Direct, deterministic. You decide.

automatic

Claude reads the description

Claude decides based on the task at hand, which is why a precise, trigger-aware description is the most important part of any skill.

weak “Code review helper”

strong “Reviews diffs for security & style. Use before merging any branch.”

The hook execution flow

User request

Claude picks a tool

PreToolUse hooks fire

Tool executes

PostToolUse hooks fire

Claude continues

Hooks receive JSON on stdin and can:

exit 0 allow the action
exit ≠ 0 block it (Claude sees stderr)
return JSON add context to Claude’s next decision

Namespacing

Every plugin skill is prefixed /plugin-name:skill-name, preventing conflicts. The prefix comes from name in the manifest.

Hot reloading

Run /reload-plugins to pick up changes without restarting. It reloads skills, agents, hooks, MCP, and LSP, and monitors restart on their own.

What to consider before building

Answer these before writing a single line. They determine whether you’re building the right thing.

animated · the first fork in the road

new capability

share it?

standalone.claude/

plugin.claude-plugin/

Will more than one person use it across projects? Yes → build a plugin. No → start standalone and convert later.

Plugin, or standalone config?

Start standalone. Convert to a plugin when sharing becomes necessary.

Multiple people will use this
Works across several projects
Needs versioning & controlled rollout
Has external dependencies (MCP, LSP)
Just for you, one project, a quick test

4.2

Core capability

Finish this sentence: “With this plugin, Claude can now ____.” Be specific. “Developer productivity” is too broad to be useful.

4.3

Scope & boundaries

Which tools? What should it explicitly not do? Persistent state? Network access? Scope creep breaks trust.

4.4

Dependency inventory

External binaries, API keys, network domains, other plugins. Write them all down, and fail gracefully when one is missing.

4.5

Namespace conflicts

Pick a unique, organization-scoped name. Prefer acme-code-review over code-review.

4.6

Version strategy

Explicit version = stable, disciplined updates. No version = every commit ships. Pick explicit for anything beyond yourself.

4.7

Distribution channel

Local dir · private git marketplace · community submission · enterprise marketplace behind your auth.

Why build a plugin?

Seven reasons a plugin beats re-explaining yourself every session.

animated · one update, everyone gets it

pluginv1.1

Bump the plugin once and the change ripples out to every engineer’s Claude Code. Standards and tooling, propagated org-wide.

Encode institutional knowledge

“The way we do things” becomes permanently available and automatically applied, instead of sitting in a wiki Claude can’t read.

Enforce standards consistently

A PostToolUse hook running your linter means style-violating code never gets committed. No human review step for mechanical checks.

Compress repetitive context

The background you retype every session (architecture, file layout, conventions) belongs in a skill that sets Claude up at the start.

Create specialized personas

A security reviewer that only thinks vulnerabilities; a doc writer that only writes docs. Specialization produces better outputs.

Integrate your toolchain

MCP turns Claude Code into a hub that talks to your issue tracker, CI, and observability, so there’s no copy-paste from Datadog.

Scale across your org

One install gives every engineer the same baseline. One update propagates everywhere.

Monetization & community

Solve a general problem elegantly and there’s a real user base waiting on the community marketplace.

How Claude Code interacts with plugins

Claude Code is an orchestrator. Plugins extend what it knows and what it can do.

animated · the orchestrator routes work

Every request flows through the main thread, which fans out to skills, MCP tools, agents, and hooks, then pulls the results back together.

main thread Claude
orchestrator

Skills

reads descriptions → decides which to invoke

MCP tools

sees available tools → decides which to call

Agents

spawns sub-agents → delegates focused subtasks

Hooks

intercept tool calls → shell scripts run

Context injection

When a skill is invoked, its SKILL.md drops into Claude’s working context at exactly the right moment. Put the critical info near the top, and load the detail only when it’s needed.

Tool routing

MCP tools appear right alongside Read, Write, and Bash. Claude routes by description, so your tool descriptions matter just as much as your skill descriptions.

Agent delegation

The orchestrator delegates to an agent that runs with its own prompt and restricted tools, then returns findings to be synthesized.

Monitor feed

Monitors pipe stdout to Claude as notifications, giving it a quiet awareness of test failures, error logs, and status changes without being asked.

Security design

This is the section that separates thoughtful authors from the ones who create real risk. Plugins are powerful, and that power needs constraints.

animated · validate, then allow

hook stdin

validate
& allowlist

tool runs

Treat every hook input as untrusted. Well-formed calls pass the gate, and the malicious payload is stopped at the boundary. Use least privilege, and allowlist everything else.

The trust pyramid problem

Installing a plugin means implicitly trusting every component inside it. Trust is transitive and often opaque.

monitors · bin MCP servers hooks skills · agents a single malicious component can exfiltrate keys or run arbitrary code

Real CVEs have exploited this

CVE-2025-59536

Remote code execution via malicious hooks planted in a repository’s settings file.

CVE-2026-21852

API-key exfiltration by overriding environment variables through a rogue MCP server.

Least privilege, component by component

Skills

Request only the tools you actually need. Reading logs? tools: Read, Glob, and nothing more.

Agents

Give every agent an explicit tool list. A doc writer needs Read, Write, Glob, not Bash.

Hooks most dangerous

Always quote variables "$FILE". Validate & sanitize input. Never pipe user content to sh. Allowlist, don’t blocklist.

MCP servers

Each is a trust boundary. Ship only audited servers. Reference secrets via env. Scope tokens minimally; prefer read-only.

hook input validation
# Extract and validate; treat stdin as untrusted
FILE_PATH=$(echo "$STDIN" | jq -r '.tool_input.file_path // empty')
if [ -z "$FILE_PATH" ]; then exit 0; fi
# Ensure no path traversal
case "$FILE_PATH" in *../*) exit 1 ;; esac

Security checklist before publishing

No hardcoded secrets anywhere
All hook shell commands use quoted variables
MCP servers pin dependency versions
Agent definitions have explicit tool restrictions
claude plugin validate passes with no warnings
README documents all required environment variables
Tested in a sandboxed container or VM
No unnecessary network access
Least privilege applied to every component

Designing for repetitive workflows

This is where plugins pay off the most, turning high-friction, multi-step work into a single command.

animated · ~20 minutes collapses to ~2

manual · 8 steps · ~20 min / PR

plugin · one command · ~2 min

The manual workflow crawls through eight steps while the plugin finishes in a single pass. Same outcome, a tenth of the time.

without a plugin~20 min / PR

Open PR, copy diff into chat
Type “review for security”
Receive findings
Manually create GitHub comments
Update the Jira ticket
Run the linter by hand
Fix issues · repeat every PR

with a plugin~2 min · zero copy-paste

/pr-tools:full-review PR-456

fetches the diff via GitHub MCP
security-reviewer agent analyzes it
PostToolUse hook runs the linter
GitHub MCP posts review comments
Jira MCP updates ticket status

The four automation patterns for skills

Context loader

Sets Claude up with everything it needs at the start. No action, just context.

Workflow executor

Runs a multi-step process in order (fetch, analyze, act, report) and stops the moment a step fails.

State-aware operator

Checks external state through MCP tools and acts conditionally: classify a ticket, then branch.

Feedback loop

A skill paired with hooks for continuous improvement: write the test, run it, implement, verify, refactor.

Hooks are the workflow glue

The key insight: hooks return their stdout to Claude. A TypeScript error in the hook output gets read by Claude, which then fixes it, all without anyone stepping in. Design hooks to auto-correct, auto-verify, auto-document, and auto-notify.

Architecture best practices

Lessons from building production-grade plugins. Treat plugin development like production code.

animated · idempotent feedback loop

write test run implement refactor

safe to
run twice

Skills and hooks should loop cleanly: observable, fail-loud, and idempotent, so running the same step twice does nothing bad.

9.1

Design for observability

Write audit logs from hooks. Add a :status skill reporting MCP health and recent hook activity.

9.2

Fail gracefully & loudly

Missing dependency? Surface it on stderr with a fix, don’t silently degrade. Give skills explicit fallbacks.

9.3

Progressive disclosure

Core instructions in SKILL.md (100 to 200 lines), with the deep detail in a reference.md loaded on demand.

9.4

Idempotency

Safe to run twice. Ask: “What happens if this runs twice on the same input?” The answer: nothing bad.

9.5

One plugin, one domain

Resist the Swiss-army knife. Three focused plugins beat one that does everything.

9.6

Namespace everything

Plugin → skills → MCP servers → agents all share a coherent namespace.

9.7

Version & changelog discipline

Bump version, write a changelog entry, document migrations for breaking changes.

9.8

Test matrix

Clean install, upgrade, missing deps, co-installed plugins, concurrent invocations, local override.

9.9

Document the why

The problem solved, what changes in Claude’s behavior, required setup, known limitations.

9.10

Treat it like production

Git from day one, tested hook scripts, CI validation, tagged releases, security review before publish.

Going beyond

What the internet doesn’t tell you: the things you actually need to build plugins that work at scale.

animated · the description is the router

“review this PR
for security”

format-docs security-review run-tests

Claude scans every skill’s description and routes the task to the one that fits. That’s why the description is your most important code.

10.1 · the big one

The description is your most important code

Claude’s decision to use a skill rests entirely on its description. Test it: describe a scenario without naming the skill, and see if Claude reaches for it. If it doesn’t, rewrite the description. Add negative constraints too, because saying what the skill is not for keeps Claude from over-applying it.

10.3

The hook → Claude feedback loop

Underused. Hooks that return rich, structured context (JSON lint results) tell Claude exactly what to fix and where.

10.4

MCP descriptions = routing table

Every tool description is Claude’s decision criterion for calling it. Write them with skill-level care.

10.5

Agents vs. skills

Skill: linear, fast, no tool isolation. Agent: strict isolation, a distinct persona, and deep focus, at the cost of some spawn overhead.

10.6

Monitors = background intelligence

Any line of stdout can be a monitor: git commits, API polling, fswatch, slow-query logs. Sessions start to feel proactive.

10.7

settings.json agent activation

The most underused feature: a default agent gives Claude Code organizational identity for the session.

10.8

Private team marketplace

A marketplace.json in a private git repo: centralized, version-pinned, audited plugins with a review gate.

10.10

A plugin that teaches itself

A skill that reads its own files, checks them against the codebase, and proposes updates. A knowledge base that stays alive.

＋

Quick reference

The cheat sheet: locations, events, and commands.

File locations

.claude-plugin/plugin.json: Manifest
skills/<name>/SKILL.md: Skill definition
agents/<name>.md: Agent definition
hooks/hooks.json: Hook handlers
.mcp.json: MCP server configs
.lsp.json: LSP server configs
monitors/monitors.json: Background monitors
settings.json: Default settings
bin/: Executables → PATH

Hook events

PreToolUse: Before any tool executes
PostToolUse: After any tool executes
ConfigChange: Config is mutated
SessionStart: Session begins
SessionEnd: Session ends

Development commands

# scaffold
claude plugin init my-plugin
# load locally
claude --plugin-dir ./my-plugin
# load from URL
claude --plugin-url …/my-plugin.zip
# validate before publish
claude plugin validate
# reload during dev
/reload-plugins