12 ファイル変更 +523 -29
この更新の概要
モノレポや大規模コードベース向けの新しいガイド large-codebases が追加され、ディレクトリごとの設定パターンが詳しく解説されています。Agent SDKにおいてスラッシュコマンドが「コマンド」に名称変更され、新機能としての「スキル」へ移行が促されるようになりました。各クラウドプロバイダーの設定では、認証方式の都合により logout コマンドのみが無効化される仕様に変更されています。セキュリティガイドでは、git リポジトリが必須であることや診断ログの場所など、トラブルシューティング情報が大幅に拡充されました。
@@ -131,5 +131,6 @@ With provider and delivery mechanism chosen, move on to detailed configuration:
- [Server-managed settings](/en/server-managed-settings): deliver managed policy from the Claude admin console
- [Settings reference](/en/settings): every setting key, file location, and precedence rule
- [Monorepos and large repos](/en/large-codebases): per-directory configuration patterns for organizations deploying into a monorepo
- [Amazon Bedrock](/en/amazon-bedrock), [Google Vertex AI](/en/google-vertex-ai), [Microsoft Foundry](/en/microsoft-foundry): provider-specific deployment
- [Claude Enterprise Administrator Guide](https://claude.com/resources/tutorials/claude-enterprise-administrator-guide): SSO, SCIM, seat management, and rollout playbook
@@ -216,7 +216,7 @@ You can customize compaction behavior in several ways:
- **Summarization instructions in CLAUDE.md:** The compactor reads your CLAUDE.md like any other context, so you can include a section telling it what to preserve when summarizing. The section header is free-form (not a magic string); the compactor matches on intent.
- **`PreCompact` hook:** Run custom logic before compaction occurs, for example to archive the full transcript. The hook receives a `trigger` field (`manual` or `auto`). See [hooks](/en/agent-sdk/hooks).
- **Manual compaction:** Send `/compact` as a prompt string to trigger compaction on demand. (Slash commands sent this way are SDK inputs, not CLI-only shortcuts. See [slash commands in the SDK](/en/agent-sdk/slash-commands).)
- **Manual compaction:** Send `/compact` as a prompt string to trigger compaction on demand. Commands sent this way are SDK inputs, not CLI-only shortcuts. See [commands in the SDK](/en/agent-sdk/slash-commands).
Add a section to your project's CLAUDE.md telling the compactor what to preserve. The header name isn't special; use any clear label.
@@ -400,10 +400,10 @@ The SDK also supports Claude Code's filesystem-based configuration. With default
| Feature | Description | Location |
| - | - | - |
| [Skills](/en/agent-sdk/skills) | Specialized capabilities defined in Markdown | `.claude/skills/*/SKILL.md` |
| [Slash commands](/en/agent-sdk/slash-commands) | Custom commands for common tasks | `.claude/commands/*.md` |
| [Skills](/en/agent-sdk/skills) | Specialized capabilities Claude uses automatically or you invoke with `/name` | `.claude/skills/*/SKILL.md` |
| [Commands](/en/agent-sdk/slash-commands) | Custom commands in the legacy format. Use skills for new custom commands | `.claude/commands/*.md` |
| [Memory](/en/agent-sdk/modifying-system-prompts) | Project context and instructions | `CLAUDE.md` or `.claude/CLAUDE.md` |
| [Plugins](/en/agent-sdk/plugins) | Extend with custom commands, agents, and MCP servers | Programmatic via `plugins` option |
| [Plugins](/en/agent-sdk/plugins) | Extend with skills, agents, hooks, and MCP servers | Programmatic via `plugins` option |
## Compare the Agent SDK to other Claude tools
@@ -5,9 +5,9 @@ source: https://code.claude.com/docs/en/agent-sdk/plugins.md
# Plugins in the SDK
> Load custom plugins to extend Claude Code with commands, agents, skills, and hooks through the Agent SDK
> Load custom plugins to extend Claude Code with skills, agents, hooks, and MCP servers through the Agent SDK
Plugins allow you to extend Claude Code with custom functionality that can be shared across projects. Through the Agent SDK, you can programmatically load plugins from local directories to add custom slash commands, agents, skills, hooks, and MCP servers to your agent sessions.
Plugins allow you to extend Claude Code with custom functionality that can be shared across projects. Through the Agent SDK, you can programmatically load plugins from local directories to add skills, agents, hooks, and MCP servers to your agent sessions.
## What are plugins?
@@ -89,9 +89,13 @@ for await (const message of query({
console.log("Plugins:", message.plugins);
// Example: [{ name: "my-plugin", path: "./my-plugin" }]
// Check available commands from plugins
// Plugin skills appear with the plugin name as a prefix
console.log("Skills:", message.skills);
// Example: ["my-plugin:greet"]
// Plugin commands use the same prefix, and skills appear here too
console.log("Commands:", message.slash_commands);
// Example: ["compact", "context", "my-plugin:custom-command"]
// Example: ["compact", "context", "my-plugin:custom-command", "my-plugin:greet"]
}
}
```
@@ -112,16 +116,20 @@ async def main():
print("Plugins:", message.data.get("plugins"))
# Example: [{"name": "my-plugin", "path": "./my-plugin"}]
# Check available commands from plugins
# Plugin skills appear with the plugin name as a prefix
print("Skills:", message.data.get("skills"))
# Example: ["my-plugin:greet"]
# Plugin commands use the same prefix, and skills appear here too
print("Commands:", message.data.get("slash_commands"))
# Example: ["compact", "context", "my-plugin:custom-command"]
# Example: ["compact", "context", "my-plugin:custom-command", "my-plugin:greet"]
asyncio.run(main())
```
## Using plugin skills
Skills from plugins are automatically namespaced with the plugin name to avoid conflicts. When invoked as slash commands, the format is `plugin-name:skill-name`.
Skills from plugins are automatically namespaced with the plugin name to avoid conflicts. To invoke one directly, send `/plugin-name:skill-name` as the prompt.
```typescript TypeScript theme={null}
import { query } from "@anthropic-ai/claude-agent-sdk";
@@ -185,6 +193,7 @@ async function runWithPlugin() {
})) {
if (message.type === "system" && message.subtype === "init") {
console.log("Loaded plugins:", message.plugins);
console.log("Available skills:", message.skills);
console.log("Available commands:", message.slash_commands);
}
@@ -227,6 +236,7 @@ async def run_with_plugin():
):
if isinstance(message, SystemMessage) and message.subtype == "init":
print(f"Loaded plugins: {message.data.get('plugins')}")
print(f"Available skills: {message.data.get('skills')}")
print(f"Available commands: {message.data.get('slash_commands')}")
if isinstance(message, AssistantMessage):
@@ -306,9 +316,9 @@ If your plugin doesn't appear in the init message:
If plugin skills don't work:
1. **Use the namespace**: Plugin skills require the `plugin-name:skill-name` format when invoked as slash commands
2. **Check init message**: Verify the skill appears in `slash_commands` with the correct namespace
3. **Validate skill files**: Ensure each skill has a `SKILL.md` file in its own subdirectory under `skills/` (for example, `skills/my-skill/SKILL.md`)
1. **Use the namespace**: invoke plugin skills as `/plugin-name:skill-name`
2. **Check init message**: verify the skill appears in the `skills` list with the correct namespace
3. **Validate skill files**: ensure each skill has a `SKILL.md` file in its own subdirectory under `skills/`, for example `skills/my-skill/SKILL.md`
### Path resolution issues
@@ -322,6 +332,6 @@ If relative paths don't work:
- [Plugins](/en/plugins) - Complete plugin development guide
- [Plugins reference](/en/plugins-reference) - Technical specifications
- [Slash Commands](/en/agent-sdk/slash-commands) - Using slash commands in the SDK
- [Commands](/en/agent-sdk/slash-commands) - Using commands in the SDK
- [Subagents](/en/agent-sdk/subagents) - Working with specialized agents
- [Skills](/en/agent-sdk/skills) - Using Agent Skills
@@ -208,7 +208,7 @@ export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2
When enabling Bedrock for Claude Code, keep the following in mind:
* `AWS_REGION` is a required environment variable. Claude Code does not read from the `.aws` config file for this setting.
* When using Bedrock, the `/login` and `/logout` commands are disabled since authentication is handled through AWS credentials.
* When using Bedrock, the `/logout` command is unavailable since authentication is handled through AWS credentials.
* You can use settings files for environment variables like `AWS_PROFILE` that you don't want to leak to other processes. See [Settings](/en/settings) for more information.
### 4. Pin model versions
@@ -24,6 +24,8 @@ These are prompt patterns for everyday tasks like exploring unfamiliar code, deb
### Understand new codebases
For configuring Claude Code in a monorepo or large codebase, see [Monorepos and large repos](/en/large-codebases).
#### Get a quick codebase overview
Suppose you've just joined a new project and need to understand its structure quickly.
@@ -185,7 +185,7 @@ export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1
Most model versions have a corresponding `VERTEX_REGION_CLAUDE_*` variable. See the [Environment variables reference](/en/env-vars) for the full list. Check [Vertex Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) to determine which models support global endpoints versus regional only.
[Prompt caching](/en/prompt-caching) is enabled automatically. To disable it, set `DISABLE_PROMPT_CACHING=1`. To request a 1-hour cache TTL instead of the 5-minute default, set `ENABLE_PROMPT_CACHING_1H=1`; cache writes with a 1-hour TTL are billed at a higher rate. For heightened rate limits, contact Google Cloud support. When using Vertex AI, the `/login` and `/logout` commands are disabled since authentication is handled through Google Cloud credentials.
[Prompt caching](/en/prompt-caching) is enabled automatically. To disable it, set `DISABLE_PROMPT_CACHING=1`. To request a 1-hour cache TTL instead of the 5-minute default, set `ENABLE_PROMPT_CACHING_1H=1`; cache writes with a 1-hour TTL are billed at a higher rate. For heightened rate limits, contact Google Cloud support. When using Vertex AI, the `/logout` command is unavailable since authentication is handled through Google Cloud credentials.
Claude Code disables [MCP tool search](/en/mcp#scale-with-mcp-tool-search) by default on Vertex AI, so MCP tool definitions load upfront. Vertex AI supports tool search for Claude Sonnet 4.5 and later and Claude Opus 4.5 and later. Set `ENABLE_TOOL_SEARCH=true` to enable it on those models. Earlier models on Vertex AI do not accept the required beta header, and requests fail if you enable tool search with them.
@@ -308,7 +308,7 @@ claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/ant
### Scope hierarchy and precedence
When the same server is defined in more than one place, Claude Code connects to it once, using the definition from the highest-precedence source:
When the same server is defined in more than one place, Claude Code connects to it once, using the definition from the highest-precedence source. The entire server entry from that source is used; fields are not merged across scopes.
1. Local scope
2. Project scope
@@ -21,7 +21,7 @@ This page covers how to:
## CLAUDE.md vs auto memory
Claude Code has two complementary memory systems. Both are loaded at the start of every conversation. Claude treats them as context, not enforced configuration. The more specific and concise your instructions, the more consistently Claude follows them.
Claude Code has two complementary memory systems. Both are loaded at the start of every conversation. Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a [PreToolUse hook](/en/hooks-guide) instead. The more specific and concise your instructions, the more consistently Claude follows them.
| | CLAUDE.md files | Auto memory |
| :- | :- | :- |
@@ -147,7 +147,7 @@ All discovered files are concatenated into context rather than overriding each o
Claude also discovers `CLAUDE.md` and `CLAUDE.local.md` files in subdirectories under your current working directory. Instead of loading them at launch, they are included when Claude reads files in those subdirectories.
If you work in a large monorepo where other teams' CLAUDE.md files get picked up, use [`claudeMdExcludes`](#exclude-specific-claude-md-files) to skip them.
If you work in a large monorepo where other teams' CLAUDE.md files get picked up, use [`claudeMdExcludes`](#exclude-specific-claude-md-files) to skip them. For the full layout of root and per-directory CLAUDE.md files and rules, see [Monorepos and large repos](/en/large-codebases).
Block-level HTML comments (`<!-- maintainer notes -->`) in CLAUDE.md files are stripped before the content is injected into Claude's context. Use them to leave notes for human maintainers without spending context tokens on them. Comments inside code blocks are preserved. When you open a CLAUDE.md file directly with the Read tool, comments remain visible.
@@ -115,7 +115,7 @@ az login
```
<Note>
When using Microsoft Foundry, the `/login` and `/logout` commands are disabled since authentication is handled through Azure credentials.
When using Microsoft Foundry, the `/logout` command is unavailable since authentication is handled through Azure credentials.
</Note>
### 3. Configure Claude Code
@@ -17,6 +17,9 @@ The plugin is the in-session companion to [Code Review](/en/code-review), which
- Claude Code CLI version 2.1.144 or later
- Python 3.8 or later on your `PATH`. The plugin tries `python3`, `python`, and `py -3` in that order
- A git repository for the directory you work in. The end-of-turn and commit reviews diff against git state and skip silently outside a repository. The per-edit pattern check works anywhere
On first run the plugin creates a virtual environment under `~/.claude/security/` and installs the Claude Agent SDK into it, which requires `pip` and network access. If that install fails, the commit review falls back to a single-shot review instead of the agentic one. On Windows the virtual environment step is skipped, so the agentic commit review runs only if `claude-agent-sdk` is already importable and otherwise falls back the same way.
## Install the plugin
@@ -26,14 +29,14 @@ In a Claude Code session, install from the [official Anthropic marketplace](/en/
/plugin install security-guidance@claude-plugins-official
```
Then activate it in the current session:
The install prompts for a scope. Choose user scope to write the plugin to your user settings, so it loads in every new local session you start on this machine. If Claude Code reports that the marketplace is not found, run `/plugin marketplace add anthropics/claude-plugins-official` first, then retry the install.
Then activate it in the current session with `/reload-plugins`, which applies pending plugin changes without a restart:
```text
/reload-plugins
```
The install writes to your user settings, so the plugin loads in every new local session you start on this machine. Sessions that were already running need `/reload-plugins` to load it.
### Enable in cloud sessions and shared repositories
User-scoped plugins do not carry into [Claude Code on the web](/en/claude-code-on-the-web), because those sessions run on Anthropic infrastructure rather than your machine. To enable the plugin there, or to turn it on for everyone who clones a repository, declare it in the project's checked-in settings:
@@ -91,7 +94,7 @@ You see both the finding and Claude's resolution directly in your session. The r
When Claude runs `git commit` or `git push` through its Bash tool, the plugin runs a deeper agentic review of the change in the background. This review reads surrounding code, including callers, sanitizers, and related files, to decide whether a finding is real before reporting it. The extra context keeps false positives low on patterns that look dangerous in isolation but are safe in your codebase.
This layer fires only on commits and pushes Claude makes through its Bash tool. Commits you run from your own shell, including the `!` shell escape inside a session, are not reviewed. Commit and push reviews are capped at 20 per rolling hour.
This layer fires only on commits and pushes Claude makes through its Bash tool. Commits you run from your own shell, including the `!` shell escape inside a session, are not reviewed. Commit and push reviews are capped at 20 per rolling hour. If the commit review's findings duplicate what the end-of-turn review already reported, Claude is not re-prompted, so a clean commit produces no visible output from this layer.
### Review independence and limits
@@ -130,7 +133,7 @@ patterns:
reminder: "Hardcoded API key prefix. Load credentials from the secret manager."
- rule_name: tenant_unfiltered_query
regex: "\\.objects\\.all\\(\\)"
paths: ["src/tenants/**"]
paths: ["**/src/tenants/**"]
reminder: "Multi-tenant code must filter by org_id."
```
@@ -140,8 +143,8 @@ patterns:
| `reminder` | string | Warning text appended to Claude's context, capped at 1 KB |
| `regex` | string | Python regex matched against the edited content |
| `substrings` | list | Literal substrings; provide this or `regex` |
| `paths` | list | Optional glob patterns; the rule applies only to matching files |
| `exclude_paths` | list | Optional glob patterns to skip |
| `paths` | list | Optional glob patterns; the rule applies only to matching files. Globs match against the full file path, so prefix project-relative patterns with `**/` |
| `exclude_paths` | list | Optional glob patterns to skip; same matching as `paths` |
The plugin also reads `.claude/security-patterns.yml` and `.claude/security-patterns.json` with the same schema. JSON works on any Python install. The YAML forms require PyYAML to be importable, which the plugin does not install for you. The plugin loads up to 50 custom rules and skips regexes that look prone to catastrophic backtracking.
@@ -159,7 +162,7 @@ The plugin loads all locations that exist and concatenates them, with a combined
## Usage cost
The [per-edit pattern check](#on-each-file-edit) makes no model call and adds no cost. The [end-of-turn](#at-the-end-of-each-turn) and [commit](#on-each-commit-or-push-claude-makes) reviews each spend additional model usage that counts toward your [usage](/en/costs) like any other Claude request. The commit review is agentic and may take several model turns per commit. The increase scales with how often Claude edits files and commits in the session.
The [per-edit pattern check](#on-each-file-edit) makes no model call and adds no cost. The [end-of-turn](#at-the-end-of-each-turn) and [commit](#on-each-commit-or-push-claude-makes) reviews each spend additional model usage that counts toward your [usage](/en/costs) like any other Claude request. The commit review is agentic and may take several model turns per commit, capped at 20 reviews per rolling hour. Expect roughly one review call per turn that changes files and one deeper review per commit, both subject to the caps above.
Both model-backed reviews use Claude Opus 4.7 by default. Set `SECURITY_REVIEW_MODEL` to choose a different model for the end-of-turn review and `SG_AGENTIC_MODEL` for the commit review.
@@ -218,6 +221,16 @@ The plugin is one layer in a defense-in-depth approach. It catches issues earlie
Each later stage catches what earlier ones miss. The plugin's value is reducing the volume that reaches them, not eliminating the need for them.
## Troubleshooting
The plugin writes runtime diagnostics to `~/.claude/security/log.txt`. Check there first if reviews are not appearing.
Common reasons a review layer skips without a message in the conversation:
- The directory is not a git repository: the end-of-turn and commit reviews require git state and skip outside a repository
- The session has no Anthropic authentication: the model-backed reviews skip and only the per-edit pattern check runs
- A `security-patterns.yaml` file is present but PyYAML is not importable: the file is ignored. Use `security-patterns.json` instead
## Related resources
To go deeper on the pieces this page touches: