Fundamentals
Plugins are shareable packages that bundle skills, subagents, hooks, MCP servers, LSP servers, output styles, themes, monitors, and more into single installable units.
Before plugins, setting up Claude Code with custom commands, agents, and integrations meant scattered configuration files across different projects. When teammates asked "How do I set up the same thing?", reproducing your setup was tedious and error-prone.
Plugins solve this
Bundle all your customizations into shareable packages that install with a single command. Share with your team or use across your own projects. Learn more in the official plugin guide.
Claude Code has several extension points that often get confused. Here's how they relate:
CLAUDE.md / AGENTS.md
Durable project and team policy. Loaded as context so Claude always knows your rules and conventions.
SKILL.md
Task-specific runbooks. Claude sees descriptions to know what's available, but the full content loads only when needed.
Hooks
Event-driven enforcement and automation. Run on matching lifecycle events without Claude deciding whether to use them.
Plugins
Packaging and distribution. A plugin bundles skills, agents, hooks, MCP/LSP servers, and more into a single installable unit.
MCP / LSP / Monitors
Live external capabilities and background signals. Expose tools, code intelligence, and streaming notifications to Claude.
A common source of confusion is when each piece actually loads into Claude's context.
| What | Loaded When |
|---|---|
| CLAUDE.md (project root) | At session start. Subdirectory CLAUDE.md files load on demand when Claude works in those directories. |
| AGENTS.md | Not read directly by Claude Code. Import via @AGENTS.md in your CLAUDE.md, or symlink CLAUDE.md to AGENTS.md. |
| Skill descriptions | Loaded into context so Claude knows what's available. Exception: disable-model-invocation: true skills are user-invocable only and their description is not in context until invoked. |
| Skill body (SKILL.md) | On invocation -- when Claude decides it's relevant, or when you type /name. |
| Commands (flat .md) | Same as skills -- commands and skills share the same mechanism. commands/*.md is the flat-file form; skills/<name>/SKILL.md is the richer folder form. |
| Hooks | On matching lifecycle events (deterministic for configured events). Async hooks cannot block or control Claude's behavior. |
| MCP / LSP Servers | Available when configured and enabled for the session. They expose tools and code intelligence capabilities, not prompt text. |
| Monitors | Run for the session lifetime, streaming stdout to Claude as notifications. Interactive CLI sessions only. (Experimental) |
| Output Styles / Themes | On selection through Claude Code's style and theme controls. Output styles modify the system prompt; themes change terminal appearance. (Themes: experimental) |
Plugin-root CLAUDE.md
A CLAUDE.md inside a plugin root is not loaded as project context. Plugins contribute context through skills, agents, hooks, and other components -- not through their own CLAUDE.md file.
Plugins can include any combination of these component types. Each type has different invocation semantics.
Skills are directories (skills/<name>/SKILL.md) that can include supporting files and scripts. Claude sees the skill description so it knows what's available, but the full content loads only when invoked. Custom commands have merged into skills: commands/*.md is the flat-file shorthand, while skills/<name>/SKILL.md supports additional files. Both create /name shortcuts and share the same invocation mechanism.
Example: api-integration - Claude automatically uses it when you need to interact with REST APIs
Subagents are specialized assistants with isolated context windows that Claude can delegate to — the subagent does its work and returns only a summary, keeping your main conversation clean. Invoke them by natural language delegation, by calling @agent-name directly, or by starting a session with claude --agent.
Example: security-reviewer - Specialized agent for security audits
Hooks run custom scripts automatically at specific lifecycle points — before tool execution, after prompts, when sessions start or end, and more. They are deterministic for configured events: Claude has no say in whether they fire. Note that async hooks cannot block or control Claude's behavior.
Example: pre-commit hook - Run tests before every commit
MCP servers provide standardized connections to external services like databases, APIs, cloud providers, and development tools. They expose tools and capabilities to Claude when configured and enabled. Remote MCP servers should use the HTTP transport (recommended) — the SSE transport is deprecated in current Claude Code.
Example: GitHub MCP - Access repositories and pull requests
LSP servers connect Claude Code to language servers that provide IDE-like features: go-to-definition, find references, hover documentation, and code diagnostics. They require you to have the language server binary installed on your system.
Example: TypeScript LSP - Get type information and navigate to definitions
Output styles modify Claude's system prompt to change role, tone, and response format. Built-in styles include Default, Proactive, Explanatory, and Learning. Custom styles are Markdown files with frontmatter — select them through Claude Code's output style controls. Use keep-coding-instructions: true to change communication style while keeping coding behavior.
Example: Diagrams first - Lead every explanation with a Mermaid diagram
Themes customize Claude Code's terminal colors, selectable via /theme alongside built-in presets. A theme is a JSON file with a base preset and a sparse overrides map of color tokens. Plugin themes are read-only; pressing Ctrl+E copies one to your local themes for editing. Themes are an experimental component — the manifest schema may change between releases.
Example: solarized-dark - Solarized color scheme for Claude Code
Monitors run a shell command for the lifetime of the session and deliver every stdout line to Claude as a notification, so Claude can react to log entries, status changes, or polled events without being asked. They run only in interactive CLI sessions. Monitors are an experimental component — the manifest schema may change between releases.
Example: deploy-watcher - Stream deployment status to Claude
Learn more in the official Claude Code plugin reference.
Not sure which component type fits your use case? Use this guide:
| When You Need... | Best Choice |
|---|---|
| Project-specific instructions | CLAUDE.md |
| Reusable workflow across projects | Skill |
| User-triggered automation | Command |
| External API/service access | MCP Server |
| Deterministic enforcement | Hook |
| Code intelligence features | LSP Server |
Pro tip: Start with CLAUDE.md
Begin with CLAUDE.md for project rules -- it requires no plugin setup. Only create a plugin when you need to share functionality across projects or with teammates.
CLAUDE.md vs AGENTS.md
AGENTS.md is the cross-tool equivalent of CLAUDE.md, used by Codex, Cursor, and other coding agents. Claude Code reads CLAUDE.md, not AGENTS.md directly. If your repo already uses AGENTS.md, create a CLAUDE.md that imports @AGENTS.md, or symlink CLAUDE.md to AGENTS.md if no Claude-specific additions are needed.
Single commands, agents, or MCP servers configured manually
Bundled packages that work together seamlessly
Imagine you're working on a web application that needs deployment automation. A DevOps plugin might include:
/deploy command
User-invoked: One-command secure deployments
Infrastructure subagent
Specialized knowledge of your cloud setup
Deployment skill
Invoked by Claude when deployment context is detected, or by you via /deployment-skill
Cloud provider MCP
Direct connections to AWS/Vercel/etc.
Pre-deployment hook
Event-driven: Run security scans before every deployment
Result: Install once with /plugin install devops-suite and get the complete automation stack.
Skills use lazy loading-- Claude only sees the skill name and description until it's actually needed. A detailed skill with hundreds of lines costs nothing until activated.
Rule of Thumb
If you find yourself adding instructions to CLAUDE.md that only matter for specific tasks, extract them into a skill instead. Your context window stays clean for the work that matters.
Example: API Documentation Skill
---
name: api-docs-helper
description: Generate OpenAPI documentation from code comments
---
# API Documentation Generator
When asked to document an API endpoint:
1. Extract JSDoc/docstring comments from the handler
2. Identify request/response types from TypeScript interfaces
3. Generate OpenAPI 3.0 YAML snippet
4. Include example request/response payloadsThis entire skill loads only when Claude detects you're working on API documentation -- not during unrelated tasks.
Both skills and flat commands support parameters via $ARGUMENTS and can spawn subagents for complex workflows.
Parameterized Command
---
name: deploy
description: Deploy to specified environment
arguments:
- name: environment
description: Target environment (staging/production)
required: true
---
Deploy the current branch to $ARGUMENTS environment.
Before deploying:
1. Run the test suite
2. Check for uncommitted changes
3. Verify the target environment is valid
After deployment, report the deployed commit SHA and URL.Usage: /deploy staging or /deploy production
Command with Subagent
---
name: research
description: Spawn a research agent to investigate a topic
---
Use the Task tool to spawn a research subagent with these instructions:
"Research the following topic thoroughly: $ARGUMENTS
Focus on:
- Official documentation
- Recent changes or updates
- Common pitfalls and gotchas
Return a concise summary with source links."
This keeps research isolated from your main conversation context.Subagents run in isolated context, preventing research from cluttering your main conversation.
Now that you understand what plugins are, learn how to install and use them.