SpyBara
Go Premium

plugins/components.md 2026-09-24 22:57 UTC to 2026-09-25 23:58 UTC

This page contains 1130 additions and 0 deletions.

2026
Fri 25 23:58

Добавление компонентов в плагин

Добавляйте skills, hooks, MCP серверы и все остальные типы компонентов в плагин Claude Code с примерами, которые проходят валидацию для каждого.

export const Piece = ({id, children}) =>

{children}
;

export const PluginExplorer = ({children}) => { const PIECES = [{ id: 'manifest', name: 'Manifest', path: '.claude-plugin/plugin.json', required: "Required by Anthropic's directory", lines: [{ depth: 0, kind: 'folder', text: '.claude-plugin/' }, { depth: 1, kind: 'file', text: 'plugin.json' }], href: '/en/plugins/manifest-reference#manifest-file', linkText: 'Go to the manifest reference' }, { id: 'skills', name: 'Skills', path: 'skills/review/SKILL.md', lines: [{ depth: 0, kind: 'folder', text: 'skills/' }, { depth: 1, kind: 'folder', text: 'review/' }, { depth: 2, kind: 'file', text: 'SKILL.md' }], href: '/en/plugins/components#skills', linkText: 'Go to the Skills section' }, { id: 'commands', name: 'Commands', path: 'commands/about.md', lines: [{ depth: 0, kind: 'folder', text: 'commands/' }, { depth: 1, kind: 'file', text: 'about.md' }], href: '/en/plugins/components#commands', linkText: 'Go to the Commands section' }, { id: 'agents', name: 'Agents', path: 'agents/security-reviewer.md', lines: [{ depth: 0, kind: 'folder', text: 'agents/' }, { depth: 1, kind: 'file', text: 'security-reviewer.md' }], href: '/en/plugins/components#agents', linkText: 'Go to the Agents section' }, { id: 'hooks', name: 'Hooks', path: 'hooks/hooks.json', lines: [{ depth: 0, kind: 'folder', text: 'hooks/' }, { depth: 1, kind: 'file', text: 'hooks.json' }], href: '/en/plugins/components#hooks', linkText: 'Go to the Hooks section' }, { id: 'monitors', name: 'Monitors', path: 'monitors/monitors.json', lines: [{ depth: 0, kind: 'folder', text: 'monitors/' }, { depth: 1, kind: 'file', text: 'monitors.json' }], href: '/en/plugins/components#monitors', linkText: 'Go to the Monitors section' }, { id: 'output-styles', name: 'Output styles', path: 'output-styles/terse.md', lines: [{ depth: 0, kind: 'folder', text: 'output-styles/' }, { depth: 1, kind: 'file', text: 'terse.md' }], href: '/en/plugins/components#themes-and-output-styles', linkText: 'Go to the Themes and output styles section' }, { id: 'themes', name: 'Themes', path: 'themes/dracula.json', lines: [{ depth: 0, kind: 'folder', text: 'themes/' }, { depth: 1, kind: 'file', text: 'dracula.json' }], href: '/en/plugins/components#themes-and-output-styles', linkText: 'Go to the Themes and output styles section' }, { id: 'workflows', name: 'Workflows', path: 'workflows/audit-routes.js', lines: [{ depth: 0, kind: 'folder', text: 'workflows/' }, { depth: 1, kind: 'file', text: 'audit-routes.js' }], href: '/en/workflows#distribute-a-workflow-in-a-plugin', linkText: 'Go to Distribute a workflow in a plugin' }, { id: 'bin', name: 'Executables', path: 'bin/hello-plugin', lines: [{ depth: 0, kind: 'folder', text: 'bin/' }, { depth: 1, kind: 'file', text: 'hello-plugin' }], href: '/en/plugins/components#executables', linkText: 'Go to the Executables section' }, { id: 'scripts', name: 'Scripts', path: 'scripts/format.sh', lines: [{ depth: 0, kind: 'folder', text: 'scripts/' }, { depth: 1, kind: 'file', text: 'format.sh' }], href: '/en/plugins/components#hooks', linkText: 'Go to the Hooks section' }, { id: 'settings', name: 'Default settings', path: 'settings.json', lines: [{ depth: 0, kind: 'file', text: 'settings.json' }], href: '/en/plugins/components#default-settings', linkText: 'Go to the Default settings section' }, { id: 'mcp', name: 'MCP servers', path: '.mcp.json', lines: [{ depth: 0, kind: 'file', text: '.mcp.json' }], href: '/en/plugins/components#mcp-servers', linkText: 'Go to the MCP servers section' }, { id: 'lsp', name: 'LSP servers', path: '.lsp.json', lines: [{ depth: 0, kind: 'file', text: '.lsp.json' }], href: '/en/plugins/components#lsp-servers', linkText: 'Go to the LSP servers section' }]; const [selectedId, setSelectedId] = useState('manifest'); const [isFullscreen, setIsFullscreen] = useState(false); const rootRef = useRef(null); useEffect(() => { const onFsChange = () => setIsFullscreen(!!document.fullscreenElement); document.addEventListener('fullscreenchange', onFsChange); return () => document.removeEventListener('fullscreenchange', onFsChange); }, []); const toggleFullscreen = () => { if (!rootRef.current) return; if (document.fullscreenElement) document.exitFullscreen(); else rootRef.current.requestFullscreen().catch(() => {}); }; const selected = PIECES.find(p => p.id === selectedId) || PIECES[0]; const onTreeKeyDown = e => { const keys = ['ArrowDown', 'ArrowUp', 'Home', 'End']; if (keys.indexOf(e.key) === -1) return; const i = PIECES.findIndex(p => p.id === selectedId); let next = i; if (e.key === 'ArrowDown') next = Math.min(PIECES.length - 1, i + 1); if (e.key === 'ArrowUp') next = Math.max(0, i - 1); if (e.key === 'Home') next = 0; if (e.key === 'End') next = PIECES.length - 1; e.preventDefault(); if (next === i) return; const id = PIECES[next].id; setSelectedId(id); const el = document.getElementById('pe-node-' + id); if (el) el.focus(); }; const FolderIcon = () => ; const FileIcon = () => ; return <div ref={rootRef} className={isFullscreen ? 'pe-root pe-fullscreen not-prose' : 'pe-root not-prose'} data-selected={selected.id}>

  <div className="pe-head">
    <div className="pe-head-text">
      <div className="pe-title">What goes in a plugin</div>
      <div className="pe-sub">This example plugin, <code>my-plugin</code>, has one of every kind of component, each in its default location. Select a file or folder to read what it’s for and see what goes in it.</div>
    </div>
    <button type="button" className="pe-fs-btn" onClick={toggleFullscreen} aria-label={isFullscreen ? 'Exit fullscreen' : 'Fullscreen'} title={isFullscreen ? 'Exit fullscreen' : 'Fullscreen'}>
      {isFullscreen ? '⤡' : '⛶'}
    </button>
  </div>

  <div className="pe-body">
    <div className="pe-tree-pane">
      <div className="pe-caption" id="pe-tree-caption">Plugin directory</div>
      <div role="group" aria-labelledby="pe-tree-caption" onKeyDown={onTreeKeyDown}>
        <div className="pe-rootline"><FolderIcon /><span>my-plugin/</span></div>
        {PIECES.map(p => <button key={p.id} id={'pe-node-' + p.id} type="button" className="pe-node" aria-pressed={p.id === selected.id} aria-label={p.name + ', ' + p.path} onClick={() => setSelectedId(p.id)}>
            {p.lines.map((line, i) => <span key={i} className="pe-line pe-line-tree" style={{
paddingLeft: line.depth * 18 + 'px'

}}> {line.kind === 'folder' ? : } {line.text} {p.required && i === p.lines.length - 1 ? {p.required} : null} )} {p.path} {p.required ? {p.required} : null} )}

    <div className="pe-panel" role="region" aria-labelledby="pe-panel-caption" aria-live="polite" aria-atomic="true">
      <div className="pe-caption" id="pe-panel-caption">Selected piece</div>
      <div className="pe-name">{selected.name}{selected.required ? <span className="pe-req">{selected.required}</span> : null}</div>
      <div className="pe-path">{selected.path}</div>

      <div className="pe-block">{children}</div>

      <a className="pe-link" href={selected.href}>{selected.linkText}</a>
    </div>
  </div>
</div>;

};

Плагин Claude Code строится из компонентов, таких как skills, agents, hooks и MCP серверы. Каждый компонент имеет папку по умолчанию в плагине, необязательный ключ манифеста в .claude-plugin/plugin.json, который заменяет или добавляет к этой папке, и имя, которое видит пользователь. Для полной таблицы полей каждого ключа см. справочник манифеста.

Используйте эту страницу для добавления компонента в плагин, который уже загружается.

После добавления компонента запустите /reload-plugins в работающей сессии или начните новую, чтобы Claude Code загрузил его. Чтобы проверить файл компонента перед загрузкой, запустите claude plugin validate . в вашей оболочке из директории плагина.

Изучите каталог плагинов

Обозреватель показывает пример плагина my-plugin, который содержит по одному компоненту каждого вида в его расположении по умолчанию:

Каждый файл — это наименьший допустимый пример своего формата, предназначенный для демонстрации структуры, а не для практического использования: реальный skill или agent содержит полные инструкции и часто вспомогательные файлы, а реальный hook или монитор выполняет реальную работу. Разделы после обозревателя используют те же файлы в качестве примеров и ссылаются на более полные версии. Выберите файл или папку, чтобы прочитать, для чего она нужна, увидеть, что в ней содержится, и найти раздел, который её описывает.

[Манифест](/docs/ru/plugins/manifest-reference) — это файл `plugin.json` в директории `.claude-plugin/` плагина. Он содержит метаданные плагина и значения `userConfig`, которые Claude Code запрашивает у пользователя. Обязателен только `name`. В этом примере `description` — это текст, который пользователи видят для плагина в `/plugin`, а `version` удерживает пользователей на этой версии, пока вы её не измените:
```json theme={null}
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Review, formatting, and database tools for this team"
}
```
[Skill](/docs/ru/skills) — это файл `SKILL.md`. Сохраняйте каждый skill в отдельной директории в папке `skills/`. Claude читает `description` каждого skill, и когда то, что просит пользователь, совпадает с ней, например, когда пользователь просит Claude проверить pull request, Claude загружает инструкции skill и следует им. Пользователь также может запустить его напрямую как `/my-plugin:review`:
```markdown theme={null}
---
description: Reviews a pull request for style and test coverage. Use when asked to review code.
---

Review the changed files. Report style problems first, then missing tests.
```
Команда — это один файл Markdown, который пользователь запускает по имени. Команды — это более старый формат: skill запускается по имени таким же образом и может также содержать вспомогательные файлы в собственной директории, поэтому пишите новые как skills и сохраняйте `commands/` для файлов, которые у вас уже есть. Этот файл становится `/my-plugin:about` и принимает тот же frontmatter, что и skill:
```markdown theme={null}
---
description: Summarize the repository
---

Summarize what this repository does in three sentences.
```
[Subagent](/docs/ru/sub-agents) — это отдельный помощник с собственными инструкциями и собственным контекстным окном, которому Claude может делегировать задачу и получить результат. Каждый файл Markdown в папке `agents/` определяет один: frontmatter называет его и говорит, когда его использовать, а тело — это его системный prompt. Этот назван `my-plugin:security-reviewer`, и пользователь может вызвать его с помощью `@agent-my-plugin:security-reviewer`:
```markdown theme={null}
---
name: security-reviewer
description: Reviews code changes for security issues. Use after edits to authentication or input handling.
model: sonnet
---

You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.
```
[Hook](/docs/ru/hooks-guide) запускает что-то автоматически в точке жизненного цикла Claude Code, например, после каждого редактирования файла: команду shell, HTTP запрос, вызов инструмента MCP, prompt к модели или subagent. Сохраняйте hooks плагина в `hooks/hooks.json` в корне плагина. Этот запускает `scripts/format.sh` плагина после того, как Claude записывает или редактирует файл:
```json theme={null}
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/format.sh\""
          }
        ]
      }
    ]
  }
}
```
Монитор — это команда shell, которую Claude Code запускает в фоне при запуске сеанса и держит запущенной до его завершения, используя [инструмент Monitor](/docs/ru/tools-reference#monitor-tool). То, что он выводит, достигает Claude как уведомления. Поле `when` может вместо этого запустить его в первый раз, когда запустится названный skill. Этот отслеживает журнал ошибок:
```json theme={null}
[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]
```
Плагин может включать [стили вывода](/docs/ru/output-styles), которые изменяют, как Claude форматирует и формулирует свои ответы. Сохраняйте каждый стиль вывода как `output-styles/.md`. Этот появляется в `/output-style` как `my-plugin:terse`:
```markdown theme={null}
---
name: terse
description: Answer in as few words as possible
keep-coding-instructions: true
---

Keep every reply short. Skip preambles and summaries.
```
Плагин может включать [цветовые темы](/docs/ru/terminal-config#create-a-custom-theme) для интерфейса Claude Code. Сохраняйте каждую тему как `themes/.json`. Этот появляется в `/theme` как `Dracula`, отмеченный как из `my-plugin`:
```json theme={null}
{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555"
  }
}
```
Папка `workflows/` содержит файлы [workflow](/docs/ru/workflows) `.js`: блок `meta`, затем тело скрипта, которое координирует несколько subagents. Этот запускается как `/my-plugin:audit-routes`:
```javascript theme={null}
export const meta = {
  name: 'audit-routes',
  description: 'Audit every route handler for missing auth checks',
}

const found = await agent('List every .ts file under src/routes/.', {
  schema: { type: 'object', required: ['files'], properties: { files: { type: 'array', items: { type: 'string' } } } },
})

const audits = await pipeline(found.files, file =>
  agent(`Audit ${file} for missing authentication checks.`, { label: file }),
)

return audits.filter(Boolean)
```
`bin/` — это способ, которым плагин поставляет инструмент командной строки. Пока плагин включен, Claude Code помещает эту папку в `PATH` shell, в котором он запускает команды, поэтому Claude или инструкции skill могут запустить инструмент по имени без установки пользователем. С этим [исполняемым файлом](#executables) на месте `hello-plugin` — это команда, которую Claude может запустить:
```bash theme={null}
#!/bin/bash
echo "hello from my-plugin"
```
Hook в `hooks/hooks.json` запускает скрипт, и эта папка — это место, где пример его хранит. Имя `scripts/` — это соглашение, а не что-то, что Claude Code ищет: hook указывает на файл по его пути, `${CLAUDE_PLUGIN_ROOT}/scripts/format.sh`. Скрипт форматирования может выглядеть так:
```bash theme={null}
#!/bin/bash
npx prettier --write .
```
`settings.json` в корне плагина содержит [параметры](/docs/ru/settings-reference), которые применяются, пока плагин включен, поэтому плагин может изменить поведение сеанса и не только добавить компоненты. Только два ключа действуют из плагина, [`agent`](/docs/ru/settings-reference#agent) и [`subagentStatusLine`](/docs/ru/settings-reference#subagentstatusline); все остальные ключи отбрасываются. См. [Параметры по умолчанию](#default-settings).
Этот устанавливает `agent`, который запускает основной поток сеанса как собственный agent `security-reviewer` плагина, поэтому системный prompt этого agent, ограничения инструментов и модель применяются ко всему сеансу:

```json theme={null}
{
  "agent": "security-reviewer"
}
```
[MCP сервер](/docs/ru/mcp) предоставляет Claude инструменты из внешней системы. Объявите его в `.mcp.json` в корне плагина. Этот запускает локальный сервер из скрипта внутри плагина и появляется в `/mcp` как `plugin:my-plugin:db`:
```json theme={null}
{
  "mcpServers": {
    "db": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  }
}
```
LSP сервер предоставляет Claude [диагностику и навигацию по коду](/docs/ru/plugins/code-intelligence) для языка. Объявите сервер в `.lsp.json` в корне плагина. Этот подключает языковой сервер Go для файлов `.go`:
```json theme={null}
{
  "gopls": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}
```

Добавление каждого вида компонента

Каждый раздел ниже охватывает один вид компонента: где его файлы находятся в плагине, пример, который проходит валидацию, что видит пользователь после загрузки плагина, и ключ манифеста, который изменяет расположение по умолчанию. Добавляйте те, которые нужны вашему плагину; ни один не требуется.

Skills

Skill — это файл SKILL.md, который Claude может загрузить, когда его описание совпадает с задачей. Пользователь также может запустить его как команду. Сохраняйте каждый skill в его собственной директории под skills/:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── review/
        └── SKILL.md

Дайте SKILL.md description, чтобы Claude знал, когда его использовать:

---
description: Reviews a pull request for style and test coverage. Use when asked to review code.
---

Review the changed files. Report style problems first, then missing tests.

После загрузки плагина /my-plugin:review запускает skill. Имя команды и кто может её вызвать следуют этим правилам:

Вы также можете разместить skills вне директории по умолчанию skills/:

Чтобы включить инструкции в плагин, напишите их как skill. Claude Code не загружает CLAUDE.md в корне плагина, и claude plugin validate предупреждает CLAUDE.md at the plugin root is not loaded as project context.

Для полей frontmatter и вспомогательных файлов см. Skills.

Команды

Команда — это один файл Markdown, который пользователь запускает по имени, например /my-plugin:about.

Сохраняйте команду в commands/<file>.md и она становится /<plugin>:<file>. Подпапка добавляет сегмент, поэтому commands/db/migrate.md — это /my-plugin:db:migrate.

Файлы команд принимают тот же frontmatter, что и skills.

Определение команд в манифесте

Это нужно только, если вы хотите сохранить файлы команд где-то в другом месте, чем commands/, или определить короткую команду внутри plugin.json без отдельного файла Markdown. Установите ключ манифеста commands, и Claude Code читает его вместо сканирования commands/. Ключ принимает путь, массив путей или объект, который отображает каждое имя команды либо на файл source, либо на встроенное content.

Этот манифест определяет /my-plugin:about встроенным образом, без файла Markdown:

{
  "name": "my-plugin",
  "commands": {
    "about": {
      "content": "Summarize what this repository does in three sentences.",
      "description": "Summarize the repository"
    }
  }
}

Загрузите плагин и запустите /my-plugin:about в сессии, чтобы подтвердить, что он загрузился.

Для полного синтаксиса ключа см. commands.

Агенты

Подагент — это отдельный помощник с собственными инструкциями и окном контекста, которому Claude может делегировать задачу. Каждый файл Markdown под agents/ определяет один:

---
name: security-reviewer
description: Reviews code changes for security issues. Use after edits to authentication or input handling.
model: sonnet
---

You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.

Этот агент назван my-plugin:security-reviewer, и пользователь может вызвать его явно с помощью @agent-my-plugin:security-reviewer. Форма имени — <plugin>:<name>, где <name> берётся из frontmatter или из имени файла, когда его нет.

Ключ agents манифеста заменяет сканирование agents/.

Организация агентов в подпапках

Вы можете поместить файлы агентов плагина в подпапки agents/. Claude Code загружает их рекурсивно и объединяет имя плагина, каждое имя подпапки и имя файла с двоеточиями, чтобы сформировать имя агента с областью видимости. Например, agents/review/security.md в плагине с именем my-plugin загружается как my-plugin:review:security. Два параметра изменяют это имя:

Поля frontmatter в агентах плагина

Frontmatter агента плагина следует этим правилам:

Для того, что делает каждое поле и правила приоритета, см. Subagents.

Hooks

Hook запускает что-то автоматически в точке жизненного цикла Claude Code, например, после каждого редактирования файла: команду оболочки, HTTP запрос, вызов инструмента MCP, prompt к модели или подагента. Сохраняйте hooks плагина в hooks/hooks.json в корне плагина, под верхним уровнем ключа "hooks", в той же форме, что и объект hooks в settings.json. Это позволяет вам скопировать существующий hook параметров без изменений.

Этот hook запускает встроенный скрипт после каждого Write или Edit:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/format.sh\""
          }
        ]
      }
    ]
  }
}

Сохраняйте скрипт в scripts/format.sh и сделайте его исполняемым.

Загрузите плагин и попросите Claude отредактировать файл. Hook PostToolUse, который выходит с кодом 0, ничего не показывает в транскрипте, поэтому подтвердите, что он запустился с помощью debug logging или по тому, что сам скрипт изменяет.

Hooks в hooks/hooks.json и в ключе манифеста hooks оба загружаются. Для каждого события и его payload см. Hook events.

Когда запускаются hooks плагина

Hooks плагина не ждут использования одного из skills или команд плагина. Claude Code регистрирует их, когда сессия загружает плагин, и они запускаются на своих событиях с этого момента. Чтобы ограничить, когда запускается hook, сузьте его matcher.

Если hook никогда не запускается, см. hooks that don't fire.

Окружение, кавычки и соответствие инструментам MCP

Окружение hook, кавычки ${CLAUDE_PLUGIN_ROOT} и matchers для собственных инструментов MCP плагина работают следующим образом:

MCP серверы

MCP сервер предоставляет Claude инструменты из внешней системы. Объявите его в .mcp.json в корне плагина, в той же форме, что и проект .mcp.json. Этот .mcp.json объявляет один сервер с именем db:

{
  "mcpServers": {
    "db": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  }
}

Вы также можете опустить обёртку mcpServers и поместить db на верхний уровень файла.

Загрузите плагин и запустите /mcp, чтобы подтвердить, что сервер появляется как plugin:my-plugin:db.

claude plugin validate проверяет .mcp.json и сообщает запись сервера, которую Claude Code отбросит во время загрузки, как ошибку. Требуется Claude Code v2.1.281 или позже.

Для того, где плохая запись появляется во время загрузки, см. MCP servers that don't start.

Ключ манифеста mcpServers принимает встроенную карту сервера, путь к файлу JSON или массив этих. Когда сервер манифеста имеет то же имя, что и один в .mcp.json, сервер манифеста заменяет его.

Достижение пользователей на claude.ai и Cowork

Локальный сервер stdio, такой как сервер db под MCP servers, работает в Claude Code и в сессии Cowork, которая работает на вашей машине в приложении Claude Desktop, но не на claude.ai. Чтобы достичь пользователей там тоже, ссылайтесь на удалённый сервер по его URL https://, который claude.ai и Cowork предлагают пользователю как соединитель.

Имена серверов, имена инструментов и перезагрузки

Имена сервера, подстановка переменных и поведение перезагрузки следуют этим правилам:

Включение упакованного MCPB сервера

Ключ mcpServers также принимает упакованный сервер как файл MCPB, расширение которого .mcpb или более старое .dxt. Укажите ключ на файл, как путь внутри плагина или URL https://:

{
  "name": "my-plugin",
  "mcpServers": "./servers/db.mcpb"
}

Сервер берёт своё имя из name в манифесте пакета.

Для транспортов и аутентификации см. MCP.

LSP серверы

LSP сервер предоставляет Claude диагностику и навигацию по коду для языка. Если официальный плагин code intelligence уже охватывает ваш язык, установите его вместо написания собственного. Иначе объявите сервер в .lsp.json в корне плагина:

{
  "gopls": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

Файл отображает каждое имя сервера непосредственно на его конфигурацию, без объекта-обёртки вокруг карты. command — это имя двоичного файла, с его аргументами в args. extensionToLanguage нуждается по крайней мере в одном расширении, каждое начинается с ..

claude plugin validate не читает этот файл. Когда любая запись недействительна, весь файл пропускается при загрузке и Invalid LSP server config for ".lsp.json" появляется на вкладке Errors в /plugin.

Ваш плагин конфигурирует соединение, но не устанавливает двоичный файл сервера, и каждое расширение файла получает один сервер:

Ключ манифеста lspServers принимает ту же карту встроенной, путь к файлу JSON или массив этих, и его серверы добавляются к тем, что в .lsp.json. Когда сервер манифеста имеет то же имя, что и один в .lsp.json, сервер манифеста заменяет его.

Для transport, timeouts, restarts и других полей см. lspServers.

Отправляйте вывод логов в stderr, а не stdout. Claude Code читает stdout сервера только как сообщения протокола и принимает заголовки сообщений до 64 КиБ и тело сообщения до 32 МиБ.

Claude Code отключает сервер, который превышает любой лимит или пишет вывод, не являющийся протоколом, в stdout, и считает отключение сбоем для restartOnCrash и maxRestarts. Когда вы запускаете с --debug, Claude Code пишет ошибку, называющую причину, в журнал отладки.

Исполняемые файлы

Файлы в bin/ в корне плагина находятся на PATH оболочки инструмента Bash, пока плагин включен, поэтому Claude может запустить их как простые команды. Добавьте исполняемый скрипт:

#!/bin/bash
echo "hello from my-plugin"

Сделайте его исполняемым с помощью chmod +x bin/hello-plugin и загрузите плагин. Когда вы просите Claude запустить hello-plugin, результат инструмента Bash показывает вывод скрипта.

Директории bin/ плагина идут после собственных записей PATH пользователя, поэтому плагин не может затенять git, ls или другую системную команду.

claude.ai и Cowork не устанавливают плагин, который имеет директорию bin/ верхнего уровня, включая тот, который вы распространяете через параметры организации claude.ai.

Параметры по умолчанию

Чтобы установить значения по умолчанию, которые применяются, пока плагин включен, добавьте settings.json в корень плагина или поместите тот же объект встроенным в ключ манифеста settings. Два ключа вступают в силу, agent и subagentStatusLine, и все остальные ключи отбрасываются.

Установите agent для запуска одного из собственных агентов плагина как основного потока:

{
  "agent": "security-reviewer"
}

Загрузите плагин и начните сессию. Claude затем отвечает в основном разговоре с системным prompt и моделью агента security-reviewer.

Для всего, что контролирует ключ, см. параметр agent.

Когда один и тот же ключ установлен в более чем одном месте, эти правила решают, какое значение применяется:

Для формы subagentStatusLine см. subagent status lines.

Темы и стили вывода

Плагин может включать цветовые темы и стили вывода. Оба появляются в тех же выборщиках, что и собственные пользователя. Для любого из них установка ключа манифеста заменяет сканирование папки.

Компонент Сохраняйте как Формат Появляется в Ключ манифеста
Тема themes/<slug>.json Формат пользовательского файла темы, который пользователи пишут в ~/.claude/themes/ /theme, под name файла experimental.themes
Стиль вывода output-styles/<name>.md Формат пользовательского стиля вывода, с frontmatter name и description /output-style, как <plugin>:<name> outputStyles

Темы плагина доступны только для чтения, поэтому когда пользователь редактирует одну в /theme, редактирование сохраняется как копия в их собственной директории тем.

Эта тема перекрашивает акцент prompt и текст ошибки на тёмном предустановке:

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555"
  }
}

Каналы

Канал позволяет внешней системе, такой как приложение чата, отправлять сообщения в сессию. В плагине канал — это один из MCP серверов плюс запись channels, которая привязывает к нему и может запросить собственную конфигурацию. Этот манифест привязывает канал к серверу telegram и запрашивает токен бота:

{
  "name": "my-plugin",
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": { "BOT_TOKEN": "${user_config.bot_token}" }
    }
  },
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        }
      }
    }
  ]
}

server должен совпадать с ключом в mcpServers. Per-channel userConfig принимает ту же форму, что и верхний уровень ключа userConfig.

Для того, что должен реализовать сервер и как пользователи включают плагин канала, см. Package as a plugin в справочнике каналов. Для таблицы полей см. channels.

Мониторы

Монитор — это команда оболочки, которая работает в фоне для всей сессии. То, что она выводит, достигает Claude как уведомления, поэтому Claude может реагировать на журнал или изменение статуса без просьбы наблюдать за ним. Сохраняйте записи в monitors/monitors.json:

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

Команда запускается в оболочке, в рабочей директории, в которой сессия началась.

Команда монитора ограничена в том, где она запускается и на что может ссылаться:

Ключ манифеста experimental.monitors принимает тот же массив встроенным или путь к файлу JSON и читается вместо monitors/monitors.json.

Для триггера when и других полей см. monitors.

Запрос значений конфигурации у пользователя

Объявите значения, которые ваш плагин нужен от пользователя, в ключе манифеста userConfig, чтобы пользователи не редактировали settings.json сами. Каждый вариант появляется в диалоге с его title как метка и его description под ней.

Установите "sensitive": true для токена или пароля. Диалог затем маскирует ввод, и значение хранится в защищённом хранилище, а не в settings.json.

Этот манифест запрашивает конечную точку и токен:

{
  "name": "my-plugin",
  "userConfig": {
    "api_url": {
      "type": "string",
      "title": "API URL",
      "description": "Base URL of your team's API"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "Token for your team's API",
      "sensitive": true
    }
  }
}

Когда появляется диалог конфигурации

Диалог появляется только в интерактивном интерфейсе /plugin. Он открывается для любого варианта, который ещё не установлен, когда пользователь делает любое из следующего:

Чтобы открыть тот же диалог в любое время, пользователь запускает /plugin configure <plugin>@<marketplace>.

Команда оболочки claude plugin install никогда не запрашивает значения userConfig. Чтобы установить значения из оболочки, передайте каждое как --config KEY=VALUE. Когда варианты остаются неустановленными, команда выводит строку userConfig options not yet set, которая называет оба способа их установки. The userConfig dialog never appears цитирует строку.

Для полей варианта, где хранится каждое значение, как компонент ссылается на сохранённое значение и какие поля отклоняют ${user_config.*}, см. User configuration.

Ссылка на пути плагина и хранение данных

Вы не знаете, где будет установлен ваш плагин, поэтому ссылайтесь на его файлы и данные через эти переменные, а не через фиксированные пути. Они подставляются в содержимое skill, команды и агента, в команды hook и монитора, а также в конфигурации MCP и LSP сервера. Они также экспортируются в процессы hook, MCP и LSP:

В пути директории данных <id> — это идентификатор плагина со всеми символами, кроме букв, цифр, _ и -, заменённых на -, поэтому my-plugin@my-marketplace становится my-plugin-my-marketplace.

На Windows подставленные пути используют прямые слэши, поэтому оболочка не читает обратные слэши как экранирование.

Установка зависимостей в директорию данных

Для плагина, установленного из marketplace, Claude Code автоматически устанавливает подходящие зависимости пакета Node.js при кэшировании плагина, поэтому вам может не потребоваться устанавливать их самостоятельно. Когда вам нужно, этот hook SessionStart устанавливает node_modules в ${CLAUDE_PLUGIN_DATA} при первом запуске и снова после обновления, которое изменяет package.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "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\""
          }
        ]
      }
    ]
  }
}

После первой сессии ~/.claude/plugins/data/<id>/node_modules существует. MCP сервер может затем установить NODE_PATH в ${CLAUDE_PLUGIN_DATA}/node_modules в его env. Для того, какие поля подставляют какую переменную, см. Environment variables.

Следующие шаги