holocron/plugins/kyberforge/docs/research/docs/claude-code-plugins/overview.md

topic, source_keys

topic	source_keys
overview	context7-websites-code-claude claude-code-plugins-docs claude-code-subagents-docs

What Plugins Are

Plugins extend Claude Code with custom functionality — skills, agents, hooks, MCP servers, LSP servers, background monitors, and default settings — that can be shared across projects and teams. The core distinction between standalone configuration (files in a project's .claude/ directory) and plugins (self-contained directories) is namespacing and shareability: standalone skill names look like /hello; the same skill packaged in a plugin becomes /my-plugin:hello, preventing naming conflicts between plugins.

A plugin lives in its own directory with a .claude-plugin/plugin.json manifest at the root. All content directories (skills/, agents/, hooks/, bin/) also live at the plugin root — not inside .claude-plugin/.

What Subagents Are

Subagents are specialized AI assistants that handle specific tasks inside a Claude Code session. Each subagent runs in its own isolated context window with a custom system prompt, restricted tool access, and independent permissions. When Claude encounters a task matching a subagent's description field, it delegates to that subagent; the subagent works independently and returns only a summary, keeping verbose output out of the main conversation.

Subagents differ from the main thread in three key ways:

• Isolated context: they start fresh (own system prompt, CLAUDE.md, git status snapshot, preloaded skills), not inheriting the main conversation
• Restricted tools: the tools frontmatter allowlist or disallowedTools denylist limits what they can do
• Independent model: a subagent can use a cheaper model (e.g. Haiku for fast search) without affecting the main session

Plugin Architecture

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Manifest (optional — components auto-discovered without it)
├── skills/                   # Agent Skills (/plugin-name:skill-name)
│   └── my-skill/
│       └── SKILL.md
├── agents/                   # Subagent definition files
│   └── specialist.md
├── hooks/
│   └── hooks.json
├── .mcp.json                # MCP server definitions
├── bin/                     # Executables added to Bash PATH
└── settings.json            # Default settings applied when plugin enabled

A plugin that ships exactly one skill can place SKILL.md directly at the plugin root instead of using the skills/ layout.

Built-in Subagents

Claude Code ships four built-in subagents registered automatically in interactive sessions:

Name	Model	Tools	Notes
Explore	Haiku	Read, Grep, Glob (read-only)	Fast codebase search; skips CLAUDE.md and git status
Plan	Inherits	Read-only	Used in plan mode; skips CLAUDE.md and git status
General-purpose	Inherits	All	Complex multi-step tasks
claude-code-guide	Haiku	Read, WebFetch, WebSearch	Claude Code questions

The Explore and Plan agents are one-shot and cannot be resumed; use general-purpose for resumable work.

Scope and Priority

When two subagent definitions share the same name, the higher-priority location wins:

1. Managed settings (org-wide policy, highest)
2. --agents CLI flag (session-only)
3. .claude/agents/ (project scope)
4. ~/.claude/agents/ (user scope, all projects)
5. Plugin agents/ directory (lowest)

Nesting and Limits

Subagents can spawn their own subagents up to depth 5 (not configurable). At depth 5 the Agent tool is withheld. A fork cannot spawn another fork.