---
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.

## `commands` vs `skills`

The manifest supports two fields that both register slash-command-style invocations, but they use different formats and have different capabilities:

| Feature | `skills` | `commands` |
|---|---|---|
| Format | `skills/<name>/SKILL.md` directory per skill | Single `.md` files listed as paths |
| Invocation | `/plugin-name:skill-name` (namespaced) | `/command-name` (global, no namespace) |
| Autonomous use by Claude | Yes — Claude can invoke without an explicit `/` command | No — only user-typed `/` triggers it |
| Status | Recommended | Legacy |

The `commands` field is the **legacy** slash-command format. It accepts an array of paths to individual Markdown files:

```json
"commands": ["./custom/commands/special.md"]
```

Each file is a single command definition equivalent to a `.md` file in `.claude/commands/`. The command is invoked as `/filename` (without the extension).

The `skills` field is the recommended replacement. A skill directory (`skills/<name>/SKILL.md`) provides the same `/name` invocation plus autonomous invocation by Claude (Claude can call the skill proactively without the user typing a `/` command). Skills also support bundling supporting files alongside `SKILL.md`.

**Practical rule**: use `skills/` for new plugin content. The `commands` field exists for backward compatibility when porting legacy `.claude/commands/` files into a plugin. The CLI supports both formats.

## 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.