`plugin`

plugin — нативное расширение харнесса. Оно может добавлять skills, agents, commands, hooks, клиентскую MCP-конфигурацию или другие surfaces там, где этот харнесс их документирует.

Plugin отвечает на вопрос: какой пакет расширяет сам харнесс?

Он не отвечает «какой один MCP-сервер подключён?» (), «какой workflow должен следовать агент?» () и «через какой каталог plugins это поставляется?» (это упаковка marketplace, а не вид компонента).

!!! warning "Plugin — не marketplace"

marketplace — нативная упаковка: коллекция или ledger, которым харнесс распространяет plugins. Это не один из восьми видов компонента. plugins/marketplaces у Grok Build — служебный контейнер, не plugin, и discovery не возвращает его как кандидат.

Каталог под plugins/ становится plugin только через точный манифест из закрытого набора. JSON-значения манифеста не читаются — существование файла доказывает, что каталог является plugin.

Внутри доказанного plugin вложенные члены сохраняют свои виды (skill, agent, command, hook, instruction, mcp). Pack — это plugin; члены не переименовываются в plugins.

Соседи

Выбирайте plugin, когда поставляете пакет харнесса. Выбирайте mcp, когда поставляете сервер. Выбирайте skill, когда нужен только workflow.

Рекомендуемая структура пакета

--language для plugin — одно из python, typescript, javascript, rust, go или dart-flutter. Plugins OpenCode и Pi — один модуль JS/TS, не выдуманный манифест: для этих двух харнессов --language должен быть javascript или typescript.

Манифест-каталоги plugins (Claude Code, Codex, Cursor и переносимый plugin.json):

review-pack/
├── .claude-plugin/
│   └── plugin.json                # или .codex-plugin / .cursor-plugin / plugin.json
├── skills/                        # необязательно; каждый потомок с SKILL.md — skill
├── agents/                        # Claude Code / Cursor, когда есть
├── commands/                      # Claude Code / Cursor, когда есть
├── hooks/
│   └── hooks.json                 # Claude Code / Codex, когда есть
└── .mcp.json                      # клиентский конфиг Claude Code; не сервер

Cursor внутри доказанного pack: skills, agents, commands и rules (каждый файл — instruction). Официальная схема также называет hooks и mcpServers; walker не изобретает эти виды из соседнего каталога.

Когда вы начинаете из ai_stp, сначала сделайте scaffold. Авторский каталог шире опубликованного пакета: discover / adopt переносят source/ для portable и projections/<harness>/ для конкретного харнесса, а не всё дерево.

review-pack/                       # component-scaffold/3
├── .ai-stp-template.json
├── .gitignore
├── README.md
├── component-passport.json
├── eval-profile.json
└── source/
    ├── plugin.json
    └── skills/
        └── README.md

ai-stp component scaffold plan \
  --type plugin \
  --language python \
  --harness portable \
  --name review-pack \
  --output ./review-pack \
  --json

ai-stp component scaffold apply \
  --type plugin \
  --language python \
  --harness portable \
  --name review-pack \
  --output ./review-pack \
  --expected-plan-digest <digest> \
  --json

Для OpenCode или Pi сделайте scaffold одного {name}.js или {name}.ts под source/ (и projections/<harness>/). Не выдумывайте plugin.json, который эти продукты не используют.

Adopt каталога требует манифест из закрытого набора. Имена plugin в этом наборе: plugin.json, .claude-plugin/plugin.json, .codex-plugin/plugin.json и .cursor-plugin/plugin.json. Каталог plugins/, у членов которого нет манифеста ни одного поддерживаемого харнесса, компонентов не даёт и один раз на коллекцию сообщает unsupported_manifest.

Команды ai-stp component plugin validate нет. Структурная готовность — component passport validate. Kind-specific проверка по спецификации есть только у .

Стандарты и фреймворки

• Plugins Claude Code (проверенный источник): Create plugins. Discovery layout_source для этого pack — code.claude.com/docs/en/plugins.
• Packs Codex и Cursor: ссылайтесь на layout_source находки (learn.chatgpt.com/docs/build-plugins, cursor.com/docs/reference/plugins). Не выдумывайте URL документации.
• Вложенные skills по-прежнему следуют Agent Skills Specification.
• Вложенный MCP-клиентский конфиг следует MCP как протоколу; файл .mcp.json всё равно не сервер.

NVIDIA SkillSpector и Cisco Skill Scanner — сканеры skill. Они не проверяют пакет plugin целиком.

Нативные layout по харнессам

Discovery сообщает только объявленные layout. Точные пути на машине даёт ai-stp component discover --json. У каждой находки есть layout_source. Если классификация неясна, покажите это поле; не угадывайте путь соседа.

Из матрицы discovery:

Pack одного харнесса не вызывает жалобу другого: Codex pack остаётся pack даже без манифеста Claude.

Под skills/ каталог с SKILL.md — это skill; каталог с .claude-plugin/plugin.json или plugin.json — это plugin. Discovery различает их по манифесту, а не по имени родительской папки.

ai-stp component discover --root . --json
ai-stp toolchain harness-capabilities --json

Версии — `X.Y`, не SemVer

Опубликованная версия plugin неизменяема и имеет вид X.Y. Патч-номера нет. Изменение манифеста, вложенного члена или входного модуля — новая версия. Обновление plugin внутри сетапа — новая версия сетапа.

Манифесты plugin вендора могут содержать собственные строки версии. Эти строки — не версии ai_stp. ai_stp по-прежнему выпускает неизменяемый X.Y.

ai-stp component version list --id <stable_id> --json
ai-stp component version release --id <stable_id> --json

--major открывает следующую мажорную линию. Мажорная линия — отдельная граница доступа.

Что проверяет `ai_stp`

Процент карточки каталога и разделение обязательных и необязательных проверок объяснены на странице Проверки безопасности. Для plugin ожидайте как минимум:

• структуру, digest, лицензию, tags, исходный репозиторий;
• ограниченную распаковку и path denylist;
• сканирование секретов (secrets_heuristic и Gitleaks, если включён);
• правила prompt-injection и скрытого содержимого;
• языковой SAST и SCA, когда есть scripts и lockfiles;
• вложенные члены, сканируемые как свои виды, когда они есть (mcp_config_static, hook_schema_static, hook_command_argv, skill_static_gate).

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

Перед установкой также смотрите:

author_verified и component_verified независимы. Ни одно не является гарантией безопасности.

Связанные команды CLI

Только команды, которые существуют. Флаги всегда со страниц CLI и всегда --json. Исполняемый файл — ai-stp (пакет ai-stp-cli). Команд component inspect и setup show нет. Единственный kind-specific validate — ai-stp component skill validate.

Именно этот вид: команды component plugin validate нет. Используйте проверку паспорта. Вложенные skills всё равно можно проверить так:

ai-stp component skill validate --path <directory-with-SKILL.md> --json

Автор, adopt, публикация:

ai-stp component discover --root . --json
ai-stp component adopt --path <source_path> --json
ai-stp component passport validate --id <stable_id> --json
ai-stp component version release --id <stable_id> --json
ai-stp publication plan --id <stable_id> --version 1.0 --json
ai-stp publication confirm --plan-id <id> --plan-hash <hash> --confirm --json

Если путь также заявлен как каталог skill:

ai-stp component adopt --path <source_path> --kind plugin --json

Найти, выбрать, установить:

ai-stp registry search --kind component --query <name> --json
ai-stp select eligibility --harness <id> --json
ai-stp install plan --json

Plugin может быть embedded-членом compose-манифеста. См. Сетапы.

Как plugin проходит через `ai_stp`

=== "Автор" Автор публикует plugin из публичного GitHub-источника или импортирует его локально. Версия закрепляет точный commit и подпуть. Discovery plugin не запускает.

=== "Каталог" Каталог показывает назначение, поддерживаемые харнессы, ограничения, trusted status автора и независимый status самого компонента.

=== "Сборщик" Сборщик проверяет, что plugin можно встроить в выбранный сетап и что его файловая структура подходит проекции provider.

=== "Provider" Provider устанавливает нативный пакет только после плана, digest и подтверждения. Rollback должен вернуть target настолько, насколько позволяет provider этого харнесса.

Красные флаги

• Каталог plugins/ без поддерживаемого манифеста, выданный за plugin. Discovery один раз сообщает unsupported_manifest; пустой инвентарь без этой диагностики был бы хуже.
• Marketplace или plugins/marketplaces Grok Build, помеченные как вид plugin.
• commands/, agents/, skills/ или hooks/ внутри .claude-plugin/ (там принадлежит только plugin.json).
• Каталог под skills/, который на самом деле plugin, помеченный как skill.
• Открытие .mcp.json, чтобы скопировать токены в паспорт.
• Живые токены, закрытые ключи или тела .env в пакете.
• Линия доверия experimental без consent allow.
• Харнесс не в списке совместимости компонента.
• «Latest» или имя ветки вместо точных X.Y и commit.
• Обращение с author_verified как с component_verified.
• Обращение с github/exact как с доказательством, что plugin безопасен.

??? question "Можно ли plugin использовать без публикации" Да. Собственный, импортированный или точно закреплённый plugin можно использовать после локальных проверок. Он от этого не становится platform-verified и должен быть показан именно как локальный или закреплённый объект (local_owner_or_pinned). Supply-chain и post-install поведение по-прежнему требуют плана.

Чеклист автора

1. Сделайте scaffold с --type plugin и настоящим --language. Для OpenCode или Pi используйте javascript или typescript и один модуль.
2. Докажите pack точным манифестом этого харнесса. Не выдумывайте вид marketplace.
3. Кладите вложенные члены в корень plugin (skills/, agents/, commands/, hooks/hooks.json, .mcp.json, rules/ Cursor) только когда доказанный pack этого харнесса их действительно читает.
4. Объявите post-install поведение в паспорте. Секретов нет.
5. Запустите ai-stp component discover --root . --json и прочитайте layout_source у находки plugin и у вложенных членов.
6. component adopt --path <точный source_path> — добавьте --kind plugin, если путь также является каталогом skill.
7. Закрепите точный публичный GitHub commit и подпуть.
8. component passport validate → component version release, чтобы выпустить неизменяемый X.Y.
9. Публикуйте через путь публикации. В сетапе закрепите этот X.Y.

Связанное: Авторство, Компоненты, , .