A visual guide to Plugins, Subagents, and Skills—the three mechanisms for extending Claude Code's capabilities
Claude Code offers three complementary systems for extending its capabilities. Plugins bundle multiple extensions into shareable packages, subagents provide specialized AI assistants with isolated context, and skills inject task-specific instructions on demand.
All extensions live under the .claude/ directory at your project root, with optional user-level extensions in ~/.claude/.
Subagents are pre-configured AI personalities that Claude delegates tasks to. Each subagent operates in its own context window with specific tools and expertise.
| Problem | How Subagents Help |
|---|---|
| Context pollution | Each runs in isolated context window |
| Repetitive instructions | Define expertise once, reuse everywhere |
| Tool sprawl | Limit each subagent to relevant tools only |
| Team consistency | Share via version control |
--- name: code-reviewer # REQUIRED: lowercase-with-hyphens description: > # REQUIRED: When to invoke this agent Expert code reviewer. Use PROACTIVELY after any code changes to check quality and security. tools: Read, Grep, Glob, Bash # OPTIONAL: Limits available tools model: inherit # OPTIONAL: sonnet|opus|haiku|inherit permissionMode: default # OPTIONAL: How to handle permissions skills: project-conventions # OPTIONAL: Skills to auto-load --- <!-- BODY: The subagent's system prompt --> You are a senior code reviewer ensuring high standards. ## When Invoked 1. Run `git diff` to see recent changes 2. Focus on modified files only 3. Begin review immediately ## Review Checklist - [ ] Code is simple and readable - [ ] No duplicated logic - [ ] Proper error handling - [ ] No exposed secrets or API keys - [ ] Input validation implemented ## Output Format Organize feedback by priority: - 🔴 Critical (must fix before merge) - 🟡 Warning (should address) - 🟢 Suggestion (nice to have)
--- name: test-runner description: Run tests and fix failures. Use PROACTIVELY after code changes. tools: Read, Edit, Bash, Glob --- You are a test automation expert. ## Process 1. Detect test framework: `package.json` → Jest/Vitest, `pytest.ini` → pytest 2. Run appropriate command: `npm test` or `pytest -v` 3. If failures occur: - Analyze stack traces - Identify root cause - Fix while preserving test intent 4. Re-run to confirm fix ## Key Principle Never modify tests to make them pass. Fix the code they're testing.
--- name: doc-generator description: Generate API docs and README files. Use when creating documentation. tools: Read, Write, Grep, Glob model: opus --- You are a technical writer specializing in developer documentation. ## When Generating API Docs 1. Scan for exported functions/classes 2. Extract JSDoc/docstrings 3. Generate OpenAPI spec or markdown tables 4. Include code examples for each endpoint ## README Structure - Quick start (under 5 minutes) - Installation options - Configuration reference - Common use cases with examples
Skills are markdown files that teach Claude specific tasks. Unlike subagents, skills expand the current context rather than spawning new assistants. They use progressive disclosure to load only what's needed.
--- name: code-review # REQUIRED: max 64 chars description: > # REQUIRED: max 1024 chars Reviews code for quality, security, and best practices. Use when reviewing PRs or analyzing code changes. allowed-tools: "Bash(git:*),Read,Grep" # OPTIONAL: Tool permissions model: "claude-opus-4-20250514" # OPTIONAL: Model override version: "1.0.0" # OPTIONAL: Tracking disable-model-invocation: false # OPTIONAL: Manual-only if true user-invocable: true # OPTIONAL: Show in menu --- # Code Review Skill ## Prerequisites - Git repository with staged or committed changes - Access to source files ## Process ### Step 1: Gather Changes Run the analyzer script to collect diff information: ```bash python {baseDir}/scripts/analyzer.py --path . --output /tmp/review.json ``` ### Step 2: Review Checklist For each changed file, verify: - [ ] Functions under 50 lines - [ ] Clear variable names - [ ] Error handling present - [ ] No hardcoded secrets ## Resources For advanced patterns, see [{baseDir}/references/patterns.md]
--- name: commit-messages description: Generates conventional commit messages. Use when committing code. allowed-tools: "Bash(git diff:*),Bash(git status:*)" --- # Commit Message Generator ## Format ``` <type>(<scope>): <subject> <body> <footer> ``` ## Types - feat: New feature - fix: Bug fix - refactor: Code restructure - docs: Documentation - test: Adding tests ## Process 1. Run `git diff --staged --stat` for overview 2. Run `git diff --staged` for details 3. Identify primary change type 4. Generate message following format
--- name: api-scaffold description: Scaffold REST API endpoints with validation and tests. allowed-tools: "Read,Write,Bash(npm:*)" --- # API Endpoint Scaffolding ## Process 1. Get endpoint details: method, path, request/response schema 2. Generate files: - `routes/<resource>.ts` - Route handler - `validators/<resource>.ts` - Zod schemas - `tests/<resource>.test.ts` - Integration tests ## Template ```typescript import { Router } from 'express'; import { validate } from '../middleware/validate'; import { {Resource}Schema } from '../validators/{resource}'; const router = Router(); router.post('/', validate({Resource}Schema), async (req, res) => { // Implementation }); export default router; ```
Plugins are shareable packages that bundle multiple extensions (commands, subagents, skills, hooks, MCP servers) into installable units.
{
// ═══════════════════════════════════════════════════════════
// REQUIRED FIELD
// ═══════════════════════════════════════════════════════════
"name": "code-quality-suite", // Unique, kebab-case identifier
// ═══════════════════════════════════════════════════════════
// METADATA (optional but recommended)
// ═══════════════════════════════════════════════════════════
"version": "1.2.0", // Semantic version
"description": "Code review, testing, and documentation tools",
"author": {
"name": "Dev Team",
"email": "dev@example.com"
},
"license": "MIT",
// ═══════════════════════════════════════════════════════════
// COMPONENT PATHS (optional - supplements default locations)
// ═══════════════════════════════════════════════════════════
"commands": "./extra-commands/", // String or array
"agents": [ // Multiple paths supported
"./agents/",
"./advanced-agents/"
],
"mcpServers": { // Inline MCP config
"plugin-db": {
"command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
"args": ["--port", "5432"]
}
}
}
| Feature | Subagents | Skills | Plugins |
|---|---|---|---|
| Primary purpose | Delegate to specialists | Expand prompts | Bundle & share |
| Context | Own isolated window | Same conversation | Container for others |
| Location | .claude/agents/*.md | .claude/skills/*/SKILL.md | */.claude-plugin/ |
| Invocation | Auto or explicit | Auto via Skill tool | Contains other types |
| Tool access | Configurable per agent | Scoped via allowed-tools | Inherited by contents |
| Model override | ✓ Yes | ✓ Yes | Via contained agents |
| Resumable | ✓ Yes (agentId) | ✗ No | N/A |
| Shareability | Copy .md file | Copy skill folder | Install from marketplace |
| Scenario | Best Choice | Why |
|---|---|---|
| Code review automation | Subagent | Needs isolated context, specialized tools |
| Test generation | Subagent | Complex multi-step process, tool access |
| Documentation generation | Skill or Subagent | Skill for templates, subagent for full docs |
| Linting/formatting | Plugin with hooks | Triggers automatically after edits |
| API scaffolding | Skill | Inject templates into current context |
| Project conventions | Skill | Expand prompts with team standards |
| Team tooling bundle | Plugin | Distribute multiple extensions together |
| Error | Cause | Fix |
|---|---|---|
| Subagent not appearing | File not in agents/ | Move to .claude/agents/ |
| Skill not loading | SKILL.md in wrong location | Must be .claude/skills/<n>/SKILL.md |
| Plugin commands missing | Wrong directory structure | Ensure commands/ at plugin root |
| Hook not firing | Script not executable | chmod +x script.sh |
| Path errors after install | Absolute paths used | Use ${CLAUDE_PLUGIN_ROOT} or {baseDir} |
| YAML parse error | Tabs or missing --- | Use spaces, ensure frontmatter starts line 1 |
Claude Code's extensibility architecture follows a composition pattern: skills provide atomic capabilities, subagents combine skills with isolated context for complex tasks, and plugins bundle everything into distributable packages.
The key insight is that each mechanism operates at a different level of abstraction—skills expand prompts, subagents delegate execution, and plugins organize distribution.
For most coding workflows: start with skills for reusable instructions, add subagents when you need specialized delegation with isolated context, and wrap everything in a plugin when you need to share across teams or projects.