plugins-reference.md +0 −1645 deleted
File Deleted View Diff
1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# Справочник по plugins
6
7> Полный технический справочник по системе plugins Claude Code, включая схемы, команды CLI и спецификации компонентов.
8
9<Tip>
10 Ищете способ установить plugins? См. [Обнаружение и установка plugins](/docs/ru/discover-plugins). Для создания plugins см. [Plugins](/docs/ru/plugins). Для распространения plugins см. [Plugin marketplaces](/docs/ru/plugin-marketplaces).
11</Tip>
12
13**Plugin** — это самостоятельный каталог компонентов, который расширяет Claude Code пользовательской функциональностью. Компоненты plugin включают skills, agents, hooks, MCP servers, LSP servers и monitors.
14
15<h2 id="plugin-components-reference">
16 Справочник компонентов плагинов
17</h2>
18
19<h3 id="skills">
20 Skills
21</h3>
22
23Плагины добавляют skills в Claude Code, создавая сочетания `/name`, которые вы или Claude можете вызвать.
24
25**Расположение**: директория `skills/` или `commands/` в корне плагина, или один файл `SKILL.md` в корне плагина
26
27**Формат файла**: Skills — это директории с `SKILL.md`; commands — это простые файлы markdown
28
29**Структура skill**:
30
31```text theme={null}
32skills/
33├── pdf-processor/
34│ ├── SKILL.md
35│ ├── reference.md (опционально)
36│ └── scripts/ (опционально)
37└── code-reviewer/
38 └── SKILL.md
39```
40
41Skills и commands автоматически обнаруживаются при установке плагина.
42
43Если плагин не имеет директории `skills/` и не имеет поля манифеста `skills`, то `SKILL.md` в корне плагина загружается как один skill. Установите поле frontmatter `name` для управления именем вызова skill. Без него Claude Code возвращается к имени директории установки. Для плагина [скопированного в кэш](#plugin-caching-and-file-resolution), это имя — строка версии, которая меняется при каждом обновлении. Для плагинов, которые поставляют более одного skill, используйте макет директории `skills/`, показанный выше.
44
45В skills и commands плагинов логические поля frontmatter, такие как `disable-model-invocation`, принимают `yes`, `no`, `on`, `off`, `1` и `0` в любом регистре букв, в дополнение к `true` и `false`. До версии v2.1.218 Claude Code распознавал только `true` и `false`.
46
47Для полной информации см. [Skills](/docs/ru/skills).
48
49<h3 id="agents">
50 Agents
51</h3>
52
53Плагины могут предоставлять специализированные подагенты для конкретных задач, которые Claude может автоматически вызывать при необходимости.
54
55**Расположение**: директория `agents/` в корне плагина
56
57**Формат файла**: Файлы markdown, описывающие возможности агента
58
59**Структура агента**:
60
61```markdown theme={null}
62name: agent-name
63description: What this agent specializes in and when Claude should invoke it
64model: sonnet
65effort: medium
66maxTurns: 20
67disallowedTools: Write, Edit
68
69Detailed system prompt for the agent describing its role, expertise, and behavior.
70```
71
72<h4 id="plugin-agent-frontmatter">
73 Frontmatter агента плагина
74</h4>
75
76Файл агента плагина использует те же [поля frontmatter, что и файл подагента](/docs/ru/sub-agents#supported-frontmatter-fields), за исключением того, что Claude Code учитывает только некоторые из них, когда агент поступает из плагина:
77
78* **Поддерживаемые**: `name`, `description`, `model`, `effort`, `maxTurns`, `tools`, `disallowedTools`, `skills`, `memory`, `background`, `omitClaudeMd`, `isolation`, `color` и `experimental`. Единственное допустимое значение `isolation` — это `"worktree"`.
79* **Не поддерживаемые по соображениям безопасности**: `hooks`, `mcpServers` и `permissionMode`. Claude Code игнорирует их при загрузке агента из плагина. Чтобы их использовать, скопируйте файл агента в `.claude/agents/` или `~/.claude/agents/`.
80* **Не поддерживаемые**: `initialPrompt`.
81
82Вы можете поместить файлы агента плагина в подпапки `agents/`. Claude Code [загружает их рекурсивно](/docs/ru/sub-agents#choose-the-subagent-scope) и объединяет имя плагина, каждое имя подпапки и имя файла с двоеточиями для формирования scoped имени агента. Например, `agents/review/security.md` в плагине с именем `my-plugin` загружается как `my-plugin:review:security`. Два параметра изменяют это имя:
83
84* Frontmatter `name`: он заменяет только имя файла, поэтому `name: audit` в `agents/review/security.md` загружается как `my-plugin:review:audit`
85* Поле манифеста [`agents`](#component-path-fields): файл, который вы там указываете, загружается без имён подпапок, поэтому `"agents": "./custom/review/security.md"` загружается как `my-plugin:security`
86
87Claude Code загружает агента плагина даже когда его frontmatter не имеет `name` или не анализируется:
88
89* Нет `name`: Claude Code называет агента по имени файла, поэтому `agents/reviewer.md` в плагине с именем `my-plugin` загружается как `my-plugin:reviewer`
90* Frontmatter, который не анализируется: Claude Code называет агента по имени файла, использует `Agent from my-plugin plugin` в качестве его описания и игнорирует каждое поле в файле
91
92В отличие от этого, Claude Code пропускает файл проекта, пользователя или управляемого агента, frontmatter которого не имеет `name` или не анализируется.
93
94Чтобы найти файлы в директории `agents/` плагина по умолчанию, frontmatter которых не анализируется, запустите `claude plugin validate`. Путь, который вы передаёте, зависит от того, имеет ли плагин манифест, и оба примера используют `./my-plugin` в качестве директории плагина:
95
96* Плагин с манифестом: `claude plugin validate ./my-plugin`
97* Плагин без манифеста: `claude plugin validate ./my-plugin/agents`. Требует Claude Code v2.1.233 или позже.
98
99Агенты появляются в [@-mention typeahead](/docs/ru/sub-agents#invoke-subagents-explicitly) под их scoped именем, таким как `my-plugin:code-reviewer`, после включения плагина.
100
101Для полной информации см. [Subagents](/docs/ru/sub-agents).
102
103<h3 id="hooks">
104 Hooks
105</h3>
106
107Плагины могут предоставлять обработчики событий, которые автоматически реагируют на события Claude Code.
108
109**Расположение**: `hooks/hooks.json` в корне плагина, или встроенный в plugin.json
110
111**Формат**: JSON конфигурация с матчерами событий и действиями
112
113`hooks/hooks.json` может содержать ключ верхнего уровня `$schema`, который указывает URL JSON Schema для автодополнения и валидации редактора. Claude Code игнорирует ключ при загрузке.
114
115**Конфигурация hook**:
116
117```json theme={null}
118{
119 "hooks": {
120 "PostToolUse": [
121 {
122 "matcher": "Write|Edit",
123 "hooks": [
124 {
125 "type": "command",
126 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format-code.sh"
127 }
128 ]
129 }
130 ]
131 }
132}
133```
134
135Hooks плагинов реагируют на те же события жизненного цикла, что и [определённые пользователем hooks](/docs/ru/hooks):
136
137| Событие | Когда оно срабатывает |
138| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
139| `SessionStart` | Когда сеанс начинается или возобновляется |
140| `Setup` | Когда вы запускаете Claude Code с `--init-only`, или с `--init` или `--maintenance` в режиме `-p`. Для одноразовой подготовки в CI или скриптах |
141| `UserPromptSubmit` | Когда вы отправляете запрос, прежде чем Claude его обработает |
142| `UserPromptExpansion` | Когда команда, введённая пользователем, расширяется в запрос, прежде чем она достигнет Claude. Может заблокировать расширение |
143| `PreToolUse` | Перед выполнением вызова инструмента. Может заблокировать его |
144| `PermissionRequest` | Когда вызов инструмента требует решения о разрешении |
145| `PermissionDenied` | Когда автоматический режим отклоняет вызов инструмента, включая отклонения без вердикта классификатора. Используйте JSON `hookSpecificOutput.retry: true`, чтобы сообщить модели, что она может повторить попытку отклонённого вызова инструмента. Claude Code игнорирует `retry`, когда классификатор не выдал вердикт |
146| `PostToolUse` | После успешного выполнения вызова инструмента |
147| `PostToolUseFailure` | После неудачного выполнения вызова инструмента |
148| `PostToolBatch` | После разрешения полного пакета параллельных вызовов инструментов, перед следующим вызовом модели |
149| `Notification` | Когда Claude Code отправляет уведомление |
150| `MessageDisplay` | Во время отображения текста сообщения помощника |
151| `SubagentStart` | Когда порождается подагент |
152| `SubagentStop` | Когда подагент завершает работу |
153| `TaskCreated` | Когда задача создаётся через `TaskCreate` |
154| `TaskCompleted` | Когда задача отмечается как завершённая |
155| `Stop` | Когда Claude завершает ответ |
156| `StopFailure` | Когда ход завершается из-за ошибки API |
157| `TeammateIdle` | Когда товарищ по команде [команды агентов](/docs/ru/agent-teams) собирается перейти в режим ожидания |
158| `InstructionsLoaded` | Когда файл CLAUDE.md или `.claude/rules/*.md` загружается в контекст. Срабатывает при запуске сеанса и когда файлы ленивой загрузки загружаются во время сеанса |
159| `ConfigChange` | Когда файл конфигурации изменяется во время сеанса |
160| `CwdChanged` | Когда рабочий каталог изменяется, например когда Claude выполняет команду `cd`. Полезно для реактивного управления окружением с помощью инструментов, таких как direnv |
161| `DirectoryAdded` | Когда рабочий каталог добавляется в середине сеанса через `/add-dir` или запрос управления SDK `register_repo_root` |
162| `FileChanged` | Когда наблюдаемый файл изменяется на диске. Поле `matcher` указывает, какие имена файлов отслеживать |
163| `WorktreeCreate` | Когда worktree создаётся через `--worktree`, `isolation: "worktree"`, или для фонового сеанса. Заменяет поведение git по умолчанию |
164| `WorktreeRemove` | Когда worktree удаляется при выходе из сеанса, когда подагент завершает работу, или когда вы удаляете фоновый сеанс |
165| `PreCompact` | Перед компактизацией контекста |
166| `PostCompact` | После завершения компактизации контекста |
167| `PreModelSwitch` | Перед тем как Claude Code применяет переключение модели, которое вы или клиент запросили. Может заблокировать переключение |
168| `PostModelSwitch` | После изменения модели сеанса, включая изменения, которые Claude Code делает самостоятельно, такие как восстановление модели при возобновлении сеанса |
169| `Elicitation` | Когда сервер MCP запрашивает ввод пользователя во время вызова инструмента |
170| `ElicitationResult` | После того как пользователь отвечает на запрос MCP, перед отправкой ответа обратно на сервер |
171| `SessionEnd` | Когда сеанс завершается |
172
173**Типы hooks**:
174
175* `command`: выполнение shell команд или скриптов
176* `http`: отправка JSON события как POST запроса на URL
177* `mcp_tool`: вызов инструмента на настроенном [MCP сервере](/docs/ru/mcp)
178* `prompt`: оценка prompt с LLM (использует заполнитель `$ARGUMENTS` для контекста)
179* `agent`: запуск агентного верификатора с инструментами для сложных задач верификации
180
181Hooks, которые нацелены на собственный [bundled MCP сервер](#mcp-servers) плагина, должны использовать его scoped имена. Матчеры инструментов и поля `if` принимают scoped имя инструмента `mcp__plugin_<plugin-name>_<server-name>__<tool>`, и поле `server` hook `mcp_tool` принимает `plugin:<plugin-name>:<server-name>`. Матчер, написанный для простого ключа сервера, никогда не срабатывает. См. [Match MCP tools](/docs/ru/hooks#match-mcp-tools) и [Plugin-provided MCP servers](/docs/ru/mcp#plugin-provided-mcp-servers).
182
183<h3 id="mcp-servers">
184 MCP servers
185</h3>
186
187Плагины могут включать серверы Model Context Protocol (MCP) для подключения Claude Code с внешними инструментами и сервисами.
188
189**Расположение**: `.mcp.json` в корне плагина, или встроенный в plugin.json
190
191**Формат**: Стандартная конфигурация MCP сервера
192
193**Конфигурация MCP сервера**:
194
195```json theme={null}
196{
197 "mcpServers": {
198 "plugin-database": {
199 "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
200 "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
201 "env": {
202 "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
203 }
204 },
205 "plugin-api-client": {
206 "command": "npx",
207 "args": ["@company/mcp-server", "--plugin-mode"]
208 }
209 }
210}
211```
212
213**Поведение интеграции**:
214
215* Серверы MCP плагинов запускаются автоматически при включении плагина
216* Серверы появляются как стандартные MCP инструменты в наборе инструментов Claude
217* Серверы плагинов могут быть настроены независимо от пользовательских MCP серверов
218* Если вы запустите [`/reload-plugins`](/docs/ru/discover-plugins#apply-plugin-changes-without-restarting) в середине сеанса, Claude Code сохраняет живые соединения серверов, конфигурация которых не изменилась
219
220<h3 id="lsp-servers">
221 LSP servers
222</h3>
223
224<Tip>
225 Ищете использование LSP плагинов? Установите их из официального marketplace: поищите "lsp" на вкладке Discover `/plugin`. Этот раздел документирует, как создавать LSP плагины для языков, не охватываемых официальным marketplace.
226</Tip>
227
228Плагины могут предоставлять серверы [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) для предоставления Claude [real-time code intelligence](/docs/ru/discover-plugins#code-intelligence) при работе с вашей кодовой базой.
229
230**Расположение**: `.lsp.json` в корне плагина, или встроенный в `plugin.json`
231
232**Формат**: JSON конфигурация, отображающая имена языковых серверов на их конфигурации
233
234**Формат файла `.lsp.json`**:
235
236```json theme={null}
237{
238 "go": {
239 "command": "gopls",
240 "args": ["serve"],
241 "extensionToLanguage": {
242 ".go": "go"
243 }
244 }
245}
246```
247
248**Встроенный в `plugin.json`**:
249
250```json theme={null}
251{
252 "name": "my-plugin",
253 "lspServers": {
254 "go": {
255 "command": "gopls",
256 "args": ["serve"],
257 "extensionToLanguage": {
258 ".go": "go"
259 }
260 }
261 }
262}
263```
264
265**Обязательные поля:**
266
267| Поле | Описание |
268| :-------------------- | :---------------------------------------------------- |
269| `command` | Бинарный файл LSP для выполнения (должен быть в PATH) |
270| `extensionToLanguage` | Отображает расширения файлов на идентификаторы языков |
271
272**Опциональные поля:**
273
274| Поле | Описание |
275| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
276| `args` | Аргументы командной строки для LSP сервера |
277| `transport` | Транспорт коммуникации: `stdio` (по умолчанию) или `socket`. Claude Code принимает `socket`, но запускает каждый сервер через stdio, поэтому правила протокола stdout применяются ко всем серверам |
278| `env` | Переменные окружения для установки при запуске сервера |
279| `initializationOptions` | Опции, передаваемые серверу при инициализации |
280| `settings` | Параметры, передаваемые через `workspace/didChangeConfiguration` |
281| `workspaceFolder` | Путь папки рабочего пространства для сервера |
282| `startupTimeout` | Максимальное время ожидания запуска сервера (миллисекунды) |
283| `shutdownTimeout` | Максимальное время ожидания корректного завершения (миллисекунды). Когда истекает время ожидания, Claude Code завершает процесс сервера. Если не установлено, время ожидания не применяется |
284| `restartOnCrash` | Следует ли перезапустить сервер после его сбоя. По умолчанию `true`. Установите `false`, чтобы оставить упавший сервер остановленным вместо его перезапуска |
285| `maxRestarts` | Максимальное количество попыток перезапуска перед отказом |
286| `diagnostics` | Следует ли отправлять диагностику в контекст Claude после редактирования (по умолчанию `true`). Установите `false`, чтобы сохранить навигацию по коду, но подавить автоматическое внедрение диагностики |
287
288`restartOnCrash` и `shutdownTimeout` требуют Claude Code v2.1.205 или позже. До версии v2.1.205 схема конфигурации принимала обе опции, но установка любой из них вызывала пропуск этого LSP сервера Claude Code при запуске, с причиной видимой только в выводе `claude --debug`.
289
290**Несколько серверов для одного расширения**: когда более одного включённого LSP сервера объявляет одно и то же расширение файла в `extensionToLanguage`, независимо от того, поступают ли серверы из одного плагина или из разных плагинов, первый зарегистрированный сервер обрабатывает файлы с этим расширением, а остальные никогда не запускаются. Интерфейс `/plugin` показывает предупреждение, называющее плагин, чей сервер активен.
291
292**Серверы, которые не инициализируются**: Claude Code пропускает сервер, конфигурация которого недействительна, например отсутствует `command` или `extensionToLanguage`, и остальные настроенные серверы всё ещё запускаются. Запустите `claude --debug`, чтобы увидеть, почему сервер был пропущен.
293
294Пропущенный сервер не заявляет свои расширения файлов, поэтому другой действительный сервер, который объявляет то же расширение, из того же или другого плагина, всё ещё обрабатывает эти файлы.
295
296**Отправляйте вывод логов в stderr, а не stdout**: Claude Code читает stdout сервера только как сообщения протокола и принимает заголовки сообщений до 64 КиБ и тело сообщения до 32 МиБ. Claude Code отключает сервер, который превышает любой лимит или записывает вывод, не являющийся протоколом, в stdout, и считает отключение сбоем для `restartOnCrash` и `maxRestarts`. Когда вы запускаете с `--debug`, Claude Code записывает ошибку, называющую причину, в журнал отладки.
297
298<Warning>
299 **Вы должны установить бинарный файл языкового сервера отдельно.** LSP плагины настраивают, как Claude Code подключается к языковому серверу, но они не включают сам сервер. Если вы видите `Executable not found in $PATH` на вкладке Errors `/plugin`, установите требуемый бинарный файл для вашего языка.
300</Warning>
301
302**Доступные LSP плагины:**
303
304| Плагин | Языковой сервер | Команда установки |
305| :------------------ | :------------------------- | :----------------------------------------------------------------------------------------- |
306| `pyright-lsp` | Pyright (Python) | `pip install pyright` или `npm install -g pyright` |
307| `typescript-lsp` | TypeScript Language Server | `npm install -g typescript-language-server typescript` |
308| `rust-analyzer-lsp` | rust-analyzer | [See rust-analyzer installation](https://rust-analyzer.github.io/manual.html#installation) |
309
310Сначала установите языковой сервер, затем установите плагин из marketplace.
311
312<h3 id="monitors">
313 Monitors
314</h3>
315
316Плагины могут объявлять фоновые мониторы, которые Claude Code автоматически запускает при активном плагине. Каждый монитор запускает shell команду на протяжении всего сеанса и доставляет каждую строку stdout Claude как уведомление, поэтому Claude может реагировать на записи логов, изменения статуса или опрашиваемые события без необходимости просить запустить наблюдение самостоятельно.
317
318Мониторы плагинов используют тот же механизм, что и [Monitor tool](/docs/ru/tools-reference#monitor-tool), и разделяют его ограничения доступности. Они запускаются только в интерактивных сеансах CLI, запускаются без песочницы на том же уровне доверия, что и [hooks](#hooks), и пропускаются на хостах, где Monitor tool недоступен.
319
320**Расположение**: `monitors/monitors.json` в корне плагина, или встроенный в `plugin.json`
321
322**Формат**: JSON массив записей монитора
323
324Следующий `monitors/monitors.json` отслеживает конечную точку статуса развёртывания и локальный журнал ошибок:
325
326```json theme={null}
327[
328 {
329 "name": "deploy-status",
330 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
331 "description": "Deployment status changes"
332 },
333 {
334 "name": "error-log",
335 "command": "tail -F ./logs/error.log",
336 "description": "Application error log",
337 "when": "on-skill-invoke:debug"
338 }
339]
340```
341
342Чтобы объявить мониторы встроенным образом, установите `experimental.monitors` в `plugin.json` на тот же массив. Чтобы загрузить из пути, отличного от пути по умолчанию, установите `experimental.monitors` на строку относительного пути, такую как `"./config/monitors.json"`. Мониторы — это [experimental component](#experimental-components).
343
344**Обязательные поля:**
345
346| Поле | Описание |
347| :------------ | :------------------------------------------------------------------------------------------------------------------------------------- |
348| `name` | Идентификатор, уникальный в пределах плагина. Предотвращает дублирование процессов при перезагрузке плагина или повторном вызове skill |
349| `command` | Shell команда, запускаемая как постоянный фоновый процесс в рабочей директории сеанса |
350| `description` | Краткое резюме того, что отслеживается. Показывается в панели задач и в сводках уведомлений |
351
352**Опциональные поля:**
353
354| Поле | Описание |
355| :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
356| `when` | Управляет тем, когда запускается монитор. `"always"` запускает его при запуске сеанса и при перезагрузке плагина и является значением по умолчанию. `"on-skill-invoke:<skill-name>"` запускает его в первый раз, когда именованный skill в этом плагине отправляется |
357
358Значение `command` поддерживает [path substitutions](#environment-variables) `${CLAUDE_PLUGIN_ROOT}`, `${CLAUDE_PLUGIN_DATA}` и `${CLAUDE_PROJECT_DIR}`, плюс любой `${ENV_VAR}` из окружения. Добавьте префикс команды с `cd "${CLAUDE_PLUGIN_ROOT}" && `, если скрипт должен запускаться из собственной директории плагина.
359
360Команда монитора `command` не может ссылаться на значения [`${user_config.*}`](#user-configuration). Команда запускается через shell, поэтому Claude Code отклоняет монитор с [error](/docs/ru/errors#plugin-command-references-user-config) вместо подстановки значения. Процессы мониторов не получают переменные окружения `CLAUDE_PLUGIN_OPTION_<KEY>`, поэтому скрипт монитора должен читать значение из файла конфигурации, который он владеет.
361
362Если вы отключите плагин в середине сеанса, Claude Code не останавливает мониторы, которые уже запущены; они останавливаются при завершении сеанса.
363
364<h3 id="themes">
365 Themes
366</h3>
367
368Плагины могут поставлять цветовые темы, которые появляются в `/theme` наряду с встроенными предустановками и локальными темами пользователя. Тема — это JSON файл в `themes/` с предустановкой `base` и разреженной картой `overrides` цветовых токенов. Темы — это [experimental component](#experimental-components).
369
370```json theme={null}
371{
372 "name": "Dracula",
373 "base": "dark",
374 "overrides": {
375 "claude": "#bd93f9",
376 "error": "#ff5555",
377 "success": "#50fa7b"
378 }
379}
380```
381
382Когда пользователь выбирает тему плагина, Claude Code сохраняет `custom:<plugin-name>:<slug>` в его конфигурации. Темы плагинов доступны только для чтения: когда пользователь нажимает `Ctrl+E` на одной из них в `/theme`, Claude Code копирует её в `~/.claude/themes/`, чтобы они могли редактировать копию.
383
384***
385
386<h2 id="plugin-installation-scopes">
387 Области установки плагинов
388</h2>
389
390При установке плагина вы выбираете **область**, которая определяет, где плагин доступен и кто еще может его использовать:
391
392| Область | Файл параметров | Вариант использования |
393| :-------- | :--------------------------------------- | :------------------------------------------------------------------------------------------------------- |
394| `user` | `~/.claude/settings.json` | Личные плагины, доступные во всех проектах (по умолчанию) |
395| `project` | `.claude/settings.json` | Командные плагины, общие через систему контроля версий |
396| `local` | `.claude/settings.local.json` | Плагины, специфичные для проекта, игнорируются в .gitignore, когда Claude Code сохраняет параметр в него |
397| `managed` | [Managed settings](/docs/ru/managed-settings) | Управляемые плагины (только для чтения, только обновление) |
398
399Плагины используют ту же систему областей, что и другие конфигурации Claude Code. Инструкции по установке и флаги области см. в разделе [Install plugins](/docs/ru/discover-plugins#install-plugins). Полное объяснение областей см. в разделе [Configuration scopes](/docs/ru/settings#where-settings-live).
400
401***
402
403<h2 id="skills-directory-plugins">
404 Плагины каталога skills
405</h2>
406
407Любая папка в каталоге skills, содержащая манифест `.claude-plugin/plugin.json`, загружается как плагин с именем `<name>@skills-dir` в следующем сеансе без marketplace и без этапа установки. Создайте его с помощью [`plugin init`](#plugin-init). В отличие от скопированной установки из marketplace, плагин обнаруживается на месте, а не копируется в кэш плагинов.
408
409Дерево каталога skills поддерживает три различных вещи:
410
411| Что у вас есть | Что это такое |
412| :-------------------------------------------- | :------------------------------------------------------------------------------------------------------ |
413| `<skills-dir>/foo/SKILL.md` без манифеста | Обычный [skill](/docs/ru/skills) с именем `foo` |
414| `<skills-dir>/foo/.claude-plugin/plugin.json` | Плагин `foo@skills-dir`, который может содержать свои собственные skills, agents, hooks и многое другое |
415| `<plugin>/skills/bar/SKILL.md` | Skill `bar`, упакованный внутри плагина |
416
417<h3 id="choose-where-the-plugin-loads-from">
418 Выберите, откуда загружается плагин
419</h3>
420
421| Каталог skills | Область | Загружает |
422| :---------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------- |
423| `~/.claude/skills/` | личный | В каждом проекте, так как это расположение только ваше |
424| `<cwd>/.claude/skills/` | проект | Только после того, как вы примете диалог [доверия рабочей области](/docs/ru/permissions#what-runs-before-you-trust-a-folder) для этой папки |
425
426Плагин с областью проекта проверяется в репозитории и доступен каждому сотруднику, который его клонирует. Поскольку это содержимое поступает из репозитория, а не от вас, оно загружается только после того же шлюза доверия, который управляет правилами разрешения проекта в `.claude/settings.json`, поэтому доверие к родительской папке или запуск с `-p` недостаточно, и компоненты, которые выполняют код, имеют дополнительные ограничения:
427
428* MCP серверы, которые он объявляет, проходят через [то же одобрение для каждого сервера](/docs/ru/mcp), что и проект `.mcp.json`
429* LSP серверы запускаются только после того, как вы доверяете рабочей области
430* [Фоновые мониторы](#monitors) не загружаются
431
432Плагины с личной областью не имеют никаких из этих ограничений.
433
434<Warning>
435 Плагины `@skills-dir` с областью проекта загружаются только из `.claude/skills/` [основного рабочего каталога](/docs/ru/permissions#working-directories) сеанса. Они не [поднимаются к корню репозитория](/docs/ru/skills#discovery-from-parent-and-nested-directories) так, как это делают обычные skills и команды, поэтому запуск из подкаталога пропускает плагин, который находится в корне репо. Запустите из корня репозитория или [переместите сеанс туда с помощью `/cd`](/docs/ru/permissions#move-the-session-to-another-directory) на v2.1.246 или позже.
436</Warning>
437
438<h3 id="edit-reload-and-disable-a-skills-directory-plugin">
439 Редактируйте, перезагружайте и отключайте плагин каталога skills
440</h3>
441
442Изменения, которые вы вносите в `SKILL.md` skill, вступают в силу немедленно в текущем сеансе. Изменения в других компонентах плагина, таких как `hooks/`, `.mcp.json`, `agents/` и `output-styles/`, не вступают. Запустите `/reload-plugins` или перезагрузите Claude Code, чтобы их подхватить. См. [Обнаружение живых изменений](/docs/ru/skills#live-change-detection).
443
444Чтобы остановить загрузку плагина каталога skills, удалите его папку или отключите его по имени. Нет этапа `uninstall`, потому что ничего не было установлено из marketplace.
445
446```bash theme={null}
447claude plugin disable my-tool@skills-dir
448```
449
450***
451
452<h2 id="synced-plugins">
453 Плагины, синхронизированные с claude.ai
454</h2>
455
456Claude Code загружает плагины, включённые для вашей учётной записи claude.ai, включая плагины, которые ваша организация включает для своих членов, наряду с плагинами, которые вы устанавливаете из marketplace. Он загружает каждый в `~/.claude/plugins/synced/` и загружает его как `<name>@synced`, без marketplace и без записи об установке. Синхронизированный плагин работает с тем же уровнем доверия, что и плагин marketplace, который вы установили: его skills, agents, hooks, MCP servers и LSP servers все загружаются.
457
458Место, где Claude Code синхронизирует эти плагины, зависит от сеанса:
459
460* В [Cowork](https://claude.com/product/cowork) и [облачных сеансах](/docs/ru/cloud-environments#what-carries-over-from-your-setup) Claude Code загружает их в собственную среду сеанса при запуске сеанса. До версии 2.1.239 Claude Code загружал эти плагины как `<name>@inline`, идентификатор, который используют плагины `--plugin-dir`.
461* В сеансах терминала, где вы входите с помощью своей учётной записи claude.ai, Claude Code проверяет вашу учётную запись один раз каждый раз при запуске, затем загружает новые и обновлённые плагины и удаляет те, которые вы или ваша организация отключили, всё в фоновом режиме. Синхронизация в сеансах терминала требует Claude Code версии 2.1.273 или позже.
462
463Проверка при запуске выполняется в фоновом режиме, поэтому она может завершиться после того, как ваш сеанс начался. Когда она добавляет, обновляет или удаляет синхронизированный плагин в интерактивном сеансе, Claude Code показывает `Plugins changed. Run /reload-plugins to activate.` Запустите [`/reload-plugins`](/docs/ru/discover-plugins#apply-plugin-changes-without-restarting), чтобы загрузить изменение в этом сеансе, или оставьте его на следующий раз, когда вы запустите Claude Code. Если вы включите плагин на claude.ai во время работы сеанса, Claude Code загружает его при следующем запуске.
464
465Синхронизация плагинов в сеансах терминала выполняется при тех же условиях входа, что и [skills, синхронизированные с claude.ai](/docs/ru/skills#where-synced-skills-load). Это также требует входа, который предоставляет Claude Code доступ к плагинам вашей учётной записи.
466
467Вход из более ранней версии Claude Code получает доступ к плагинам при следующем обновлении Claude Code этого входа в фоновом режиме, в течение нескольких часов, или сразу же, если вы снова запустите `/login`. Синхронизация плагинов начинается при следующем запуске Claude Code после этого.
468
469`claude plugin list` показывает синхронизированные плагины под заголовком `Synced from claude.ai`, и вкладка **Installed** в `/plugin` перечисляет их с `synced` в качестве источника. Управляйте синхронизированным плагином по ID `<name>@synced`, который выводит `claude plugin list`:
470
471* **Отключить один**: запустите `claude plugin disable <name>@synced` или отключите его на вкладке **Installed** в `/plugin`. Claude Code сохраняет выбор как `"<name>@synced": false` в [`enabledPlugins`](/docs/ru/settings-reference#enabledplugins) на уровне пользователя. Чтобы включить плагин обратно, запустите `claude plugin enable <name>@synced`.
472* **Исключить один везде**: [отключите плагин для вашей учётной записи claude.ai](/docs/ru/desktop#extend-claude-code). Чтобы исключить его из одного проекта в каждой среде, установите `"<name>@synced": false` под `enabledPlugins` в файле `.claude/settings.json` этого проекта.
473* **Управляйте самим плагином на claude.ai**: `claude plugin install`, `update` и `uninstall` не применяются к синхронизированному плагину. Claude Code загружает обновления плагина при следующей синхронизации. Чтобы удалить его, отключите плагин для вашей учётной записи claude.ai, и Claude Code удалит его при следующей синхронизации.
474* **Остановить синхронизацию на машине**: установите [`syncClaudeAiPlugins`](/docs/ru/settings-reference#syncclaudeaiplugins) в `false` в ваших пользовательских настройках. Claude Code прекращает загрузку, и при следующем запуске он перемещает уже синхронизированные плагины в `~/.claude/plugins/.trash/` и больше их не загружает. Ваша организация может установить тот же ключ в [управляемых настройках](/docs/ru/managed-settings), или отключить Skills на claude.ai, что также останавливает синхронизацию плагинов.
475
476Вы не можете отключить плагин, который ваша организация отмечает как обязательный на claude.ai. Claude Code загружает его даже если вы отключили его ранее, и `claude plugin disable` отказывает с `Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it.` В `claude plugin list` эти плагины отмечены как `required by your org`.
477
478Когда включённый плагин из любого другого источника совпадает по имени с синхронизированным плагином, Claude Code загружает этот плагин и сообщает, что синхронизированная копия не загружена. Другие источники включают установки из marketplace, [плагины каталога skills](#skills-directory-plugins), плагины `--plugin-dir` и плагины, встроенные в Claude Code. Чтобы использовать копию с claude.ai, отключите свою копию. До версии 2.1.239 Claude Code загружал синхронизированную копию вместо установки из marketplace с тем же именем.
479
480***
481
482<h2 id="plugin-manifest-schema">
483 Схема манифеста plugin
484</h2>
485
486Файл `.claude-plugin/plugin.json` определяет метаданные и конфигурацию вашего plugin.
487
488Манифест является необязательным. Если он опущен, Claude Code автоматически обнаруживает компоненты в [местоположениях по умолчанию](#file-locations-reference) и выводит имя plugin из имени каталога. Используйте манифест, когда вам нужно предоставить метаданные или пользовательские пути компонентов.
489
490<h3 id="complete-schema">
491 Полная схема
492</h3>
493
494```json theme={null}
495{
496 "name": "plugin-name",
497 "displayName": "Plugin Name",
498 "version": "1.2.0",
499 "description": "Brief plugin description",
500 "author": {
501 "name": "Author Name",
502 "email": "author@example.com",
503 "url": "https://github.com/author"
504 },
505 "homepage": "https://docs.example.com/plugin",
506 "repository": "https://github.com/author/plugin",
507 "license": "MIT",
508 "keywords": ["keyword1", "keyword2"],
509 "metadata": { "catalogId": "cat-123", "tier": "pro" },
510 "skills": "./custom/skills/",
511 "commands": ["./custom/commands/special.md"],
512 "agents": ["./custom/agents/reviewer.md"],
513 "hooks": "./config/hooks.json",
514 "mcpServers": "./mcp-config.json",
515 "outputStyles": "./styles/",
516 "lspServers": "./.lsp.json",
517 "experimental": {
518 "themes": "./themes/",
519 "monitors": "./monitors.json",
520 "evals": "quality/evals"
521 },
522 "dependencies": [
523 "helper-lib",
524 { "name": "secrets-vault", "version": "~2.1.0" }
525 ]
526}
527```
528
529<h3 id="required-fields">
530 Обязательные поля
531</h3>
532
533Если вы включаете манифест, `name` — единственное обязательное поле.
534
535| Поле | Тип | Описание | Пример |
536| :----- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------- |
537| `name` | string | Уникальный идентификатор в kebab-case без пробелов, управляющих символов или символов двунаправленного форматирования. Когда [запись marketplace](/docs/ru/plugin-marketplaces#plugin-entries) указывает plugin под другим именем, имя записи marketplace — это то, что используют ключи `enabledPlugins` и `/plugin` | `"deployment-tools"` |
538
539Это имя используется для пространства имён компонентов. Например, в пользовательском интерфейсе agent `agent-creator` для plugin с именем `plugin-dev` будет отображаться как `plugin-dev:agent-creator`.
540
541<h3 id="unrecognized-fields">
542 Нераспознанные поля
543</h3>
544
545Claude Code игнорирует поля верхнего уровня, которые он не распознаёт. Вы можете сохранить метаданные из другой экосистемы в `plugin.json`, и plugin всё равно загрузится. Это позволяет практично поддерживать один манифест, который одновременно служит манифестом расширения VS Code или Cursor, npm `package.json` или манифестом bundle MCPB/DXT.
546
547`claude plugin validate` сообщает о нераспознанных полях как о предупреждениях, а не об ошибках. Если поле отличается на один или два символа от распознанного, предупреждение предлагает вероятное предполагаемое имя. Plugin только с предупреждениями о нераспознанных полях всё равно проходит валидацию и загружается во время выполнения.
548
549То, как Claude Code обрабатывает распознанное поле, значение которого имеет неправильный тип, зависит от поля:
550
551* **Большинство полей**: plugin не загружается. Например, значение `keywords`, которое является строкой вместо массива, является ошибкой загрузки, и `claude plugin validate` сообщает об этом.
552* **`experimental` и `metadata`**: Claude Code игнорирует значение, которое не является объектом, и `claude plugin validate` сообщает предупреждение.
553
554Передайте `--strict`, чтобы рассматривать предупреждения как ошибки. Используйте это в CI, чтобы перехватить неправильно написанное имя поля или поле, оставшееся от манифеста другого инструмента перед публикацией, даже если plugin загружается во время выполнения.
555
556```bash theme={null}
557claude plugin validate ./my-plugin --strict
558```
559
560<h3 id="metadata-fields">
561 Поля метаданных
562</h3>
563
564| Поле | Тип | Описание | Пример |
565| :--------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- |
566| `$schema` | string | URL JSON Schema для автодополнения и валидации редактора. Claude Code игнорирует это поле во время загрузки. | `"https://json.schemastore.org/claude-code-plugin-manifest.json"` |
567| `displayName` | string | Удобочитаемое имя, отображаемое в средстве выбора `/plugin` и других поверхностях пользовательского интерфейса. Для plugin, установленного из marketplace, `displayName` в [записи marketplace](/docs/ru/plugin-marketplaces#optional-plugin-fields) имеет приоритет над этим значением. Когда имя отображения не установлено ни в одном месте, пользователи видят `name`. В отличие от `name`, может содержать пробелы и любой регистр. Не используется для пространства имён или поиска. | `"Deployment Tools"` |
568| `version` | string | Необязательно. Семантическая версия. Установка этого параметра закрепляет plugin на этой строке версии, поэтому пользователи получают обновления только при её изменении, за исключением [источника `command`](/docs/ru/plugin-marketplaces#command-sources) или plugin [загруженного на месте](#plugin-caching-and-file-resolution); см. [Управление версиями](#version-management). Если также установлено в записи marketplace, `plugin.json` имеет приоритет. Если опущено, версия берётся из следующего источника в [Управлении версиями](#version-management). | `"2.1.0"` |
569| `description` | string | Краткое объяснение назначения plugin | `"Deployment automation tools"` |
570| `author` | object | Информация об авторе | `{"name": "Dev Team", "email": "dev@company.com"}` |
571| `homepage` | string | URL документации | `"https://docs.example.com"` |
572| `repository` | string | URL исходного кода | `"https://github.com/user/plugin"` |
573| `license` | string | Идентификатор лицензии | `"MIT"`, `"Apache-2.0"` |
574| `keywords` | array | Теги обнаружения | `["deployment", "ci-cd"]` |
575| `metadata` | object | Объект произвольной формы для ваших собственных данных, таких как поля прав доступа или каталога. Claude Code не читает его, поэтому значения никогда не влияют на поведение plugin. Claude Code игнорирует значение, которое не является объектом, и `claude plugin validate` сообщает об этом как о предупреждении. До v2.1.222 Claude Code рассматривал ключ как [нераспознанное поле](#unrecognized-fields). | `{"catalogId": "cat-123"}` |
576| `defaultEnabled` | boolean | Включен ли plugin в состояние по умолчанию, когда пользователь не установил его. По умолчанию `true`. См. [Включение по умолчанию](#default-enablement). | `false` |
577
578<h3 id="default-enablement">
579 Включение по умолчанию
580</h3>
581
582Установите `defaultEnabled: false` в `plugin.json`, чтобы отправить plugin, который устанавливается отключённым. Пользователь включает его с помощью `claude plugin enable <plugin>` или интерфейса `/plugin`. Используйте это для plugin, которые добавляют стоимость или область, в которую пользователь должен согласиться, например для plugin, который подключается к внешнему сервису.
583
584`defaultEnabled` — это резервный вариант, когда ничто другое не решило состояние plugin. Параметр пользователя и требование зависимости имеют приоритет над ним:
585
586* **Параметр пользователя**: запись для plugin в `enabledPlugins` в любой области параметров. После записи она сохраняется при обновлениях и переустановках plugin, поэтому изменение `defaultEnabled` в более позднем выпуске не переключает существующего пользователя.
587* **Требование зависимости**: когда plugin требуется другим, который активен, Claude Code записывает `true` для него во время установки или включения. Это даёт ему явный параметр, поэтому его собственное значение по умолчанию больше не применяется. См. [Включение или отключение plugin с зависимостями](/docs/ru/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies).
588
589То же поле может появиться в записи marketplace plugin, где оно имеет приоритет над значением в `plugin.json`. См. [Необязательные поля plugin](/docs/ru/plugin-marketplaces#optional-plugin-fields).
590
591<h3 id="component-path-fields">
592 Поля пути компонента
593</h3>
594
595| Поле | Тип | Описание | Пример |
596| :---------------------- | :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |
597| `skills` | string\|array | Пользовательские каталоги skills, содержащие `<name>/SKILL.md`. Добавляет к сканированию `skills/` по умолчанию. См. [Правила поведения пути](#path-behavior-rules) для исключения корня marketplace | `"./custom/skills/"` |
598| `commands` | string\|array | Пользовательские плоские файлы `.md` skill или каталоги (заменяет `commands/` по умолчанию) | `"./custom/cmd.md"` или `["./cmd1.md"]` |
599| `agents` | string\|array | Пользовательские файлы agent (заменяет `agents/` по умолчанию) | `"./custom/agents/reviewer.md"` |
600| `workflows` | string\|array | Пользовательские файлы скриптов [workflow](/docs/ru/workflows) или каталоги (заменяет `workflows/` по умолчанию) | `"./custom/workflows/"` |
601| `hooks` | string\|array\|object | Пути конфигурации hooks или встроенная конфигурация | `"./my-extra-hooks.json"` |
602| `mcpServers` | string\|array\|object | Пути конфигурации MCP или встроенная конфигурация | `"./my-extra-mcp-config.json"` |
603| `outputStyles` | string\|array | Пользовательские файлы стилей вывода/каталоги (заменяет `output-styles/` по умолчанию) | `"./styles/"` |
604| `lspServers` | string\|array\|object | Конфигурации [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) для интеллекта кода (перейти к определению, найти ссылки и т. д.) | `"./.lsp.json"` |
605| `experimental.themes` | string\|array | Файлы цветовой темы/каталоги (заменяет `themes/` по умолчанию). См. [Темы](#themes) | `"./themes/"` |
606| `experimental.monitors` | string\|array | Конфигурации фонового [Monitor](/docs/ru/tools-reference#monitor-tool), которые запускаются автоматически, когда plugin активен. См. [Мониторы](#monitors) | `"./monitors.json"` |
607| `experimental.evals` | string\|array | Каталог ниже корня plugin, который содержит [случаи eval](/docs/ru/plugin-evals#use-a-different-eval-directory) plugin, когда это не `evals/` по умолчанию. `claude plugin eval --eval-dir` переопределяет его | `"quality/evals"` |
608| `userConfig` | object | Значения, настраиваемые пользователем, запрашиваемые при включении. См. [Конфигурация пользователя](#user-configuration) | |
609| `channels` | array | Объявления каналов для внедрения сообщений (стиль Telegram, Slack, Discord). См. [Каналы](#channels) | |
610| `dependencies` | array | Другие plugin, которые требует этот plugin, опционально с ограничениями версии semver. См. [Ограничение версий зависимостей plugin](/docs/ru/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |
611
612<h3 id="experimental-components">
613 Экспериментальные компоненты
614</h3>
615
616Компоненты под ключом `experimental`, `themes` и `monitors`, имеют схему манифеста, которая может измениться между выпусками во время их стабилизации. Где вы их объявляете, — это отдельная миграция: верхний уровень всё ещё работает, `claude plugin validate` предупреждает, и будущий выпуск потребует `experimental.*`.
617
618<h3 id="user-configuration">
619 Конфигурация пользователя
620</h3>
621
622Поле `userConfig` объявляет значения, которые Claude Code запрашивает у пользователя при включении plugin. Используйте это вместо требования пользователям вручную редактировать `settings.json`.
623
624```json theme={null}
625{
626 "userConfig": {
627 "api_endpoint": {
628 "type": "string",
629 "title": "API endpoint",
630 "description": "Your team's API endpoint"
631 },
632 "api_token": {
633 "type": "string",
634 "title": "API token",
635 "description": "API authentication token",
636 "sensitive": true
637 }
638 }
639}
640```
641
642Ключи должны быть допустимыми идентификаторами. Каждый параметр поддерживает эти поля:
643
644| Поле | Обязательно | Описание |
645| :------------ | :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
646| `type` | Да | Один из `string`, `number`, `boolean`, `directory` или `file` |
647| `title` | Да | Метка, отображаемая в диалоговом окне конфигурации |
648| `description` | Да | Справочный текст, отображаемый под полем |
649| `sensitive` | Нет | Если `true`, скрывает ввод и сохраняет значение в защищённом хранилище вместо `settings.json` |
650| `required` | Нет | Если `true`, валидация не пройдёт, когда поле пусто |
651| `default` | Нет | Значение, используемое, когда пользователь ничего не предоставляет |
652| `options` | Нет | Для типа `string`, значения, которые принимает поле, отображаемые в `/config` как средство выбора над ними. См. [Ограничение поля фиксированными параметрами](#limit-a-field-to-fixed-options). Требуется Claude Code v2.1.271 или позже |
653| `multiple` | Нет | Для типа `string`, разрешить массив строк |
654| `min` / `max` | Нет | Границы для типа `number` |
655
656За исключением полей `sensitive` и списков `multiple`, каждое поле каждого включённого plugin также отображается как строка на панели `/config`. Строки требуют Claude Code v2.1.269 или позже.
657
658Каждое значение доступно для подстановки как `${user_config.KEY}` в конфигурациях MCP и LSP серверов и команды hooks. Нечувствительные значения также могут быть подставлены в содержимое skill и agent. Все значения экспортируются в процессы hook как переменные окружения `CLAUDE_PLUGIN_OPTION_<KEY>`, где `<KEY>` — это ключ параметра в верхнем регистре.
659
660Поля, которые работают в shell, отклоняют `${user_config.*}`: подстановка настроенного значения в команду shell позволит shell запустить всё, что содержит это значение, поэтому компонент не работает с [ошибкой](/docs/ru/errors#plugin-command-references-user-config). Каждое отклонённое поле имеет альтернативный способ передачи значения:
661
662| Отклонённое поле | Как передать значение |
663| :--------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- |
664| Команды hooks в форме shell | Используйте [форму exec](/docs/ru/hooks#exec-form-and-shell-form) с `args` или прочитайте `CLAUDE_PLUGIN_OPTION_<KEY>` из окружения hook |
665| Команды [Monitor](#monitors) | Прочитайте значение из файла конфигурации в скрипте |
666| MCP [`headersHelper`](/docs/ru/mcp#use-dynamic-headers-for-custom-authentication) | Прочитайте значение из файла конфигурации в скрипте |
667
668До v2.1.207 эти поля подставляли значения `${user_config.KEY}`; обновите plugin, которые полагались на это.
669
670Нечувствительные значения хранятся под ключом [`pluginConfigs`](/docs/ru/settings-reference#pluginconfigs) в вашем пользовательском `settings.json` как `pluginConfigs[<plugin-id>].options`.
671
672На macOS Claude Code хранит чувствительные значения в macOS Keychain, переходя на `~/.claude/.credentials.json`, когда Keychain отклоняет запись. На платформах без поддерживаемого keychain он хранит их в `~/.claude/.credentials.json`. Хранилище Keychain используется совместно с токенами OAuth и имеет приблизительный общий лимит в 2 КБ, поэтому держите чувствительные значения небольшими.
673
674Claude Code читает все значения `pluginConfigs` только из трёх источников параметров:
675
676* **Параметры пользователя**: `~/.claude/settings.json`, файл, в который записывает подсказка во время включения
677* **`--settings`**: флаг CLI или встроенные параметры SDK
678* **Управляемые параметры**: [политика, контролируемая организацией](/docs/ru/permissions#managed-settings)
679
680Когда более одного источника устанавливает один и тот же ключ, управляемые параметры имеют приоритет, затем `--settings`, затем параметры пользователя. Единственный источник, который вы можете удалить из этого списка, — это параметры пользователя: передайте [`--setting-sources`](/docs/ru/cli-reference#cli-flags) без `user`, и Claude Code пропустит их. Управляемые параметры и `--settings` остаются тем, что вы передали. Опция [`settingSources`](/docs/ru/agent-sdk/claude-code-features#what-settingsources-does-not-control) SDK устанавливает тот же список.
681
682Записи в `.claude/settings.json` или `.claude/settings.local.json` проекта игнорируются. Оба файла находятся в рабочей области, поэтому клонированный репозиторий может предоставить значения там, и эти значения будут поступать в команды hook plugin, конфигурации MCP сервера, команды LSP и команды monitor. До v2.1.207 эти записи читались. Ограничение специфично для `pluginConfigs`: [`enabledPlugins`](/docs/ru/settings-reference#enabledplugins) по-прежнему учитывает параметры проекта и локальные параметры.
683
684<h4 id="limit-a-field-to-fixed-options">
685 Ограничение поля фиксированными параметрами
686</h4>
687
688Установите `options` на поле `userConfig`, чтобы пользователи выбирали его значение из фиксированного списка.
689
690Чтобы ограничить поле `tone` тремя параметрами, перечислите их в `options` и установите `default` на один из них:
691
692```json theme={null}
693{
694 "userConfig": {
695 "tone": {
696 "type": "string",
697 "title": "Tone",
698 "description": "Voice for generated replies",
699 "options": ["neutral", "warm", "formal"],
700 "default": "neutral"
701 }
702 }
703}
704```
705
706Если вы объявляете `options` на любом поле, пользователи на версиях Claude Code до v2.1.271 не смогут загрузить plugin.
707
708Когда вы устанавливаете `options` на поле, следуйте этим правилам:
709
710* Установите `type` на `string`
711* Не устанавливайте `multiple` или `sensitive` на `true`
712* Установите `default` на один из параметров
713* Если вы оставляете `default` неустановленным, установите `required` на `true`
714* Перечислите по крайней мере один параметр, каждый от 1 до 64 символов в длину
715* Не начинайте и не заканчивайте параметр пробелом
716* Не используйте управляющие символы, невидимые символы, символы, которые изменяют направление текста, или пробелы, отличные от обычного пробела в параметре
717* Не перечисляйте один и тот же параметр дважды, даже в другом регистре букв
718
719Если вы нарушите любое из этих правил, plugin не загрузится. Запустите `claude plugin validate`, чтобы увидеть, какое поле нарушает какое правило.
720
721<h3 id="channels">
722 Каналы
723</h3>
724
725Поле `channels` позволяет plugin объявить один или несколько каналов сообщений, которые внедряют содержимое в разговор. Каждый канал привязывается к MCP серверу, который предоставляет plugin.
726
727```json theme={null}
728{
729 "channels": [
730 {
731 "server": "telegram",
732 "userConfig": {
733 "bot_token": {
734 "type": "string",
735 "title": "Bot token",
736 "description": "Telegram bot token",
737 "sensitive": true
738 },
739 "owner_id": {
740 "type": "string",
741 "title": "Owner ID",
742 "description": "Your Telegram user ID"
743 }
744 }
745 }
746 ]
747}
748```
749
750Поле `server` обязательно и должно совпадать с ключом в `mcpServers` plugin. Необязательный `userConfig` для каждого канала использует ту же схему, что и поле верхнего уровня, позволяя plugin запрашивать токены бота или ID владельца при включении plugin.
751
752<h3 id="path-behavior-rules">
753 Правила поведения пути
754</h3>
755
756Заменяет ли пользовательский путь или расширяет каталог plugin по умолчанию, зависит от поля:
757
758* **Заменяет значение по умолчанию**: `commands`, `agents`, `workflows`, `outputStyles`, `experimental.themes`, `experimental.monitors`. Например, когда манифест указывает `commands`, каталог `commands/` по умолчанию не сканируется. Чтобы сохранить значение по умолчанию и добавить больше, перечислите его явно: `"commands": ["./commands/", "./extras/"]`
759* **Добавляет к значению по умолчанию**: `skills`. Каталог `skills/` по умолчанию всегда сканируется, и каталоги, перечисленные в `skills`, загружаются вместе с ним. Исключение: для [записи marketplace, чей `source` разрешается в корень marketplace](/docs/ru/plugin-marketplaces#advanced-plugin-entries), объявление определённых подкаталогов заменяет сканирование `skills/` по умолчанию
760* **Собственные правила слияния**: [hooks](#hooks), [MCP серверы](#mcp-servers) и [LSP серверы](#lsp-servers). См. каждый раздел для того, как несколько источников объединяются
761
762Когда plugin имеет как папку по умолчанию, так и соответствующий ключ манифеста, Claude Code предупреждает об игнорируемой папке в `claude plugin list` и в представлении деталей `/plugin`. Plugin всё равно загружается с использованием путей манифеста. Claude Code не предупреждает, когда ключ манифеста указывает в папку по умолчанию, например `"commands": ["./commands/deploy.md"]`, потому что этот путь явно называет папку.
763
764Для всех полей пути:
765
766* Все пути должны быть относительны к корню plugin и начинаться с `./`, за исключением того, что поле `skills` также принимает `"."`
767 * Оба `"."` и `"./"` обозначают сам корень plugin
768 * До v2.1.221 `"."` не прошёл валидацию манифеста и plugin не загрузился, поэтому используйте `"./"` для поддержки более ранних версий
769* Компоненты из пользовательских путей используют те же правила именования и пространства имён, за исключением файлов agent. См. [Agents](#agents) для того, как работают имена agent
770* Несколько путей можно указать как массивы
771* Путь skill может указывать на каталог, который содержит `SKILL.md` непосредственно, например `"skills": ["."]` для корня plugin
772 * Claude Code берёт имя вызова skill из поля frontmatter `name` в `SKILL.md`, поэтому имя остаётся стабильным, независимо от того, как называется каталог установки
773 * Если `name` не установлен в frontmatter, Claude Code переходит на имя базового каталога
774
775Plugin, который имеет `SKILL.md` в своём корне, не имеет подкаталога `skills/` и не имеет поля манифеста `skills`, автоматически загружается как plugin с одним skill. Вам не нужно устанавливать `"skills": ["./"]` в `plugin.json` для этого макета.
776
777**Примеры пути**:
778
779```json theme={null}
780{
781 "commands": [
782 "./specialized/deploy.md",
783 "./utilities/batch-process.md"
784 ],
785 "agents": [
786 "./custom-agents/reviewer.md",
787 "./custom-agents/tester.md"
788 ]
789}
790```
791
792<h3 id="environment-variables">
793 Переменные окружения
794</h3>
795
796Claude Code предоставляет три переменные для ссылки на пути:
797
798| Переменная | Разрешается в | Используйте для |
799| :---------------------- | :------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------- |
800| `${CLAUDE_PLUGIN_ROOT}` | Абсолютный путь к каталогу установки plugin | Скрипты, двоичные файлы и файлы конфигурации, поставляемые с plugin |
801| `${CLAUDE_PLUGIN_DATA}` | [Постоянный каталог](#persistent-data-directory), который сохраняется при обновлениях plugin, создаётся при первой ссылке | Установленные зависимости, такие как `node_modules` или виртуальные окружения Python, сгенерированный код и кэши |
802| `${CLAUDE_PROJECT_DIR}` | Корень проекта | Локальные скрипты и файлы конфигурации проекта |
803
804Все три экспортируются как переменные окружения в процессы hook и в подпроцессы MCP и LSP серверов. Они отсутствуют в окружении команд, которые Claude запускает через инструмент Bash, в основной сессии или в подагенте. В содержимом plugin напишите заполнитель вместо этого, и Claude Code подставит путь встроенно при загрузке содержимого. Какие поля подставляют их встроенно, зависит от компонента plugin:
805
806| Компонент plugin | Поля, где заполнители разрешаются |
807| :------------------------------ | :------------------------------------------ |
808| Содержимое skill и agent | Везде, где появляется заполнитель |
809| Команды hook и monitor | Везде, где появляется заполнитель |
810| MCP `stdio` серверы | `command`, `args`, `env` |
811| MCP `http`, `sse`, `ws` серверы | `url`, `headers`, `headersHelper` |
812| LSP серверы | `command`, `args`, `env`, `workspaceFolder` |
813
814В командах hook используйте [форму exec](/docs/ru/hooks#exec-form-and-shell-form) с `args`, чтобы каждый путь передавался как один аргумент без кавычек. В hooks в форме shell и командах monitor оберните переменные в двойные кавычки, как в `"${CLAUDE_PROJECT_DIR}/scripts/server.sh"`. Этот hook в форме shell запускает скрипт, поставляемый с plugin:
815
816```json theme={null}
817{
818 "hooks": {
819 "PostToolUse": [
820 {
821 "hooks": [
822 {
823 "type": "command",
824 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/process.sh"
825 }
826 ]
827 }
828 ]
829 }
830}
831```
832
833Для скопированного plugin `${CLAUDE_PLUGIN_ROOT}` изменяется при обновлении plugin. Каталог предыдущей версии остаётся на диске в течение периода благодати после обновления, но рассматривайте его как эфемерный и не записывайте состояние туда. Для plugin, загруженного на месте из marketplace локального каталога, переменная указывает на стабильный исходный каталог. См. [кэширование plugin](#plugin-caching-and-file-resolution) для того, какие plugin копируются и для семантики очистки.
834
835Когда скопированный plugin обновляется в середине сессии, команды hook, мониторы, MCP серверы и LSP серверы продолжают использовать путь предыдущей версии. Запустите `/reload-plugins`, чтобы переключить hooks, MCP серверы и LSP серверы на новый путь; мониторы требуют перезагрузки сессии. В сессии без интерактивного терминала перезагрузка оставляет MCP серверы plugin на старом пути до следующей сессии.
836
837Для plugin с источником `command`, Claude Code [может перезагрузить сам plugin](/docs/ru/plugin-marketplaces#when-claude-code-re-runs-the-command).
838
839MCP серверы также могут вызвать запрос `roots/list` для чтения рабочих каталогов сессии во время выполнения. См. [что возвращает `roots/list` и когда Claude Code уведомляет сервер об изменениях](/docs/ru/mcp#option-3-add-a-local-stdio-server).
840
841<h4 id="persistent-data-directory">
842 Постоянный каталог данных
843</h4>
844
845Каталог `${CLAUDE_PLUGIN_DATA}` разрешается в `~/.claude/plugins/data/{id}/`, где `{id}` — это идентификатор plugin с символами вне `a-z`, `A-Z`, `0-9`, `_` и `-`, заменённые на `-`. Для plugin, установленного как `formatter@my-marketplace`, каталог — это `~/.claude/plugins/data/formatter-my-marketplace/`.
846
847Обычное использование — установка зависимостей языка один раз и их повторное использование в сессиях и обновлениях plugin. Используйте его для зависимостей Python, зависимостей, заблокированных с помощью Yarn или pnpm, и пакетов, чьи скрипты жизненного цикла должны работать. Для plugin, установленного из marketplace, вам может вообще не понадобиться: Claude Code автоматически устанавливает подходящие [зависимости пакета Node.js](#node-js-package-dependencies) при кэшировании plugin.
848
849Поскольку каталог данных пережидает любую одну версию plugin, проверка существования каталога одной не может обнаружить, когда обновление изменяет манифест зависимостей plugin. Рекомендуемый паттерн сравнивает поставляемый манифест с копией в каталоге данных и переустанавливает, когда они отличаются.
850
851Этот hook `SessionStart` устанавливает `node_modules` при первом запуске и снова, когда обновление plugin включает изменённый `package.json`:
852
853```json theme={null}
854{
855 "hooks": {
856 "SessionStart": [
857 {
858 "hooks": [
859 {
860 "type": "command",
861 "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
862 }
863 ]
864 }
865 ]
866 }
867}
868```
869
870`diff` выходит с ненулевым кодом, когда сохранённая копия отсутствует или отличается от поставляемой, охватывая как первый запуск, так и обновления, изменяющие зависимости. Если `npm install` не удаётся, завершающий `rm` удаляет скопированный манифест, чтобы следующая сессия повторила попытку.
871
872Скрипты, поставляемые в `${CLAUDE_PLUGIN_ROOT}`, затем могут работать с сохранённым `node_modules`:
873
874```json theme={null}
875{
876 "mcpServers": {
877 "routines": {
878 "command": "node",
879 "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
880 "env": {
881 "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
882 }
883 }
884 }
885}
886```
887
888Каталог данных удаляется автоматически при удалении plugin из последней области, где он установлен. Интерфейс `/plugin` показывает размер каталога и запрашивает перед удалением. CLI удаляет по умолчанию; передайте [`--keep-data`](#plugin-uninstall), чтобы сохранить его.
889
890***
891
892<h2 id="plugin-caching-and-file-resolution">
893 Кеширование плагинов и разрешение файлов
894</h2>
895
896Плагины указываются одним из трёх способов:
897
898* Через `claude --plugin-dir` или `claude --plugin-url` на время сеанса.
899* Через marketplace, установленные для будущих сеансов.
900* Через ваш аккаунт claude.ai, [синхронизированные](#synced-plugins) в `~/.claude/plugins/synced/`.
901
902В целях безопасности и верификации Claude Code копирует плагины из *marketplace* в локальный **кеш плагинов** пользователя (`~/.claude/plugins/cache`), за исключением случаев, когда плагин загружается на месте. [`command` источник в режиме link](/docs/ru/plugin-marketplaces#copy-mode-and-link-mode) загружается на месте через ссылки в записи кеша. [Источник с относительным путём](/docs/ru/plugin-marketplaces#relative-paths) в marketplace, добавленном из локального каталога, загружается на месте из папки marketplace.
903
904Для плагина, загруженного на месте из marketplace локального каталога, ваши изменения в исходном каталоге вступают в силу при следующем запуске сеанса или `/reload-plugins`. Вам не нужно увеличивать версию. Процессы hook плагина и серверы MCP и LSP получают `CLAUDE_PLUGIN_ROOT`, который указывает на исходный каталог. Claude Code не устанавливает [зависимости пакетов Node.js](#node-js-package-dependencies) плагина в исходный каталог. Установите их там самостоятельно или из hook в [каталог постоянных данных](#persistent-data-directory).
905
906Для скопированных плагинов каждая установленная версия представляет собой отдельный каталог в кеше, сгруппированный по marketplace и плагину и названный по разрешённой версии, с собственной копией файлов плагина и [зависимостей пакетов Node.js](#node-js-package-dependencies). Зависимость, разрешённая из [тега релиза](/docs/ru/plugin-dependencies#tag-plugin-releases-for-version-resolution), получает имя каталога с суффиксом commit-SHA.
907
908Когда вы обновляете или удаляете плагин, Claude Code помечает предыдущий каталог версии как сиротский и удаляет его в фоновой очистке примерно через 14 дней. Период отсрочки позволяет одновременным сеансам Claude Code, которые уже загрузили старую версию, продолжать работу без ошибок. Claude Code запускает очистку только при наличии установленного хотя бы одного плагина; после удаления последнего плагина сиротские каталоги остаются на диске до установки плагина снова.
909
910Claude Code удаляет папку плагина или marketplace из кеша только когда она больше не содержит никаких каталогов или символических ссылок. Если вы создаёте символическую ссылку на разработочный checkout в кеш как запись версии плагина, Claude Code никогда не помечает ссылку как сиротскую и никогда не удаляет её или папки, которые её содержат. Claude Code также никогда не записывает свои файлы отслеживания версий внутри связанного checkout.
911
912Инструменты Glob и Grep Claude пропускают сиротские каталоги версий при поиске, поэтому результаты файлов не включают устаревший код плагина.
913
914<h3 id="node-js-package-dependencies">
915 Зависимости пакетов Node.js
916</h3>
917
918Когда Claude Code копирует плагин в кеш, он также устанавливает зависимости пакетов Node.js плагина там, чтобы hooks и MCP серверы плагина могли их загружать. Этот раздел охватывает пакеты npm и Bun, которые плагин объявляет в своём собственном `package.json`. Для плагинов, которые зависят от других плагинов, см. [версии зависимостей плагинов](/docs/ru/plugin-dependencies).
919
920Claude Code запускает установку внутри скопированного каталога версии каждый раз, когда создаёт его: при установке плагина, когда Claude Code обновляет плагин до новой версии, и при запуске сеанса, когда включённый плагин ещё не кеширован, например на новой машине. Установка запускается только когда корневой каталог плагина содержит как `package.json`, так и поддерживаемый файл блокировки:
921
922| Файл блокировки | Команда |
923| :-------------------------------------------- | :----------------------------------------------- |
924| `bun.lock` или `bun.lockb` | `bun install --frozen-lockfile --ignore-scripts` |
925| `npm-shrinkwrap.json` или `package-lock.json` | `npm ci --ignore-scripts` |
926
927Если плагин содержит более одного из этих файлов блокировки, Claude Code использует первое совпадение, проверяя по порядку: `bun.lock`, `bun.lockb`, `npm-shrinkwrap.json`, `package-lock.json`.
928
929Claude Code пропускает установку в двух случаях, каждый со своим решением:
930
931* Если ваш плагин поставляется только с `yarn.lock` или `pnpm-lock.yaml`, замените его на файл блокировки npm.
932* Если `bunfig.toml` находится рядом с файлом блокировки bun, удалите `bunfig.toml` или замените файл блокировки bun на файл блокировки npm.
933
934Поставляйте файл блокировки npm для максимального охвата. Claude Code запускает менеджер пакетов файла блокировки из PATH пользователя и не переходит на другой файл блокировки, если он отсутствует. Для плагина, распространяемого через источник npm, используйте `npm-shrinkwrap.json`; npm исключает `package-lock.json` из опубликованных пакетов.
935
936Claude Code ограничивает эту установку зависимостей так, чтобы никакой код из плагина или его пакетов не выполнялся во время неё, и ограничивает, как долго она может работать:
937
938* **Замороженное разрешение:** Bun и npm устанавливают ровно то, что закреплено в файле блокировки, и выходят с ошибкой, а не переразрешают версии, когда `package.json` и файл блокировки не совпадают.
939* **Без скриптов жизненного цикла:** `--ignore-scripts` предотвращает запуск скриптов `preinstall`, `install` и `postinstall`, поэтому зависимости, которые собирают нативные модули в этих скриптах, загружаются, но не компилируются во время этой установки.
940* **Тайм-аут 60 секунд:** Claude Code останавливает установку, которая работает дольше, и рассматривает её как неудачную.
941
942Claude Code получает плагин из источника npm перед этой установкой зависимостей, и ни один из собственных скриптов установки пакета не запускается во время получения. См. [пакеты npm](/docs/ru/plugin-marketplaces#npm-packages).
943
944Неудачная или пропущенная установка никогда не блокирует плагин. Когда установка не удаётся или Claude Code пропускает её из-за файла блокировки yarn или pnpm или `bunfig.toml`, он записывает причину как предупреждение в [выходе отладки](#debugging-commands). Плагин с `package.json` и без файла блокировки пропускается без записи в журнал. Истёкшая по времени установка может оставить частичное дерево `node_modules` в кешированной копии.
945
946Вы не можете отключить автоматическую установку; никакая настройка или переменная окружения её не отключает. В ограниченных сетях см. [требования к сетевому доступу](/docs/ru/network-config#network-access-requirements) для хостов, которые нужно разрешить.
947
948Для зависимостей, которые автоматическая установка не может предоставить, таких как пакеты, которым нужны скрипты жизненного цикла для сборки, зависимости Python или плагин, заблокированный Yarn или pnpm, установите их из hook в [каталог постоянных данных](#persistent-data-directory).
949
950<h3 id="path-traversal-limitations">
951 Ограничения обхода пути
952</h3>
953
954Claude Code не позволяет плагину ссылаться на файлы вне его собственного каталога. Он отклоняет путь компонента, который разрешается вне корня плагина, независимо от того, объявлен ли путь в `plugin.json` или в [записи marketplace](/docs/ru/plugin-marketplaces#plugin-entries). Это охватывает путь, который указывает вне плагина в том виде, в котором он написан, например `../shared-utils`, и символическую ссылку, которая ведёт вне плагина, кроме [ссылок в одном marketplace](#share-files-within-a-marketplace-with-symlinks).
955
956На macOS и Linux Claude Code также отклоняет путь компонента, который содержит обратную косую черту где-либо в нём, даже когда путь остаётся внутри плагина. Компоненты, объявленные с путями обратной косой черты, поэтому загружаются только на Windows. Пишите пути компонентов с прямыми косыми чертами, например `./commands/deploy.md`.
957
958Когда Claude Code отклоняет путь, он сообщает об ошибке [`path escapes plugin directory`](/docs/ru/errors#path-escapes-plugin-directory) и загружает плагин без этого компонента.
959
960Claude Code также не копирует файлы вне каталога плагина в кеш при установке плагина, поэтому когда скрипт внутри скопированного плагина читает путь выше корня плагина, он не находит эти файлы либо.
961
962<h3 id="share-files-within-a-marketplace-with-symlinks">
963 Совместное использование файлов в marketplace с помощью символических ссылок
964</h3>
965
966Если ваш плагин должен совместно использовать файлы с другими частями одного и того же marketplace, вы можете создавать символические ссылки внутри каталога вашего плагина. То, как символическая ссылка обрабатывается при копировании плагина в кеш, зависит от того, где разрешается её цель:
967
968* **Внутри собственного каталога плагина:** символическая ссылка сохраняется как относительная символическая ссылка в кеше, поэтому она продолжает разрешаться на скопированную цель во время выполнения.
969* **В другом месте в одном marketplace:** символическая ссылка разыменовывается. Содержимое цели копируется в кеш на её место. Это позволяет каталогу `skills/` мета-плагина ссылаться на skills, определённые другими плагинами в marketplace.
970* **Вне marketplace:** символическая ссылка пропускается в целях безопасности. Это предотвращает извлечение плагинами произвольных файлов хоста, таких как системные пути, в кеш.
971
972Для плагинов, установленных с `--plugin-dir`, из локального пути или из [`command` источника](/docs/ru/plugin-marketplaces#copy-mode-and-link-mode) в режиме copy, сохраняются только символические ссылки, которые разрешаются в собственном каталоге плагина. Все остальные пропускаются.
973
974Следующая команда создаёт ссылку из плагина marketplace на общий skill, определённый плагином-соседом. На Windows используйте `mklink /D` из командной строки с повышенными привилегиями или включите режим разработчика:
975
976```bash theme={null}
977ln -s ../../shared-plugin/skills/foo ./skills/foo
978```
979
980***
981
982<h2 id="plugin-directory-structure">
983 Структура каталога плагина
984</h2>
985
986<h3 id="standard-plugin-layout">
987 Стандартная структура плагина
988</h3>
989
990Полный плагин следует этой структуре:
991
992```text theme={null}
993enterprise-plugin/
994├── .claude-plugin/ # Каталог метаданных (опционально)
995│ └── plugin.json # манифест плагина
996├── skills/ # Skills
997│ ├── code-reviewer/
998│ │ └── SKILL.md
999│ └── pdf-processor/
1000│ ├── SKILL.md
1001│ └── scripts/
1002├── commands/ # Skills как плоские файлы .md
1003│ ├── status.md
1004│ └── logs.md
1005├── agents/ # Определения подагентов
1006│ ├── security-reviewer.md
1007│ ├── performance-tester.md
1008│ ├── compliance-checker.md
1009│ └── review/ # Агенты здесь загружаются как enterprise-plugin:review:<name>
1010│ └── accessibility.md
1011├── workflows/ # Скрипты рабочих процессов
1012│ └── release-audit.js
1013├── output-styles/ # Определения стилей вывода
1014│ └── terse.md
1015├── themes/ # Определения цветовых тем
1016│ └── dracula.json
1017├── monitors/ # Конфигурации фоновых мониторов
1018│ └── monitors.json
1019├── hooks/ # Конфигурации hooks
1020│ ├── hooks.json # Основная конфигурация hooks
1021│ └── security-hooks.json # Дополнительные hooks
1022├── bin/ # Исполняемые файлы плагина, добавленные в PATH
1023│ └── my-tool # Вызывается как простая команда в инструменте Bash
1024├── settings.json # Параметры по умолчанию для плагина
1025├── .mcp.json # Определения MCP-сервера
1026├── .lsp.json # Конфигурации LSP-сервера
1027├── scripts/ # Скрипты hooks и утилиты
1028│ ├── security-scan.sh
1029│ ├── format-code.py
1030│ └── deploy.js
1031├── LICENSE # Файл лицензии
1032└── CHANGELOG.md # История версий
1033```
1034
1035<Warning>
1036 Каталог `.claude-plugin/` содержит файл `plugin.json`. Все остальные каталоги (commands/, agents/, skills/, workflows/, output-styles/, themes/, monitors/, hooks/) должны находиться в корне плагина, а не внутри `.claude-plugin/`.
1037</Warning>
1038
1039Файл `CLAUDE.md` в корне плагина не загружается как контекст проекта. Плагины предоставляют контекст через skills, agents и hooks, а не через CLAUDE.md. Чтобы отправить инструкции, которые загружаются в контекст Claude, поместите их в [skill](#skills).
1040
1041<h3 id="file-locations-reference">
1042 Справочник расположения файлов
1043</h3>
1044
1045| Компонент | Расположение по умолчанию | Назначение |
1046| :-------------------- | :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1047| **Манифест** | `.claude-plugin/plugin.json` | Метаданные и конфигурация плагина (опционально) |
1048| **Skills** | `skills/` | Skills со структурой `<name>/SKILL.md` |
1049| **Команды** | `commands/` | Skills как плоские файлы Markdown. Используйте `skills/` для новых плагинов |
1050| **Агенты** | `agents/` | Файлы Markdown подагентов. Подпапки являются частью [имени агента](#agents) |
1051| **Рабочие процессы** | `workflows/` | Файлы скриптов [Workflow](/docs/ru/workflows) |
1052| **Стили вывода** | `output-styles/` | Определения стилей вывода |
1053| **Темы** | `themes/` | Определения цветовых тем |
1054| **Hooks** | `hooks/hooks.json` | Конфигурация hooks |
1055| **MCP-серверы** | `.mcp.json` | Определения MCP-сервера |
1056| **LSP-серверы** | `.lsp.json` | Конфигурации языковых серверов |
1057| **Мониторы** | `monitors/monitors.json` | Конфигурации фоновых мониторов |
1058| **Исполняемые файлы** | `bin/` | Исполняемые файлы, добавленные в `PATH` инструмента Bash и вызываемые как простые команды при включении плагина. Вы не можете включить этот каталог в плагин, который вы [распространяете через параметры организации claude.ai](/docs/ru/plugin-marketplaces#keep-executables-out-of-the-top-level-bin-directory) |
1059| **Параметры** | `settings.json` | Конфигурация по умолчанию, применяемая при включении плагина. Поддерживаются только ключи [`agent`](/docs/ru/sub-agents) и [`subagentStatusLine`](/docs/ru/statusline#subagent-status-lines) |
1060
1061***
1062
1063<h2 id="cli-commands-reference">
1064 Справочник команд CLI
1065</h2>
1066
1067Claude Code предоставляет команды CLI для неинтерактивного управления плагинами, полезные для написания скриптов и автоматизации.
1068
1069<h3 id="plugin-init">
1070 plugin init
1071</h3>
1072
1073Создайте новый плагин в `~/.claude/skills/<name>/`. На следующей сессии Claude Code он загружается автоматически как `<name>@skills-dir` и появляется в `/plugin` и `claude plugin list` без необходимости установки.
1074
1075См. [Skills-directory plugins](#skills-directory-plugins) для требований к области действия и доверию.
1076
1077```bash theme={null}
1078claude plugin init <name> [options]
1079```
1080
1081Команда принимает эти аргументы:
1082
1083* `<name>`: Имя плагина. Становится пространством имён навыка и именем каталога в `~/.claude/skills/`, поэтому не может содержать пробелы или разделители пути.
1084
1085Команда принимает эти опции:
1086
1087| Опция | Описание | По умолчанию |
1088| :----------------------- | :-------------------------------------------------------------------------------------------------------------------------- | :---------------------- |
1089| `--description <text>` | Описание в манифесте | |
1090| `--author <name>` | Имя автора | `git config user.name` |
1091| `--author-email <email>` | Email автора | `git config user.email` |
1092| `--with <components...>` | Также создайте папки компонентов. Допустимые значения: `skills`, `agents`, `hooks`, `mcp`, `lsp`, `output-style`, `channel` | |
1093| `-f, --force` | Перезаписать существующий `.claude-plugin/` в целевом месте | |
1094| `-h, --help` | Показать справку по команде | |
1095
1096`claude plugin new` является псевдонимом для этой команды.
1097
1098Каждое значение `--with` добавляет стартовый файл для этого компонента, готовый к редактированию:
1099
1100| Компонент | Что создаётся |
1101| :------------- | :---------------------------------------------------------------------------------------------------- |
1102| `skills` | Дополнительный навык с пространством имён `<name>:example` рядом с навыком по умолчанию |
1103| `agents` | Определение подагента `agents/` |
1104| `hooks` | `hooks/hooks.json` с примером обработчика события |
1105| `mcp` | `.mcp.json` с примерами HTTP и stdio серверов |
1106| `lsp` | Пример языкового сервера `.lsp.json` |
1107| `output-style` | `output-styles/<name>.md`, который применяется автоматически, пока плагин включен |
1108| `channel` | Основанный на MCP [канал](/docs/ru/channels): stdio сервер (`server.ts`), его `.mcp.json` и `package.json` |
1109
1110Созданный плагин использует источник `@skills-dir` вместо маркетплейса. Администраторы могут заблокировать этот источник с помощью `strictKnownMarketplaces` или добавив `{"source": "skills-dir"}` в `blockedMarketplaces` в [управляемых параметрах](/docs/ru/plugin-marketplaces#managed-marketplace-restrictions). При блокировке `plugin init` завершается с ошибкой перед записью.
1111
1112Эти примеры показывают распространённые вызовы:
1113
1114```bash theme={null}
1115# Создать минимальный плагин
1116claude plugin init my-helper
1117
1118# Создать с папками навыков и hooks
1119claude plugin init my-helper --with skills hooks
1120
1121# Перезаписать существующий скаффолд
1122claude plugin init my-helper --force
1123```
1124
1125<h3 id="plugin-install">
1126 plugin install
1127</h3>
1128
1129Установите плагин из доступных маркетплейсов.
1130
1131```bash theme={null}
1132claude plugin install <plugin> [options]
1133```
1134
1135Команда принимает эти аргументы:
1136
1137* `<plugin>`: Имя плагина или `plugin-name@marketplace-name` для конкретного маркетплейса
1138
1139Команда принимает эти опции:
1140
1141| Опция | Описание | По умолчанию |
1142| :-------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------- |
1143| `-s, --scope <scope>` | Область установки: `user`, `project` или `local` | `user` |
1144| `--config <key=value>` | Установить опцию [`userConfig`](#user-configuration), объявленную в манифесте плагина. Повторите флаг для установки нескольких опций | |
1145| `-y, --yes` | Принять команду, которую объявляет маркетплейс плагина, без подтверждения: команду, которая создаёт плагин с [источником `command`](/docs/ru/plugin-marketplaces#command-sources), или [`headersHelper`](/docs/ru/plugin-marketplaces#authenticate-archive-downloads), который аутентифицирует загрузку архива. Принятие `headersHelper` требует Claude Code v2.1.238 или позже. Claude Code всё равно выводит команду первой. Требуется, когда stdin или stdout не является TTY, если вы не передаёте `--accept-command`. Не имеет эффекта внутри сессии Claude Code, поэтому запустите команду из вашего собственного терминала | |
1146| `--accept-command <sha256>` | Принять объявленную маркетплейсом команду, чей `sha256` предыдущий запуск [`--json`](#plugin-json-result) сообщил в `shownCommand`, вместо `-y`. Принятие считается ровно для этой команды, плагина и каталога маркетплейса. Если любой из них изменился с момента отображения команды, включая через собственный запуск маркетплейса, Claude Code не принимает дайджест и показывает команду снова. Не может быть объединено с `-y`. Не имеет эффекта внутри сессии Claude Code, поэтому запустите команду из вашего собственного терминала. Требует Claude Code v2.1.271 или позже | |
1147| `--json` | Вывести результат как один объект JSON на последней строке stdout вместо удобочитаемого сообщения для использования в скриптах. См. [Формат результата JSON](#plugin-json-result). Требует Claude Code v2.1.268 или позже | |
1148| `-h, --help` | Показать справку по команде | |
1149
1150Область определяет, в какой файл параметров добавляется установленный плагин. Например, `--scope project` записывает в `enabledPlugins` в .claude/settings.json, делая плагин доступным для всех, кто клонирует репозиторий проекта.
1151
1152<span id="plugin-json-result" />С `--json` последняя строка stdout — это один объект JSON. Разбирайте только эту строку, потому что Claude Code выводит любую команду, которую объявляет маркетплейс, перед ней. Три поля всегда присутствуют:
1153
1154* `command`: подкоманда, которая была запущена, например `install`
1155* `outcome`: `ok` или `failed`
1156* `message`: удобочитаемое описание результата
1157
1158Другие поля, такие как `pluginId`, `scope` и `failureCode`, появляются только когда они применимы. Опция `--json` на `plugin uninstall`, `plugin update`, `plugin enable` и `plugin disable` выводит тот же объект с собственными полями этой подкоманды. Ошибка использования, такая как недопустимый `--scope`, не выводит строку результата и выходит с кодом 1 с причиной на stderr.
1159
1160Когда запуск отображает объявленную маркетплейсом команду и не запускает её, результат `failed` также содержит объект `shownCommand`, чьи поля включают команду как отображённую, плагин, к которому она принадлежит, и `sha256` команды. Чтобы принять ровно эту команду, повторно запустите с этим `sha256` как `--accept-command`. Требует Claude Code v2.1.271 или позже.
1161
1162Если `shownCommand.acceptCommandMatched` равно `false`, дайджест, который вы передали, не совпадает с командой, которая сейчас отображается. Покажите эту команду человеку перед передачей её `sha256`.
1163
1164Эти примеры показывают распространённые вызовы:
1165
1166```bash theme={null}
1167# Установить в область пользователя (по умолчанию)
1168claude plugin install formatter@my-marketplace
1169
1170# Установить в область проекта (общее с командой)
1171claude plugin install formatter@my-marketplace --scope project
1172
1173# Установить в локальную область (не общее с командой)
1174claude plugin install formatter@my-marketplace --scope local
1175```
1176
1177<h3 id="plugin-uninstall">
1178 plugin uninstall
1179</h3>
1180
1181Удалите установленный плагин.
1182
1183```bash theme={null}
1184claude plugin uninstall <plugin> [options]
1185```
1186
1187Команда принимает эти аргументы:
1188
1189* `<plugin>`: Имя плагина или `plugin-name@marketplace-name`
1190
1191Команда принимает эти опции:
1192
1193| Опция | Описание | По умолчанию |
1194| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------- |
1195| `-s, --scope <scope>` | Удалить из области: `user`, `project` или `local` | `user` |
1196| `--keep-data` | Сохранить [каталог постоянных данных](#persistent-data-directory) плагина | |
1197| `--prune` | Также удалить автоматически установленные зависимости, которые не требуются другим плагинам. См. [plugin prune](#plugin-prune) | |
1198| `-y, --yes` | Пропустить подтверждение `--prune`. Требуется, когда stdin или stdout не является TTY | |
1199| `--json` | Вывести результат как один объект JSON на последней строке stdout в [том же формате, что и `plugin install --json`](#plugin-json-result). Не может быть объединено с `--prune`. Требует Claude Code v2.1.268 или позже | |
1200| `-h, --help` | Показать справку по команде | |
1201
1202`claude plugin remove` и `claude plugin rm` являются псевдонимами для этой команды.
1203
1204По умолчанию удаление из последней оставшейся области также удаляет каталог `${CLAUDE_PLUGIN_DATA}` плагина. Используйте `--keep-data` для сохранения, например при переустановке после тестирования новой версии.
1205
1206<Note>
1207 Когда установленные плагины из разных маркетплейсов имеют одно имя, форма `plugin-name@marketplace-name` удаляет только плагин из названного маркетплейса. До v2.1.212 квалифицированная форма могла совпадать и удалять одноимённый плагин из другого маркетплейса.
1208</Note>
1209
1210<h3 id="plugin-prune">
1211 plugin prune
1212</h3>
1213
1214Удалите автоматически установленные зависимости плагинов, которые больше не требуются ни одним установленным плагином. Зависимости, которые Claude Code подтянул для удовлетворения поля [`dependencies`](/docs/ru/plugin-dependencies) другого плагина, удаляются; плагины, которые вы установили напрямую, никогда не трогаются.
1215
1216```bash theme={null}
1217claude plugin prune [options]
1218```
1219
1220Команда принимает эти опции:
1221
1222| Опция | Описание | По умолчанию |
1223| :-------------------- | :-------------------------------------------------------------------------- | :----------- |
1224| `-s, --scope <scope>` | Очистить в области: `user`, `project` или `local` | `user` |
1225| `--dry-run` | Список того, что будет удалено, без фактического удаления | |
1226| `-y, --yes` | Пропустить подтверждение. Требуется, когда stdin или stdout не является TTY | |
1227| `-h, --help` | Показать справку по команде | |
1228
1229`claude plugin autoremove` является псевдонимом для этой команды.
1230
1231Команда выводит список сиротских зависимостей и запрашивает подтверждение перед их удалением. Чтобы удалить плагин и очистить его зависимости в один шаг, запустите `claude plugin uninstall <plugin> --prune`.
1232
1233<h3 id="plugin-enable">
1234 plugin enable
1235</h3>
1236
1237Включите отключённый плагин. Когда целевой плагин установлен из маркетплейса и объявляет [зависимости](/docs/ru/plugin-dependencies), Claude Code включает их транзитивно в той же области. Команда завершается с ошибкой при условиях, которые перечисляет [Enable or disable a plugin with dependencies](/docs/ru/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies).
1238
1239```bash theme={null}
1240claude plugin enable <plugin> [options]
1241```
1242
1243Команда принимает эти аргументы:
1244
1245* `<plugin>`: Имя плагина, `plugin-name@marketplace-name` или `plugin-name@synced` для [плагина, синхронизированного из claude.ai](#synced-plugins)
1246
1247Команда принимает эти опции:
1248
1249| Опция | Описание | По умолчанию |
1250| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------- |
1251| `-s, --scope <scope>` | Область для включения: `user`, `project` или `local`. Если опущено, Claude Code определяет область, где установлен плагин | Автоопределение |
1252| `--json` | Вывести результат как один объект JSON на последней строке stdout в [том же формате, что и `plugin install --json`](#plugin-json-result). Требует Claude Code v2.1.268 или позже | |
1253| `-h, --help` | Показать справку по команде | |
1254
1255<h3 id="plugin-disable">
1256 plugin disable
1257</h3>
1258
1259Отключите плагин без его удаления.
1260
1261Когда целевой плагин установлен из маркетплейса, команда завершается с ошибкой, если другой включённый плагин [зависит от](/docs/ru/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies) него. Сообщение об ошибке включает цепочку команд, которая сначала отключает каждый зависимый плагин.
1262
1263Для [синхронизированного плагина](#synced-plugins), который требует ваша организация, команда завершается с ошибкой и ничего не сохраняет.
1264
1265```bash theme={null}
1266claude plugin disable [plugin] [options]
1267```
1268
1269Команда принимает эти аргументы:
1270
1271* `[plugin]`: Имя плагина, `plugin-name@marketplace-name` или `plugin-name@synced` для [плагина, синхронизированного из claude.ai](#synced-plugins). Опционально при использовании `--all`
1272
1273Команда принимает эти опции:
1274
1275| Опция | Описание | По умолчанию |
1276| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------- |
1277| `-a, --all` | Отключить все включённые плагины. Не может быть объединено с `--scope` | |
1278| `-s, --scope <scope>` | Область для отключения: `user`, `project` или `local`. Если опущено, Claude Code определяет область, где установлен плагин | Автоопределение |
1279| `--json` | Вывести результат как один объект JSON на последней строке stdout в [том же формате, что и `plugin install --json`](#plugin-json-result). Требует Claude Code v2.1.268 или позже | |
1280| `-h, --help` | Показать справку по команде | |
1281
1282<h3 id="plugin-update">
1283 plugin update
1284</h3>
1285
1286Обновите плагин до последней версии.
1287
1288```bash theme={null}
1289claude plugin update <plugin> [options]
1290```
1291
1292Команда принимает эти аргументы:
1293
1294* `<plugin>`: Имя плагина или `plugin-name@marketplace-name`
1295
1296Команда принимает эти опции:
1297
1298| Опция | Описание | По умолчанию |
1299| :-------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------- |
1300| `-s, --scope <scope>` | Область для обновления: `user`, `project`, `local` или `managed` | `user` |
1301| `-y, --yes` | Принять команду, которую объявляет маркетплейс плагина, без подтверждения: команду, которая создаёт плагин с [источником `command`](/docs/ru/plugin-marketplaces#command-sources), или [`headersHelper`](/docs/ru/plugin-marketplaces#authenticate-archive-downloads), который аутентифицирует загрузку архива. Принятие `headersHelper` требует Claude Code v2.1.238 или позже. Claude Code всё равно выводит команду первой. Требуется, когда stdin или stdout не является TTY, если вы не передаёте `--accept-command`. Не имеет эффекта внутри сессии Claude Code, поэтому запустите команду из вашего собственного терминала | |
1302| `--accept-command <sha256>` | Принять объявленную маркетплейсом команду, чей `sha256` предыдущий запуск [`--json`](#plugin-json-result) сообщил в `shownCommand`, вместо `-y`. Принятие считается ровно для этой команды, плагина и каталога маркетплейса. Если любой из них изменился с момента отображения команды, включая через собственный запуск маркетплейса, Claude Code не принимает дайджест и показывает команду снова. Не может быть объединено с `-y`. Не имеет эффекта внутри сессии Claude Code, поэтому запустите команду из вашего собственного терминала. Требует Claude Code v2.1.271 или позже | |
1303| `--json` | Вывести результат как один объект JSON на последней строке stdout в [том же формате, что и `plugin install --json`](#plugin-json-result). Требует Claude Code v2.1.268 или позже | |
1304| `-h, --help` | Показать справку по команде | |
1305
1306<Note>
1307 Claude Code разрешает имя плагина без квалификации в отношении установленных плагинов. Когда установленные плагины из разных маркетплейсов имеют одно имя, Claude Code отказывает в обновлении и выводит квалифицированные команды `plugin-name@marketplace-name` для запуска вместо этого. До v2.1.246 Claude Code принимал только квалифицированную форму и отклонял имя без квалификации как не найденное.
1308</Note>
1309
1310***
1311
1312<h3 id="plugin-list">
1313 plugin list
1314</h3>
1315
1316Выведите список установленных плагинов с их версией, исходным маркетплейсом и статусом включения.
1317
1318```bash theme={null}
1319claude plugin list [options]
1320```
1321
1322Команда принимает эти опции:
1323
1324| Опция | Описание | По умолчанию |
1325| :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------- |
1326| `--json` | Вывести как JSON. Строка плагина с проблемами загрузки или предупреждениями авторства содержит массивы строк `errors` или `notes`. На Claude Code v2.1.268 или позже параллельные массивы `errorDetails` и `noteDetails` дают каждой записи диагностический `type` и названия, на которые она ссылается, такие как плагин, маркетплейс, сервер или файл | |
1327| `--available` | Включить доступные плагины из маркетплейсов. Требует `--json` | |
1328| `-h, --help` | Показать справку по команде | |
1329
1330В интерактивной сессии `/plugin list` выводит похожий список встроенным образом, но охватывает только плагины, установленные из маркетплейса:
1331
1332* Плагины, загруженные из каталогов навыков, появляются в интерфейсе `/plugin` и в `claude plugin list`, но не в выводе встроенного `/plugin list`.
1333* [Плагины, синхронизированные из claude.ai](#synced-plugins) появляются в `claude plugin list` на Claude Code v2.1.239 или позже и в интерфейсе `/plugin`, но не в выводе встроенного `/plugin list`.
1334* Плагины, загруженные для сессии с `--plugin-dir` или `--plugin-url`, появляются в интерфейсе `/plugin` и в `claude plugin list` только когда тот же флаг предшествует подкоманде, как в `claude --plugin-dir <dir> plugin list`. Только имя флага указывает их местоположение, поэтому простой `claude plugin list` не может их найти, в отличие от синхронизированных плагинов и плагинов из каталога навыков, чьи фиксированные каталоги сканирует Claude Code.
1335
1336Интерактивная форма принимает `--enabled` или `--disabled` для отображения только плагинов в этом состоянии и `ls` как сокращение для `list`.
1337
1338<h3 id="plugin-details">
1339 plugin details
1340</h3>
1341
1342Показать инвентарь компонентов плагина и прогнозируемую стоимость в токенах. Вывод выводит список всех компонентов, которые вносит плагин, сгруппированных как Skills, Agents, Hooks, MCP серверы и LSP серверы, вместе с оценкой того, сколько токенов он добавляет к каждой сессии. Группа Skills включает записи как `skills/`, так и `commands/`.
1343
1344```bash theme={null}
1345claude plugin details <name>
1346```
1347
1348Команда принимает эти аргументы:
1349
1350* `<name>`: Имя плагина или `plugin-name@marketplace-name`
1351
1352Команда принимает эти опции:
1353
1354| Опция | Описание | По умолчанию |
1355| :----------- | :-------------------------- | :----------- |
1356| `-h, --help` | Показать справку по команде | |
1357
1358Вывод показывает две цифры стоимости для каждого компонента:
1359
1360* **Always-on:** токены, добавляемые к каждой сессии текстом списка плагина, такие как описания навыков, описания агентов и имена команд, независимо от того, срабатывает ли какой-либо компонент.
1361* **On-invoke:** токены, которые стоит компонент при срабатывании. Показано для каждого компонента отдельно, а не как итог плагина, потому что типичная сессия вызывает только подмножество компонентов.
1362
1363Этот пример показывает, как выглядит вывод для плагина с двумя навыками:
1364
1365```
1366dependency-guard 1.2.0
1367 Dependency analysis for Claude Code sessions
1368 Source: dependency-guard@example-marketplace
1369
1370Component inventory
1371 Skills (2) scan-dependencies, review-changes
1372 Agents (0)
1373 Hooks (1) SessionStart (harness-only — no model context cost)
1374 MCP servers (0)
1375 LSP servers (0)
1376
1377Projected token cost
1378 Always-on: ~180 tok added to every session
1379
1380Per-component (rounded)
1381 component always-on on-invoke
1382 scan-dependencies ~100 ~2400
1383 review-changes ~80 ~1800
1384
1385 On-invoke cost is paid each time a skill or agent fires.
1386 Token counts are estimates and may differ from actual usage.
1387```
1388
1389Итог always-on вычисляется через API `count_tokens` для вашей активной модели. Числа для каждого компонента пропорционально масштабируются от этого итога. Если API недоступен, команда возвращается к оценке на основе символов.
1390
1391<h3 id="plugin-validate">
1392 plugin validate
1393</h3>
1394
1395Проверьте плагин или маркетплейс на синтаксические и схемные ошибки перед публикацией.
1396
1397Команда выходит с кодом 0 при успешной валидации, 1 при неудаче и 2 при неудаче самого запуска валидации, например когда переданный путь нечитаем.
1398
1399```bash theme={null}
1400claude plugin validate <path> [options]
1401```
1402
1403Команда принимает эти аргументы:
1404
1405* `<path>`: Путь к каталогу плагина или каталогу маркетплейса. См. [Validate a plugin or a directory without a manifest](/docs/ru/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest) для того, какие файлы охватывает запуск плагина.
1406
1407Команда принимает эти опции:
1408
1409| Опция | Описание | По умолчанию |
1410| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------- |
1411| `--strict` | Рассматривать предупреждения как ошибки и выходить с кодом 1 при них. Используйте в CI для перехвата проблем, которые допускает среда выполнения, такие как [unrecognized fields](#unrecognized-fields) | |
1412| `--json` | Вывести отчёт валидации как один объект JSON с теми же кодами выхода. Требует Claude Code v2.1.259 или позже | |
1413| `-h, --help` | Показать справку по команде | |
1414
1415С `--json` Claude Code записывает отчёт в stdout как один объект JSON с этими полями верхнего уровня:
1416
1417* `success`: тот же вердикт, который даёт код выхода
1418* `strict`: рассматривала ли запуск предупреждения как ошибки
1419* `target`: разрешённый путь, который Claude Code валидировал
1420* `manifest`: собственный результат манифеста или `null` для [запуска без манифеста](/docs/ru/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest)
1421* `contents`: результаты для каждого файла, каждый называет свой `file` и несёт массивы `errors`, `warnings` и `notes`
1422
1423При выходе с кодом 2 команда ничего не записывает в stdout; сообщение об ошибке идёт в stderr.
1424
1425В интерактивной сессии `/plugin validate <path>` запускает те же проверки встроенным образом.
1426
1427<h3 id="plugin-eval">
1428 plugin eval
1429</h3>
1430
1431Запустите [eval cases](/docs/ru/plugin-evals) плагина и выведите оценённые результаты. Требует Claude Code v2.1.269 или позже. Каждый случай — это подсказка плюс оценщики; Claude Code запускает его несколько раз в изолированной сессии только с целевым плагином загруженным, и по умолчанию также без плагина, чтобы отчёт показал разницу. См. [Test plugins with evals](/docs/ru/plugin-evals) для формата случаев, оценщиков, результатов и использования в CI.
1432
1433```bash theme={null}
1434claude plugin eval [target] [options]
1435```
1436
1437Опциональный `target` — это каталог плагина, один файл `prompt.md` или `case.yaml`, установленный плагин как `name` или `name@marketplace`, или `name@skills-dir`, и по умолчанию текущий каталог. Поместите его перед `--tag`, `--allow-tools` и `--json`.
1438
1439Эта таблица выводит опции, которые используют большинство запусков. Запустите `claude plugin eval --help` для полного набора, включая `--case`, `--tag`, `--output-dir`, `--report`, `--allow-real-servers`, `--keep-temp` и `--verbose`.
1440
1441| Опция | Описание | По умолчанию |
1442| :------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------- |
1443| `--runs <n>` | Запусков на случай на ветвь | Каждого случая `runs`, иначе 3 |
1444| `-j, --concurrency <n>` | Сессии агентов для запуска одновременно, от 1 до 8. Они делят ваш лимит скорости | `1` |
1445| `--model <model>` | Модель для тестируемого агента | Каждого случая `model`, иначе `ANTHROPIC_MODEL` если установлено, иначе по умолчанию Claude Code |
1446| `--judge-model <model>` | Модель для оценщиков `llm` и `baseline` | Маленькая быстрая модель |
1447| `--ablation <mode>` | `none` или `with-without`. См. [Compare against a no-plugin baseline](/docs/ru/plugin-evals#compare-against-a-no-plugin-baseline) | `with-without` когда плагин разрешается, иначе `none` |
1448| `--threshold <0..1>` | Выход 1 если какой-либо случай оценивается ниже этого | `1.0` |
1449| `--max-cost-usd <usd>` | Остановиться перед следующим запуском после достижения расходов этого, выход 2 и вывести частичные результаты | Нет потолка |
1450| `--allow-tools <tools...>` | Предоставить инструменты сверх набора только для чтения, такие как `Bash`, `Write`, `Edit` или `"mcp__plugin_<plugin>_<server>__*"`. См. [Grant tools](/docs/ru/plugin-evals#grant-tools) | |
1451| `--scaffold` | Запустить [`scaffold_script`](/docs/ru/plugin-evals#add-setup-or-history-with-case-yaml) каждого случая | Выключено |
1452| `--trust-plugin` | Пропустить подсказку доверия при первом запуске, для CI. См. [What a run can access](/docs/ru/plugin-evals#security) | Выключено |
1453| `--mocks <mode>` | `record` или `off`. См. [Mock MCP servers](/docs/ru/plugin-evals#mock-mcp-servers) | `record` |
1454| `--eval-dir <dir>` | Каталог ниже плагина, который содержит случаи | `experimental.evals` манифеста, иначе `evals` |
1455| `--json [path]` | Вывести [документ результата](/docs/ru/plugin-evals#json-result) в stdout или записать его в путь `.json` | |
1456| `--no-publish` | Держать отчёт HTML локально | |
1457| `-h, --help` | Показать справку по команде | |
1458
1459Команда выходит с кодом 0 когда каждый случай соответствует пороговому значению, 1 при неудачном случае, ошибке загрузки или недоверенном каталоге плагина, 2 при частичном запуске, 130 при прерывании и 143 при завершении. См. [Run evals in CI](/docs/ru/plugin-evals#run-evals-in-ci).
1460
1461<h3 id="plugin-eval-init">
1462 plugin eval init
1463</h3>
1464
1465Создайте набор eval для плагина в текущем каталоге. Требует Claude Code v2.1.269 или позже. В терминале это запускает интервью по авторству, которое читает плагин, предлагает случаи и оценщики, пилотирует их и записывает файлы. С `--bare` или без терминала, оно записывает пустой шаблон одного случая вместо этого. Запустите из интерактивной сессии Claude Code, оно выводит инструкции интервью для этой сессии, чтобы следовать, а не записывать шаблон. См. [Create your first eval suite](/docs/ru/plugin-evals#create-your-first-eval-suite).
1466
1467```bash theme={null}
1468claude plugin eval init [name] [options]
1469```
1470
1471Опциональный `name` — это имя случая: интервью не нуждается в нём, в то время как `--bare` и путь шаблона без терминала требуют его. Он принимает эти опции:
1472
1473| Опция | Описание | По умолчанию |
1474| :------------------ | :--------------------------------------------------------------------------------------- | :-------------------------------------------- |
1475| `--bare` | Записать пустой `prompt.md` и `graders/criteria.md` для `<name>` вместо запуска интервью | |
1476| `-i, --interactive` | Требовать интервью. Завершается с ошибкой без терминала вместо записи шаблона | |
1477| `--eval-dir <dir>` | Каталог ниже текущего каталога для записи случаев в | `experimental.evals` манифеста, иначе `evals` |
1478| `-h, --help` | Показать справку по команде | |
1479
1480<h3 id="plugin-tag">
1481 plugin tag
1482</h3>
1483
1484Создайте тег выпуска git для плагина. По умолчанию команда помечает плагин в текущем каталоге; передайте путь для пометки плагина в другом месте. См. [Tag plugin releases](/docs/ru/plugin-dependencies#tag-plugin-releases-for-version-resolution).
1485
1486```bash theme={null}
1487claude plugin tag [path] [options]
1488```
1489
1490Команда принимает эти аргументы:
1491
1492* `[path]`: Путь к каталогу плагина. По умолчанию текущий каталог.
1493
1494Команда принимает эти опции:
1495
1496| Опция | Описание | По умолчанию |
1497| :-------------------- | :-------------------------------------------------------------------- | :----------- |
1498| `--push` | Отправить тег на удалённый репозиторий после создания | |
1499| `--dry-run` | Вывести то, что будет помечено, без создания тега | |
1500| `-f, --force` | Создать тег даже если рабочее дерево грязное или тег уже существует | |
1501| `-m, --message <msg>` | Сообщение аннотации тега. Используйте `%s` как заполнитель для версии | |
1502| `--remote <name>` | Удалённый репозиторий для отправки с `--push` | `origin` |
1503| `-h, --help` | Показать справку по команде | |
1504
1505***
1506
1507<h2 id="debugging-and-development-tools">
1508 Инструменты отладки и разработки
1509</h2>
1510
1511<h3 id="debugging-commands">
1512 Команды отладки
1513</h3>
1514
1515Используйте `claude --debug` для просмотра деталей загрузки плагинов:
1516
1517Это показывает:
1518
1519* Какие плагины загружаются
1520* Любые ошибки в манифестах плагинов
1521* Регистрацию skills, agents и hooks
1522* Инициализацию MCP сервера
1523
1524<h3 id="common-issues">
1525 Распространённые проблемы
1526</h3>
1527
1528| Проблема | Причина | Решение |
1529| :---------------------------------- | :---------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1530| Плагин не загружается | Неверный `plugin.json` | Запустите `claude plugin validate ./my-plugin` или `/plugin validate ./my-plugin`, где `./my-plugin` — это директория вашего плагина, чтобы проверить `plugin.json`, `hooks/hooks.json` и frontmatter skills, agents и commands в директориях плагина по умолчанию на синтаксические и схемные ошибки. См. [Validate a plugin or a directory without a manifest](/docs/ru/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest) для информации о том, что охватывает запуск |
1531| Skills не отображаются | Неправильная структура директории | Убедитесь, что `skills/` или `commands/` находится в корне плагина, а не внутри `.claude-plugin/` |
1532| Hooks не срабатывают | Скрипт не исполняемый | Запустите `chmod +x script.sh` |
1533| MCP сервер не работает | Отсутствует `${CLAUDE_PLUGIN_ROOT}` | Используйте переменную для всех путей плагина |
1534| Ошибки пути | Используются абсолютные пути | Сделайте пути относительными, начиная с `./`; см. [Path behavior rules](#path-behavior-rules), которые охватывают исключение `"."` в поле `skills` |
1535| LSP `Executable not found in $PATH` | Языковой сервер не установлен | Установите бинарный файл (например, `npm install -g typescript-language-server typescript`) |
1536
1537<h3 id="example-error-messages">
1538 Примеры сообщений об ошибках
1539</h3>
1540
1541**Ошибки валидации манифеста**:
1542
1543* `Invalid JSON syntax: Unexpected token } in JSON at position 142`: проверьте наличие пропущенных запятых, лишних запятых или неэкранированных строк
1544* `Plugin <name> has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Invalid input: expected string, received undefined`: отсутствует обязательное поле
1545* `Plugin <name> has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...`: ошибка синтаксиса JSON. До версии 2.1.246 Claude Code также выдавал эту ошибку для `plugin.json`, сохранённого как UTF-8 с начальной меткой порядка байтов (BOM), даже когда JSON был в остальном корректным.
1546
1547**Ошибки загрузки плагина**:
1548
1549* `Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.`: путь команды существует, но не содержит корректных файлов команд
1550* `Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.`: путь `source` в marketplace.json указывает на несуществующую директорию
1551* `Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.`: удалите дублирующиеся определения компонентов или удалите `strict: false` в записи marketplace
1552
1553<h3 id="hook-troubleshooting">
1554 Устранение неполадок hooks
1555</h3>
1556
1557**Скрипт hook не выполняется**:
1558
15591. Проверьте, что скрипт исполняемый: `chmod +x ./scripts/your-script.sh`
15602. Проверьте строку shebang: первая строка должна быть `#!/bin/bash` или `#!/usr/bin/env bash`
15613. Проверьте, что путь использует `${CLAUDE_PLUGIN_ROOT}`: `"command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/your-script.sh"`
15624. Протестируйте скрипт вручную: `./scripts/your-script.sh`
1563
1564**Hook не срабатывает на ожидаемых событиях**:
1565
15661. Проверьте, что имя события правильное (чувствительно к регистру): `PostToolUse`, а не `postToolUse`
15672. Проверьте, что шаблон matcher соответствует вашим инструментам: `"matcher": "Write|Edit"` для файловых операций
15683. Подтвердите, что тип hook корректен: `command`, `http`, `mcp_tool`, `prompt` или `agent`
1569
1570<h3 id="mcp-server-troubleshooting">
1571 Устранение неполадок MCP сервера
1572</h3>
1573
1574**Сервер не запускается**:
1575
15761. Проверьте, что команда существует и исполняемая
15772. Проверьте, что все пути используют переменную `${CLAUDE_PLUGIN_ROOT}`
15783. Проверьте логи MCP сервера: `claude --debug` показывает ошибки инициализации
15794. Протестируйте сервер вручную вне Claude Code
1580
1581**Инструменты сервера не отображаются**:
1582
15831. Убедитесь, что сервер правильно настроен в `.mcp.json` или `plugin.json`
15842. Проверьте, что сервер правильно реализует протокол MCP
15853. Проверьте наличие таймаутов соединения в выводе отладки
1586
1587<h3 id="directory-structure-mistakes">
1588 Ошибки структуры директории
1589</h3>
1590
1591**Симптомы**: плагин загружается, но компоненты (skills, agents, hooks) отсутствуют.
1592
1593**Правильная структура**: компоненты должны находиться в корне плагина, а не внутри `.claude-plugin/`. Только `plugin.json` должен находиться в `.claude-plugin/`.
1594
1595**Контрольный список отладки**:
1596
15971. Запустите `claude --debug` и ищите сообщения "loading plugin"
15982. Проверьте, что каждая директория компонента указана в выводе отладки
15993. Проверьте, что разрешения файлов позволяют читать файлы плагина
1600
1601***
1602
1603<h2 id="distribution-and-versioning-reference">
1604 Справочник по распределению и версионированию
1605</h2>
1606
1607<h3 id="version-management">
1608 Управление версиями
1609</h3>
1610
1611Claude Code использует версию плагина в качестве ключа кэша, который определяет, доступно ли обновление. Когда вы запускаете `/plugin update` или срабатывает автоматическое обновление, Claude Code вычисляет текущую версию и пропускает обновление, если она совпадает с уже установленной. Плагин [загруженный на месте](#plugin-caching-and-file-resolution) из локального каталога marketplace загружает свои текущие исходные файлы при каждом запуске сеанса, независимо от того, что говорит его строка версии.
1612
1613Для каждого типа источника, кроме `command`, Claude Code разрешает версию из первого из следующих установленных параметров:
1614
16151. Поле `version` в `plugin.json` плагина
16162. Поле `version` в записи плагина на marketplace в `marketplace.json`
16173. SHA коммита git источника плагина для источников `github`, `url`, `git-subdir` и relative-path в marketplace, размещённом на git
16184. Дайджест SHA-256 для [`archive` источников](/docs/ru/plugin-marketplaces#zip-archives): пин `sha256` в записи marketplace или дайджест загруженного файла, когда вы не устанавливаете пин. Claude Code сокращает его до первых 12 символов
16195. `unknown` для источников `npm` или локальных каталогов, не находящихся в репозитории git. Claude Code не берёт версию из репозитория, который охватывает путь установки, такого как управляемый git `~/.claude`
1620
1621Для [`command` источника](/docs/ru/plugin-marketplaces#command-sources) Claude Code всегда выводит версию из того, что произвёл команда: 12-символный хеш содержимого самостоятельно или добавленный к версии `plugin.json` как `<version>-<hash>`, когда он установлен. Claude Code игнорирует поле `version` записи marketplace для источников command. Команда, чей хешированный вывод изменяется, поэтому создаёт новую версию, даже когда строка авторской версии остаётся той же. В [режиме ссылки](/docs/ru/plugin-marketplaces#copy-mode-and-link-mode) хеш охватывает реальный путь напечатанного каталога и его записи верхнего уровня, а не содержимое файла.
1622
1623Для этих типов источников это даёт вам три способа версионирования плагина:
1624
1625| Подход | Как | Поведение обновления | Лучше всего для |
1626| :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------- |
1627| **Явная версия** | Установите `"version": "2.1.0"` в `plugin.json` | Пользователи получают обновления только при изменении этого поля. Отправка новых коммитов без изменения этого поля не имеет эффекта, и `/plugin update` сообщает "already at the latest version". Для плагина [загруженного на месте](#plugin-caching-and-file-resolution) новое содержимое загружается в любом случае. | Опубликованные плагины со стабильными циклами выпуска |
1628| **Версия Commit-SHA** | Опустите `version` из `plugin.json` и записи marketplace | Пользователи получают обновления всякий раз, когда изменяется разрешённый коммит источника | Внутренние или командные плагины в активной разработке |
1629| **Версия Digest** | Используйте [`archive` источник](/docs/ru/plugin-marketplaces#zip-archives) и опустите `version` из `plugin.json` и записи marketplace | С пином `sha256` пользователи получают обновления при изменении пина. Без него пользователи получают обновления всякий раз, когда изменяются байты размещённого zip-файла | Плагины, опубликованные как zip-файлы на статическом сервере или репозитории артефактов |
1630
1631Если вы используете явные версии, следуйте [семантическому версионированию](https://semver.org) (`MAJOR.MINOR.PATCH`): увеличивайте MAJOR для критических изменений, MINOR для новых функций, PATCH для исправлений ошибок. Документируйте изменения в `CHANGELOG.md`.
1632
1633***
1634
1635<h2 id="see-also">
1636 Смотрите также
1637</h2>
1638
1639* [Плагины](/docs/ru/plugins) - Учебные материалы и практическое использование
1640* [Маркетплейсы плагинов](/docs/ru/plugin-marketplaces) - Создание и управление маркетплейсами
1641* [Skills](/docs/ru/skills) - Детали разработки skills
1642* [Subagents](/docs/ru/sub-agents) - Конфигурация и возможности агентов
1643* [Hooks](/docs/ru/hooks) - Обработка событий и автоматизация
1644* [MCP](/docs/ru/mcp) - Интеграция внешних инструментов
1645* [Параметры](/docs/ru/settings) - Опции конфигурации для плагинов