docs(kyberforge): add Claude Code plugins and subagents research
Research from official docs (code.claude.com) and Context7, covering plugin manifest schema, agent definition frontmatter spec, scope priority, marketplace distribution, and plugin subagent restrictions. Foundation for writing an agent-author skill. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,109 @@
|
||||
---
|
||||
topic: agent-definition
|
||||
source_keys:
|
||||
- context7-websites-code-claude
|
||||
- claude-code-plugins-docs
|
||||
- claude-code-subagents-docs
|
||||
---
|
||||
|
||||
## File Format
|
||||
|
||||
Agent definitions are Markdown files with YAML frontmatter. Place them in an `agents/` directory at the plugin root (for plugin-distributed agents) or in `.claude/agents/` (project scope) or `~/.claude/agents/` (user scope).
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: code-reviewer
|
||||
description: Reviews code for correctness, security, and maintainability. Use proactively after code changes.
|
||||
tools: Read, Grep, Glob, Bash
|
||||
model: sonnet
|
||||
effort: medium
|
||||
maxTurns: 20
|
||||
---
|
||||
|
||||
You are a senior code reviewer. When invoked, analyze the changed code and provide
|
||||
specific, actionable feedback on quality, security, and best practices.
|
||||
```
|
||||
|
||||
The frontmatter block configures the agent's identity and constraints. The body is the system prompt.
|
||||
|
||||
## Required Fields
|
||||
|
||||
**`name`** — Unique identifier. Lowercase letters and hyphens only. Hooks receive this as `agent_type`. The filename does not need to match the name field. Duplicate names within the same scope level: Claude Code silently keeps one and discards the other without warning.
|
||||
|
||||
**`description`** — Tells Claude when to delegate to this agent. This is the most important field for autonomous delegation. Include "use proactively" to trigger automatic invocation without explicit user direction. Be specific about the triggering condition and the agent's expertise.
|
||||
|
||||
## Optional Fields
|
||||
|
||||
**`tools`** — Allowlist of tool names the agent can use. Omit to inherit all tools from the parent. Comma-separated or YAML list. Use `Agent(type1,type2)` to restrict which subagent types this agent can spawn; `Agent` without parens allows spawning any subagent; omitting `Agent` entirely prevents spawning.
|
||||
|
||||
**`disallowedTools`** — Denylist applied before `tools`. Supports `mcp__<server>` (one server's tools), `mcp__<server>__*` (glob), and `mcp__*` (removes all MCP tools). Takes precedence over `tools`.
|
||||
|
||||
**`model`** — Model to use. Accepts aliases (`sonnet`, `opus`, `haiku`, `fable`), full model IDs (`claude-opus-4-8`), or `inherit` (default). Resolution order: `CLAUDE_CODE_SUBAGENT_MODEL` env var → per-invocation model parameter → frontmatter model → main conversation model. If the resolved model is excluded by `availableModels` policy, falls back to the inherited model.
|
||||
|
||||
**`effort`** — Reasoning level: `low`, `medium`, `high`, `xhigh`, `max`, or a numeric value. Overrides the session effort level for this agent.
|
||||
|
||||
**`maxTurns`** — Integer cap on agentic turns. Prevents runaway agents.
|
||||
|
||||
**`permissionMode`** — One of `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan`. Silently ignored for plugin subagents — only works for `.claude/agents/` and `~/.claude/agents/`. Parent `bypassPermissions` or `acceptEdits` overrides child; parent `auto` mode overrides child permissionMode entirely.
|
||||
|
||||
**`skills`** — List of skill names to preload into the agent's context at startup (full skill body injected). Enables the agent to invoke skills by name.
|
||||
|
||||
**`mcpServers`** — Inline MCP server definitions (stdio/http/sse/ws schema keyed by server name) or string references to already-configured servers. Silently ignored for plugin subagents.
|
||||
|
||||
**`hooks`** — Per-agent `PreToolUse`/`PostToolUse`/`Stop` event handlers scoped to this agent's context. `Stop` auto-converts to `SubagentStop` when used as a subagent. Silently ignored for plugin subagents.
|
||||
|
||||
**`memory`** — Persistent cross-session memory: `user` (stored at `~/.claude/agent-memory/<name>/`), `project` (`.claude/agent-memory/<name>/`), or `local` (`.claude/agent-memory-local/<name>/`). Enables MEMORY.md (first 200 lines/25KB loaded at startup). Auto-enables Read/Write/Edit tools.
|
||||
|
||||
**`background`** — Boolean. Forces background execution when `true` (default `false`).
|
||||
|
||||
**`isolation`** — Set to `worktree` to run the agent in an isolated temporary git worktree branched from the default branch. Auto-cleaned if no changes are made.
|
||||
|
||||
**`color`** — UI color for this agent: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`.
|
||||
|
||||
**`initialPrompt`** — Auto-submitted as the first user turn when the agent runs as the main session (via `--agent` flag or `agent` setting in `settings.json`). Supports commands and skills. Prepended to the user's own prompt.
|
||||
|
||||
## TypeScript AgentDefinition Shape
|
||||
|
||||
```typescript
|
||||
type AgentDefinition = {
|
||||
description: string;
|
||||
tools?: string[];
|
||||
disallowedTools?: string[];
|
||||
prompt: string; // equivalent to the markdown body
|
||||
model?: string;
|
||||
mcpServers?: AgentMcpServerSpec[];
|
||||
skills?: string[];
|
||||
initialPrompt?: string;
|
||||
maxTurns?: number;
|
||||
background?: boolean;
|
||||
memory?: "user" | "project" | "local";
|
||||
effort?: "low" | "medium" | "high" | "xhigh" | "max" | number;
|
||||
permissionMode?: PermissionMode;
|
||||
criticalSystemReminder_EXPERIMENTAL?: string;
|
||||
};
|
||||
```
|
||||
|
||||
When passing agents via the `--agents` CLI flag, use `prompt` instead of the markdown body.
|
||||
|
||||
## Tools Always Unavailable to Subagents
|
||||
|
||||
Regardless of the `tools` field, these tools are never available to any subagent:
|
||||
- `AskUserQuestion`
|
||||
- `EnterPlanMode`
|
||||
- `ExitPlanMode` (unless `permissionMode` is `plan`)
|
||||
- `ScheduleWakeup`
|
||||
- `WaitForMcpServers`
|
||||
|
||||
## Plugin Subagent Restrictions
|
||||
|
||||
Plugin agents (in a plugin's `agents/` directory) silently ignore: `hooks`, `mcpServers`, and `permissionMode`. To use those features, copy the agent file into `.claude/agents/` or `~/.claude/agents/`.
|
||||
|
||||
## Scoped Identifiers for Plugin Agents
|
||||
|
||||
Unlike project/user scope agents where subdirectory path doesn't affect identity, plugin agents in subfolders get scoped identifiers:
|
||||
|
||||
```
|
||||
plugins/my-plugin/agents/review/security.md → my-plugin:review:security
|
||||
```
|
||||
|
||||
Users invoke these via `@agent-my-plugin:review:security` or the `/agents` UI.
|
||||
@@ -0,0 +1,99 @@
|
||||
---
|
||||
topic: api-reference
|
||||
source_keys:
|
||||
- context7-websites-code-claude
|
||||
- claude-code-plugins-docs
|
||||
- claude-code-subagents-docs
|
||||
---
|
||||
|
||||
## Plugin Manifest Fields (`plugin.json`)
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|---|---|---|---|
|
||||
| `name` | string | Yes (for namespacing) | Unique plugin identifier; prefix for skill names |
|
||||
| `displayName` | string | No | Human-readable name shown in plugin manager |
|
||||
| `version` | string | No | If omitted, git commit SHA is used |
|
||||
| `description` | string | No | Shown in plugin manager |
|
||||
| `author` | object | No | `{ name, email, url }` |
|
||||
| `homepage` | string | No | Documentation URL |
|
||||
| `repository` | string | No | Source repository URL |
|
||||
| `license` | string | No | SPDX license identifier |
|
||||
| `keywords` | string[] | No | Search/discovery tags |
|
||||
| `skills` | string | No | Path to skills directory (default: `./skills/`) |
|
||||
| `agents` | string[] | No | Explicit list of agent file paths |
|
||||
| `hooks` | string | No | Path to hooks.json |
|
||||
| `mcpServers` | string | No | Path to MCP server config |
|
||||
| `lspServers` | string | No | Path to `.lsp.json` |
|
||||
| `outputStyles` | string | No | Path to output styles directory |
|
||||
| `experimental.themes` | string | No | Path to themes directory |
|
||||
| `experimental.monitors` | string | No | Path to monitors.json |
|
||||
| `dependencies` | array | No | Plugin dependencies; string or `{ name, version }` |
|
||||
|
||||
## Agent Frontmatter Fields
|
||||
|
||||
| Field | Type | Required | Plugin subagent? | Description |
|
||||
|---|---|---|---|---|
|
||||
| `name` | string | Yes | Yes | Unique, lowercase + hyphens; hooks receive as `agent_type` |
|
||||
| `description` | string | Yes | Yes | Tells Claude when to delegate; "use proactively" triggers auto-invocation |
|
||||
| `tools` | string / list | No | Yes | Allowlist; `Agent(t1,t2)` restricts spawnable subagent types |
|
||||
| `disallowedTools` | string / list | No | Yes | Denylist; applied before `tools`; supports `mcp__*` glob patterns |
|
||||
| `model` | string | No | Yes | `sonnet`/`opus`/`haiku`/`fable` alias, full model ID, or `inherit` |
|
||||
| `effort` | string / number | No | Yes | `low`/`medium`/`high`/`xhigh`/`max` or numeric |
|
||||
| `maxTurns` | integer | No | Yes | Max agentic turns before stopping |
|
||||
| `permissionMode` | string | No | **No** | `default`/`acceptEdits`/`auto`/`dontAsk`/`bypassPermissions`/`plan` |
|
||||
| `skills` | list | No | Yes | Skill names to preload into context at startup |
|
||||
| `mcpServers` | object / list | No | **No** | Inline server defs or string references to configured servers |
|
||||
| `hooks` | object | No | **No** | Per-agent PreToolUse/PostToolUse/Stop handlers |
|
||||
| `memory` | string | No | Yes | `user`/`project`/`local`; enables MEMORY.md persistence |
|
||||
| `background` | boolean | No | Yes | Force background execution (default: `false`) |
|
||||
| `isolation` | string | No | Yes | `worktree` runs in isolated git worktree |
|
||||
| `color` | string | No | Yes | UI color: `red`/`blue`/`green`/`yellow`/`purple`/`orange`/`pink`/`cyan` |
|
||||
| `initialPrompt` | string | No | Yes | Auto-submitted first user turn when agent is main session thread |
|
||||
|
||||
Fields marked **No** in the "Plugin subagent?" column are silently ignored when the agent file lives in a plugin's `agents/` directory.
|
||||
|
||||
## CLI Flags
|
||||
|
||||
| Flag | Description |
|
||||
|---|---|
|
||||
| `--plugin-dir <path>` | Load a plugin directory or `.zip` archive for this session |
|
||||
| `--plugin-url <url>` | Load a plugin from a URL-hosted zip |
|
||||
| `--agents '<json>'` | Define session-only subagents as JSON (uses `prompt` not markdown body) |
|
||||
| `--agent <name>` | Run entire session as the named subagent |
|
||||
| `--disallowedTools 'Agent(name)'` | Block specific subagents |
|
||||
|
||||
Multiple `--plugin-dir` flags are supported for loading multiple plugins.
|
||||
|
||||
## In-Session Commands
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `/reload-plugins` | Pick up plugin file changes without restarting the session |
|
||||
| `/plugin install` | Install a plugin from a configured marketplace |
|
||||
| `/plugin marketplace add <source>` | Add a marketplace source |
|
||||
| `claude plugin init <name>` | Scaffold a new plugin under `~/.claude/skills/<name>/` |
|
||||
| `claude plugin validate` | Run the same lint checks the marketplace submission pipeline runs |
|
||||
| `/agents` | Open the agent management UI (Running + Library tabs) |
|
||||
| `/fork <directive>` | Spawn a fork subagent inheriting full conversation history |
|
||||
| `@agent-<name>` | Invoke a specific subagent for one task |
|
||||
| `@agent-<plugin>:<name>` | Invoke a scoped plugin subagent for one task |
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description |
|
||||
|---|---|
|
||||
| `CLAUDE_CODE_SUBAGENT_MODEL` | Override model for all subagents |
|
||||
| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1` | Remove built-ins in non-interactive/SDK mode |
|
||||
| `CLAUDE_CODE_FORK_SUBAGENT=1` | Enable fork mode (experimental; also forces all spawns background) |
|
||||
| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1` | Disable background task functionality |
|
||||
| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | Apply to subagent auto-compaction |
|
||||
|
||||
## Subagent Transcript Storage
|
||||
|
||||
Subagent transcripts are stored at:
|
||||
|
||||
```
|
||||
~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl
|
||||
```
|
||||
|
||||
Cleanup period is controlled by the `cleanupPeriodDays` setting (default 30 days).
|
||||
@@ -0,0 +1,109 @@
|
||||
---
|
||||
topic: configuration
|
||||
source_keys:
|
||||
- context7-websites-code-claude
|
||||
- claude-code-plugins-docs
|
||||
- claude-code-subagents-docs
|
||||
---
|
||||
|
||||
## Plugin Manifest (`plugin.json`)
|
||||
|
||||
The manifest lives at `.claude-plugin/plugin.json` in the plugin root directory. It is optional — components are auto-discovered without it — but required for namespacing, versioning, and marketplace distribution.
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "plugin-name",
|
||||
"displayName": "Plugin Name",
|
||||
"version": "1.2.0",
|
||||
"description": "Brief plugin description",
|
||||
"author": {
|
||||
"name": "Author Name",
|
||||
"email": "author@example.com",
|
||||
"url": "https://github.com/author"
|
||||
},
|
||||
"homepage": "https://docs.example.com/plugin",
|
||||
"repository": "https://github.com/author/plugin",
|
||||
"license": "MIT",
|
||||
"keywords": ["keyword1", "keyword2"],
|
||||
"skills": "./custom/skills/",
|
||||
"commands": ["./custom/commands/special.md"],
|
||||
"agents": ["./custom/agents/reviewer.md"],
|
||||
"hooks": "./config/hooks.json",
|
||||
"mcpServers": "./mcp-config.json",
|
||||
"outputStyles": "./styles/",
|
||||
"lspServers": "./.lsp.json",
|
||||
"experimental": {
|
||||
"themes": "./themes/",
|
||||
"monitors": "./monitors.json"
|
||||
},
|
||||
"dependencies": [
|
||||
"helper-lib",
|
||||
{ "name": "secrets-vault", "version": "~2.1.0" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**`name`** — Required for namespacing. Skills under this plugin are invoked as `/plugin-name:skill-name`. Must be unique across installed plugins.
|
||||
|
||||
**`version`** — Optional string. If omitted, the git commit SHA is used and every commit is treated as a new version.
|
||||
|
||||
**`author`** — Optional object with `name`, `email`, and `url`.
|
||||
|
||||
All path values in the manifest are relative to the plugin root.
|
||||
|
||||
## Plugin `settings.json`
|
||||
|
||||
A `settings.json` at the plugin root applies default settings when the plugin is enabled. Currently supports only two keys:
|
||||
|
||||
```json
|
||||
{
|
||||
"agent": "security-reviewer",
|
||||
"subagentStatusLine": true
|
||||
}
|
||||
```
|
||||
|
||||
**`agent`** — Activates a named agent from the plugin's `agents/` directory as the main session thread, replacing the default Claude Code system prompt with the agent's system prompt, tool restrictions, and model. Project and user `.claude/agents/` definitions with the same name override this.
|
||||
|
||||
Settings in `settings.json` take priority over `settings` declared inside `plugin.json`.
|
||||
|
||||
## Plugin Directory Layout
|
||||
|
||||
All content directories must be at the plugin root, not inside `.claude-plugin/`:
|
||||
|
||||
| Directory / File | Purpose |
|
||||
|---|---|
|
||||
| `skills/<name>/SKILL.md` | Skills (namespaced as `/plugin-name:skill-name`) |
|
||||
| `agents/` | Agent definition markdown files |
|
||||
| `hooks/hooks.json` | Event handlers (PreToolUse, PostToolUse, etc.) |
|
||||
| `.mcp.json` | MCP server definitions |
|
||||
| `.lsp.json` | LSP server definitions |
|
||||
| `monitors/monitors.json` | Background shell monitors |
|
||||
| `bin/` | Executables added to the Bash tool's PATH |
|
||||
| `settings.json` | Default settings applied when plugin enabled |
|
||||
|
||||
## Agent Activation as Main Thread
|
||||
|
||||
Setting `agent` in `settings.json` (or in `.claude/settings.json` for project scope) makes a subagent the default for every session:
|
||||
|
||||
```json
|
||||
// .claude/settings.json or plugin settings.json
|
||||
{
|
||||
"agent": "my-specialist-agent"
|
||||
}
|
||||
```
|
||||
|
||||
The named agent must exist in an `agents/` directory accessible to that scope. When activated this way, the agent's `initialPrompt` field is auto-submitted as the first user turn.
|
||||
|
||||
## Disabling Subagents
|
||||
|
||||
Add `Agent(subagent-name)` to `permissions.deny` in `settings.json` to block specific subagents. To block all subagent delegation, deny the `Agent` tool itself.
|
||||
|
||||
In non-interactive/SDK mode, set `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1` to remove all built-ins.
|
||||
|
||||
## Model Configuration
|
||||
|
||||
```
|
||||
CLAUDE_CODE_SUBAGENT_MODEL=<model-id> # global override for all subagents
|
||||
```
|
||||
|
||||
Resolution order: env var → per-invocation model parameter → frontmatter `model` → main session model.
|
||||
@@ -0,0 +1,198 @@
|
||||
---
|
||||
topic: examples
|
||||
source_keys:
|
||||
- context7-websites-code-claude
|
||||
- claude-code-subagents-docs
|
||||
- claude-code-plugins-docs
|
||||
---
|
||||
|
||||
## Minimal Plugin Structure
|
||||
|
||||
A plugin that ships a single skill can use the flat layout — `SKILL.md` directly at the plugin root:
|
||||
|
||||
```
|
||||
my-plugin/
|
||||
├── .claude-plugin/
|
||||
│ └── plugin.json
|
||||
└── SKILL.md
|
||||
```
|
||||
|
||||
For multiple skills or agents, use the full layout:
|
||||
|
||||
```
|
||||
my-plugin/
|
||||
├── .claude-plugin/
|
||||
│ └── plugin.json
|
||||
├── skills/
|
||||
│ └── hello/
|
||||
│ └── SKILL.md
|
||||
├── agents/
|
||||
│ └── reviewer.md
|
||||
└── settings.json
|
||||
```
|
||||
|
||||
## Plugin Manifest
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"displayName": "My Plugin",
|
||||
"version": "0.1.0",
|
||||
"description": "Example plugin with skills and agents",
|
||||
"author": { "name": "Dev Team" },
|
||||
"license": "MIT"
|
||||
}
|
||||
```
|
||||
|
||||
## Agent Definition: Read-Only Code Reviewer
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: code-reviewer
|
||||
description: Reviews code for correctness, security, and maintainability. Use proactively after code changes.
|
||||
tools: Read, Grep, Glob, Bash
|
||||
model: sonnet
|
||||
effort: medium
|
||||
---
|
||||
|
||||
You are a senior code reviewer. When invoked:
|
||||
|
||||
1. Run `git diff` to identify changed files
|
||||
2. Review each changed file for:
|
||||
- Correctness: logic errors, edge cases, null handling
|
||||
- Security: injection vulnerabilities, auth bypass, data exposure
|
||||
- Maintainability: naming, complexity, duplication
|
||||
|
||||
Prioritize findings as Critical / Warning / Suggestion.
|
||||
```
|
||||
|
||||
## Agent Definition: Debugger with Edit Access
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: debugger
|
||||
description: Debugging specialist for errors and test failures. Use when tests fail or an error is reported.
|
||||
tools: Read, Edit, Bash, Grep, Glob
|
||||
---
|
||||
|
||||
You are an expert debugger. Follow this workflow:
|
||||
|
||||
1. Capture the full error message and stack trace
|
||||
2. Identify the root cause (not just the symptom)
|
||||
3. Locate the relevant code with Grep/Read
|
||||
4. Apply the fix with Edit
|
||||
5. Verify the fix by re-running the failing command
|
||||
```
|
||||
|
||||
## Agent Definition: Data Scientist with Scoped MCP
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: data-scientist
|
||||
description: Runs SQL queries and analyzes data. Use for BigQuery analysis and reporting tasks.
|
||||
tools: Bash, Read, Write
|
||||
model: sonnet
|
||||
---
|
||||
|
||||
You are a data analysis specialist focused on SQL and BigQuery.
|
||||
Present findings with concrete numbers and recommendations, not just observations.
|
||||
```
|
||||
|
||||
## Agent Definition: Coordinator with Restricted Spawning
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: coordinator
|
||||
description: Orchestrates multi-step research tasks. Delegates to worker and researcher subagents.
|
||||
tools: Agent(worker, researcher), Read, Bash
|
||||
---
|
||||
|
||||
You are a task coordinator. Break complex requests into subtasks and delegate each to the
|
||||
appropriate specialist. Collect results and synthesize a final summary.
|
||||
```
|
||||
|
||||
## CLI-Defined Subagents (`--agents` flag)
|
||||
|
||||
```json
|
||||
{
|
||||
"code-reviewer": {
|
||||
"description": "Expert code reviewer. Use proactively after code changes.",
|
||||
"prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
|
||||
"tools": ["Read", "Grep", "Glob", "Bash"],
|
||||
"model": "sonnet"
|
||||
},
|
||||
"debugger": {
|
||||
"description": "Debugging specialist for errors and test failures.",
|
||||
"prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
When using `--agents`, the markdown body becomes `prompt` (not the YAML frontmatter body).
|
||||
|
||||
## Programmatic Subagents (Agent SDK)
|
||||
|
||||
```python
|
||||
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition
|
||||
|
||||
async for message in query(
|
||||
prompt="Review the authentication module for security issues",
|
||||
options=ClaudeAgentOptions(
|
||||
allowed_tools=["Read", "Grep", "Glob", "Agent"],
|
||||
agents={
|
||||
"code-reviewer": AgentDefinition(
|
||||
description="Expert code review specialist. Use for quality, security, and maintainability reviews.",
|
||||
prompt="You are a code review specialist...",
|
||||
tools=["Read", "Grep", "Glob"],
|
||||
model="sonnet",
|
||||
),
|
||||
},
|
||||
),
|
||||
):
|
||||
if hasattr(message, "result"):
|
||||
print(message.result)
|
||||
```
|
||||
|
||||
## Plugin Marketplace Definition
|
||||
|
||||
A private or team marketplace JSON file:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "company-tools",
|
||||
"owner": {
|
||||
"name": "DevTools Team",
|
||||
"email": "devtools@example.com"
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
"name": "code-formatter",
|
||||
"source": "./plugins/formatter",
|
||||
"description": "Automatic code formatting on save",
|
||||
"version": "2.1.0",
|
||||
"author": { "name": "DevTools Team" }
|
||||
},
|
||||
{
|
||||
"name": "deployment-tools",
|
||||
"source": {
|
||||
"source": "github",
|
||||
"repo": "company/deploy-plugin"
|
||||
},
|
||||
"description": "Deployment automation tools"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Default Agent Activation
|
||||
|
||||
To make a plugin agent the default for every session when the plugin is enabled:
|
||||
|
||||
```json
|
||||
// plugin-root/settings.json
|
||||
{
|
||||
"agent": "security-reviewer"
|
||||
}
|
||||
```
|
||||
|
||||
The named agent must be defined in the plugin's `agents/` directory. The same pattern works in `.claude/settings.json` for project-scoped agent activation.
|
||||
@@ -0,0 +1,69 @@
|
||||
---
|
||||
topic: installation
|
||||
source_keys:
|
||||
- claude-code-plugins-docs
|
||||
---
|
||||
|
||||
## Loading a Plugin for a Session
|
||||
|
||||
Use the `--plugin-dir` flag to load a plugin directory for a session:
|
||||
|
||||
```bash
|
||||
claude --plugin-dir ./my-plugin
|
||||
```
|
||||
|
||||
The flag also accepts a `.zip` archive (requires Claude Code v2.1.128+):
|
||||
|
||||
```bash
|
||||
claude --plugin-dir ./my-plugin.zip
|
||||
```
|
||||
|
||||
Load from a URL-hosted zip:
|
||||
|
||||
```bash
|
||||
claude --plugin-url https://example.com/my-plugin.zip
|
||||
```
|
||||
|
||||
Repeat the flag to load multiple plugins simultaneously:
|
||||
|
||||
```bash
|
||||
claude --plugin-dir ./plugin-a --plugin-dir ./plugin-b
|
||||
```
|
||||
|
||||
When a `--plugin-dir` plugin has the same name as an installed marketplace plugin, the local copy takes precedence.
|
||||
|
||||
## Persistent Installation
|
||||
|
||||
Scaffold a new plugin under `~/.claude/skills/<name>/` for auto-loading across all sessions:
|
||||
|
||||
```bash
|
||||
claude plugin init my-tool
|
||||
```
|
||||
|
||||
This creates the plugin structure and registers it as `my-tool@skills-dir` on the next session start.
|
||||
|
||||
## Installing from a Marketplace
|
||||
|
||||
After configuring a marketplace source:
|
||||
|
||||
```
|
||||
/plugin install
|
||||
```
|
||||
|
||||
To add the community marketplace:
|
||||
|
||||
```
|
||||
/plugin marketplace add anthropics/claude-plugins-community
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
During active development, use `/reload-plugins` inside a running session to pick up file changes without restarting. Note that agent files added manually (outside the `/agents` UI) require a session restart to load.
|
||||
|
||||
## Validation
|
||||
|
||||
Before submitting a plugin to a marketplace, run the same lint check the review pipeline uses:
|
||||
|
||||
```bash
|
||||
claude plugin validate
|
||||
```
|
||||
@@ -0,0 +1,80 @@
|
||||
---
|
||||
topic: marketplace
|
||||
source_keys:
|
||||
- context7-websites-code-claude
|
||||
- claude-code-plugins-docs
|
||||
- claude-code-subagents-docs
|
||||
---
|
||||
|
||||
## Public Marketplaces
|
||||
|
||||
Anthropic maintains two public plugin marketplaces:
|
||||
|
||||
**`claude-plugins-official`** — Curated by Anthropic. Registered automatically on first interactive launch. No application process; Anthropic selects plugins at their discretion.
|
||||
|
||||
**`claude-community`** — Third-party submissions after review. Not auto-registered; users add it via:
|
||||
|
||||
```
|
||||
/plugin marketplace add anthropics/claude-plugins-community
|
||||
```
|
||||
|
||||
Approved plugins are pinned to a commit SHA in `anthropics/claude-plugins-community`. CI bumps the pin automatically. The public catalog syncs nightly.
|
||||
|
||||
## Submitting to the Community Marketplace
|
||||
|
||||
Two submission paths:
|
||||
|
||||
- **Team/Enterprise**: Submit via `claude.ai/admin-settings/directory/submissions/plugins/new` (requires Team or Enterprise org with directory management access)
|
||||
- **Individual authors**: Submit via `platform.claude.com/plugins/submit`
|
||||
|
||||
Before submitting, run `claude plugin validate` locally — the review pipeline runs the same check. Check `marketplace.json` in the community catalog to confirm installability after approval.
|
||||
|
||||
## Private / Team Marketplaces
|
||||
|
||||
Teams can host private marketplaces in private git repositories. The marketplace definition is a JSON file:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "company-tools",
|
||||
"owner": {
|
||||
"name": "DevTools Team",
|
||||
"email": "devtools@example.com"
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
"name": "code-formatter",
|
||||
"source": "./plugins/formatter",
|
||||
"description": "Automatic code formatting on save",
|
||||
"version": "2.1.0",
|
||||
"author": { "name": "DevTools Team" }
|
||||
},
|
||||
{
|
||||
"name": "deployment-tools",
|
||||
"source": {
|
||||
"source": "github",
|
||||
"repo": "company/deploy-plugin"
|
||||
},
|
||||
"description": "Deployment automation tools"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The `source` field accepts either a local path string or a `{ source: "github", repo: "org/repo" }` object.
|
||||
|
||||
## Loading Plugins
|
||||
|
||||
| Method | Scope | Notes |
|
||||
|---|---|---|
|
||||
| `--plugin-dir <path>` | Session | Accepts directory or `.zip`; repeatable for multiple plugins |
|
||||
| `--plugin-url <url>` | Session | URL-hosted zip; requires v2.1.128+ |
|
||||
| `claude plugin init <name>` | Persistent | Creates plugin at `~/.claude/skills/<name>/`, auto-loads as `name@skills-dir` |
|
||||
| `/plugin install` | Persistent | Installs from a configured marketplace |
|
||||
|
||||
A local `--plugin-dir` plugin with the same name as an installed marketplace plugin takes precedence.
|
||||
|
||||
## Plugin Distribution via Kyberforge
|
||||
|
||||
This repo (kyberforge) is itself a plugin distributed via the Holocron marketplace. The marketplace manifest lives at `.claude-plugin/marketplace.json` (or `plugin.json`). Plugins are installed by pointing Claude Code at the marketplace source.
|
||||
|
||||
Plugin agents defined in the kyberforge `agents/` directory are available as `kyberforge:<agent-name>` in any session where the plugin is loaded. Subdirectory nesting creates deeper scoped identifiers: `kyberforge:category:agent-name`.
|
||||
@@ -0,0 +1,69 @@
|
||||
---
|
||||
topic: overview
|
||||
source_keys:
|
||||
- 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.
|
||||
@@ -0,0 +1,22 @@
|
||||
# Sources
|
||||
|
||||
## context7-websites-code-claude
|
||||
|
||||
- **URL:** context7:/websites/code_claude
|
||||
- **Description:** Official Claude Code documentation site indexed by Context7 — plugin manifest schema, subagent definition types, marketplace JSON format, agent markdown file format
|
||||
- **Contributing files:** overview.md, agent-definition.md, configuration.md, examples.md, api-reference.md, marketplace.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## claude-code-plugins-docs
|
||||
|
||||
- **URL:** https://code.claude.com/docs/en/plugins
|
||||
- **Description:** Official Claude Code plugin authoring guide — plugin structure, manifest fields, loading methods, skill namespacing, agent activation, marketplace submission
|
||||
- **Contributing files:** overview.md, installation.md, configuration.md, examples.md, api-reference.md, marketplace.md, troubleshooting.md
|
||||
- **Status:** `extracted`
|
||||
|
||||
## claude-code-subagents-docs
|
||||
|
||||
- **URL:** https://code.claude.com/docs/en/sub-agents
|
||||
- **Description:** Official Claude Code subagent reference — definition format, all frontmatter fields, scope priority, built-in agents, CLI flags, environment variables, known limitations
|
||||
- **Contributing files:** overview.md, agent-definition.md, configuration.md, examples.md, api-reference.md, marketplace.md, troubleshooting.md
|
||||
- **Status:** `extracted`
|
||||
@@ -0,0 +1,63 @@
|
||||
---
|
||||
topic: troubleshooting
|
||||
source_keys:
|
||||
- claude-code-subagents-docs
|
||||
- claude-code-plugins-docs
|
||||
---
|
||||
|
||||
## Agent Files Not Loading
|
||||
|
||||
Files added manually to `agents/` directories require a full session restart to load. Files created or edited via the `/agents` UI take effect immediately. Use `/reload-plugins` inside a session to pick up plugin file changes without restarting.
|
||||
|
||||
## Duplicate Agent Names
|
||||
|
||||
When two agent definitions share the same `name` within the same scope level, Claude Code silently keeps one and discards the other without warning. Use unique names or rely on scope priority (project `.claude/agents/` overrides plugin agents).
|
||||
|
||||
## Plugin Frontmatter Fields Silently Ignored
|
||||
|
||||
Plugin subagents (files in a plugin's `agents/` directory) silently ignore `hooks`, `mcpServers`, and `permissionMode`. To use these features, copy the agent file to `.claude/agents/` (project scope) or `~/.claude/agents/` (user scope).
|
||||
|
||||
## permissionMode Overrides
|
||||
|
||||
Parent session mode overrides child subagent mode in two cases:
|
||||
- Parent uses `bypassPermissions` or `acceptEdits` → child cannot override
|
||||
- Parent uses `auto` mode → child `permissionMode` is ignored entirely
|
||||
|
||||
`bypassPermissions` still prompts for root/home directory removals and explicit `ask` rules.
|
||||
|
||||
## Model Falls Back Silently
|
||||
|
||||
If the model resolved from `CLAUDE_CODE_SUBAGENT_MODEL`, per-invocation parameter, or frontmatter `model` is excluded by an `availableModels` policy, the subagent silently falls back to the inherited model with no warning.
|
||||
|
||||
## Nesting Depth Limit
|
||||
|
||||
Nested subagents are supported up to depth 5 (fixed, not configurable). At depth 5 the Agent tool is withheld from the subagent. A fork cannot spawn another fork. Background subagent depth is fixed at spawn time — resuming from a shallower context does not grant additional depth.
|
||||
|
||||
## Explore and Plan Cannot Be Resumed
|
||||
|
||||
Explore and Plan are one-shot agents and return no agent ID. They cannot be resumed. For work that needs resumption, use the general-purpose subagent.
|
||||
|
||||
## CLAUDE.md Not Passed to Explore / Plan
|
||||
|
||||
The built-in Explore and Plan agents skip CLAUDE.md and git status to keep their context lean. To pass a project rule to these agents, restate it explicitly in the delegation prompt.
|
||||
|
||||
## MCP Restrictions Apply to Subagent Servers
|
||||
|
||||
Enterprise MCP policies (`--strict-mcp-config`, `allowedMcpServers`/`deniedMcpServers`) apply to servers declared in subagent frontmatter `mcpServers`. Blocked servers generate a warning. Exception: `--strict-mcp-config` does not filter inline servers passed via `--agents` or the Agent SDK `agents` option.
|
||||
|
||||
## Context Consumption from Parallel Subagents
|
||||
|
||||
Running many parallel subagents that each return large result summaries can rapidly consume main conversation context. Scope subagent instructions to return concise summaries, not full verbatim output.
|
||||
|
||||
## Fork Mode Caveats
|
||||
|
||||
Fork mode (`/fork`, `CLAUDE_CODE_FORK_SUBAGENT=1`) is experimental. Enabling it forces all subagent spawns to run in the background, not just forks.
|
||||
|
||||
## Tools Unavailable to All Subagents
|
||||
|
||||
These tools are never available to any subagent regardless of the `tools` frontmatter field:
|
||||
- `AskUserQuestion`
|
||||
- `EnterPlanMode`
|
||||
- `ExitPlanMode` (unless `permissionMode: plan`)
|
||||
- `ScheduleWakeup`
|
||||
- `WaitForMcpServers`
|
||||
Reference in New Issue
Block a user