ai_stp

# `skill` `skill` — переносимый агентский workflow. Обычно он содержит `SKILL.md`, инструкции, references, assets и иногда scripts, которые помогают агенту выполнить специализированную задачу без угадывания процесса. Skill отвечает на вопрос: **как агент должен делать этот класс задач?** Он не отвечает «какой именованный shortcut набрать?» (`command`), «какой внешний tool подключён?» (`mcp`) и «какой пакет расширяет харнесс?» (`plugin`). !!! warning "Два разных объекта с именем skill" Эта страница — **вид компонента** `skill`, который входит в сетап. CLI также поставляет один канонический Agent Skill, который учит агента управлять самим `ai-stp`. Этот объект ставится командой [`ai-stp skill install`](../cli/skill.md), проверяется через `ai-stp skill status` и снимается через `ai-stp skill remove`. Это **не** компонент каталога, его **не** выбирают в сетап, и `ai-stp component skill validate` — **не** этот установщик. | Объект | Семейство команд | Живёт в сетапе? | | --- | --- | --- | | Вид `skill` (эта страница) | `component …`, `select`, `install` | да | | CLI Agent Skill | `ai-stp skill install` / `status` / `remove` | нет | ## Соседи | Вид | Главное отличие | | --- | --- | | `instruction` | даёт общие правила и контекст и не обязан описывать workflow | | `command` | запускается как именованный shortcut, а skill активируется по смыслу задачи | | `plugin` | расширяет сам харнесс, а skill расширяет рабочее поведение агента | | `mcp` | даёт инструментальный интерфейс, а skill объясняет, когда и как им пользоваться | | `hook` | срабатывает на событии жизненного цикла, а skill ждёт, пока его выберут для задачи | | `agent` | называет роль, которая может использовать несколько skills; skill — процедура, не роль | | `setting` | хранит параметры, а не workflow | Выбирайте `skill`, когда агент должен следовать повторяемой процедуре с сопроводительными файлами. Выбирайте `instruction`, когда нужны только постоянные правила. Выбирайте `command`, когда человек или агент должен вызвать работу по имени. ## Рекомендуемая структура пакета Из закрытых видов независимая спецификация есть только у `skill`: Agent Skills Specification. `SKILL.md` должен лежать в **корне пакета**. Обёртка `payload/SKILL.md` не соответствует стандарту для любого читателя, который реализует спецификацию, а не локальный layout. ```text playwright-checks/ ├── SKILL.md обязательно: YAML frontmatter и инструкции ├── scripts/ необязательно, по соглашению ├── references/ необязательно, по соглашению ├── assets/ необязательно, по соглашению ├── evals/ допустимое расширение; в отчёте отдельно └── tests/ допустимое расширение; не отказ ``` Имя каталога должно совпадать с полем `name` во frontmatter. Когда вы начинаете из `ai_stp`, стартуйте intent `author`. Не набирайте `component scaffold plan`. Авторский каталог шире опубликованного пакета: `discover` / `adopt` переносят `source/` для portable и `projections/<harness>/` для конкретного харнесса, а не всё дерево. ```text playwright-checks/ # component-scaffold/6 ├── .ai-stp-template.json ├── .gitignore ├── README.md ├── component-passport.json ├── eval-profile.json └── source/ └── SKILL.md ``` Повседневное авторство: ```bash ai-stp task start --intent author --idempotency-key author-session-01 --json ``` Expert recovery (уже есть digest): ```text ai-stp component scaffold plan \ --type skill \ --language none \ --harness portable \ --name playwright-checks \ --output ./playwright-checks \ --json ai-stp component scaffold apply \ --type skill \ --language none \ --harness portable \ --name playwright-checks \ --output ./playwright-checks \ --expected-plan-digest <digest> \ --json ``` `--language` для skill — `none`. Вид декларативный. ### Frontmatter, который примет валидатор | Поле | Обязательно | Ограничение | | --- | --- | --- | | `name` | да | 1–64 символа; строчные буквы, цифры и дефисы; не начинается и не заканчивается дефисом; без двойных дефисов; совпадает с именем каталога | | `description` | да | 1–1024 символа, непустое | | `license` | нет | стандарт не задаёт дополнительного лимита | | `compatibility` | нет | 1–500 символов | | `metadata` | нет | отображение строк в строки | | `allowed-tools` | нет | строка через пробел; experimental | Ключ верхнего уровня, который стандарт не определяет, сообщается как `SK033`. Свойства конкретного клиента кладите в `metadata`. Тело после frontmatter на формат не проверяется: спецификация говорит, что ограничений формата нет. Проверяйте форму установленного пакета, а не авторское дерево: ```bash ai-stp component skill validate --path ./playwright-checks/source --json ``` Команда только читает. Она называет каждое отклонение кодом `SKxxx`. Она не делает adopt, не публикует и не пишет target. ## Стандарты и фреймворки - [Agent Skills Specification](https://agentskills.io/specification) — независимый стандарт. `ai-stp component skill validate` реализует эту границу, а не внутренний стиль дома. - Сканеры безопасности, которые используются при публикации, если доступны: [NVIDIA SkillSpector](https://github.com/NVIDIA/SkillSpector) и [Cisco Skill Scanner](https://github.com/cisco-ai-defense/skill-scanner). Недоступный движок никогда не становится прохождением. См. [Проверки безопасности](../security-checks.md). Не выдумывайте дополнительные поля frontmatter только потому, что их показывает UI харнесса. Заметки, специфичные для харнесса, кладите в `metadata`. ## Нативные layout по харнессам Discovery сообщает только объявленные layout. Точные пути на машине даёт конверт intent `author`. У каждой находки есть `layout_source` — официальный документ, который объявил layout. Если классификация неясна, покажите это поле; не угадывайте путь соседа. Из матрицы discovery: | Харнесс | Global | Project | Что есть в контракте discovery | | --- | --- | --- | --- | | Claude Code | да | да | в `skills/` каталог с `SKILL.md` — это skill; каталог с `.claude-plugin/plugin.json` или `plugin.json` — это **plugin** | | Codex | общий skill | общий skill | общие `.agents/skills` не принадлежат харнессу (`harness_id=null`) | | Pi | да | да | | | OpenCode | да | да | | | Grok Build | да | да | | | Cursor | через plugin pack | через plugin pack | skills читаются внутри доказанного пакета `.cursor-plugin/plugin.json` | | Antigravity | да | да | | | `undefined` | переносимые соглашения | переносимые соглашения | это не харнесс; автоматическая установка не считается безопасной | Общие `.agents/skills` возвращаются один раз, а не дублируются под каждым совместимым харнессом. `nori.json` Nori или `.agents/.skill-lock.json` (версия 3) могут уточнить уже найденный путь. Они не создают skill из отсутствующего каталога и не делают внешний манифест источником подтверждённых фактов паспорта. Expert recovery — повседневное авторство это intent `author`: ```bash ai-stp task start --intent author --idempotency-key author-session-01 --json ``` Не набирайте `component discover`. Движок сам находит нативное дерево. ## Версии — `X.Y`, не SemVer Опубликованная версия skill неизменяема и имеет вид `X.Y`. Патч-номера нет. Изменение `SKILL.md`, скрипта или asset — новая версия. Обновление skill внутри сетапа — новая версия сетапа. ```bash ai-stp component version list --id <stable_id> --json ai-stp component version release --id <stable_id> --json ``` `--major` открывает следующую мажорную линию. Мажорная линия — отдельная граница доступа. ## Что проверяет `ai_stp` Процент карточки каталога и разделение обязательных и необязательных проверок объяснены на странице [Проверки безопасности](../security-checks.md). Для skill ожидайте как минимум: - структуру, digest, лицензию, tags, исходный репозиторий; - ограниченную распаковку и path denylist; - сканирование секретов (`secrets_heuristic` и Gitleaks, если включён); - правила prompt-injection и скрытого содержимого; - `skill_static_gate` (собственные правила плюс SkillSpector и Skill Scanner, когда они доступны); - языковой SAST и SCA, если есть scripts и lockfiles. Пройденное сканирование снижает известный риск. Это не гарантия, что workflow безвреден. Обязательные проверки, которые провалились или не смогли запуститься, блокируют публикацию. Перед установкой также смотрите: | Проверка | Почему важно | | --- | --- | | Есть ли scripts | скрипты могут действовать вне Markdown | | Есть ли references или assets | агенту нужен весь комплект, не только `SKILL.md` | | Совместим ли харнесс | одинаковое имя skill не гарантирует одинаковый формат | | Кто автор | verified-автор не делает содержимое автоматически безопасным | | Какой `X.Y` закреплён | обновление skill создаёт новую версию сетапа | | Линия доверия | `experimental` требует явного согласия | ## Связанные команды CLI Только команды, которые существуют. Флаги из continuation `argv`; старт — `ai-stp task intents --json`. **Именно этот вид:** ```bash ai-stp component skill validate --path <directory> --json ``` **Не этот вид** — CLI Agent Skill (см. [Agent Skill CLI](../cli/skill.md)): ```bash ai-stp skill status --json ai-stp skill install --target <dir> --json ai-stp skill remove --target <dir> --json ``` **Автор, adopt, публикация:** ```bash ai-stp task start --intent author --idempotency-key author-session-01 --json ai-stp task start --intent publish --idempotency-key publish-session-01 --json ``` **Установить:** ```bash ai-stp task start --intent install --idempotency-key install-session-01 --json ``` Expert-просмотр каталога: ```text ai-stp registry search --kind component --query <name> --json ``` Skill может быть и embedded-членом compose-манифеста. См. [Сетапы](../setups/index.md). ## Как skill проходит через `ai_stp` === "Автор" Автор публикует skill из публичного GitHub-источника или импортирует его локально. Версия закрепляет точный commit и подпуть. === "Каталог" Каталог показывает назначение, поддерживаемые харнессы, ограничения, trusted status автора и независимый status самого компонента. === "Сборщик" Сборщик проверяет, что skill можно встроить в выбранный сетап и что его файловая структура подходит проекции provider. === "Provider" Provider кладёт skill в нативный каталог харнесса и обновляет связанные индексы только после плана, digest и подтверждения. ## Красные флаги - `SKILL.md` вложен в `payload/` или другой каталог-обёртку. - `name` во frontmatter не совпадает с именем каталога (`SK013`). - Поле верхнего уровня, которое спецификация не определяет (`SK033`), вместо `metadata`. - Скрипты, которые скачивают и pipe'ят в shell, или которые велят агенту игнорировать предыдущие инструкции. - Живые токены, закрытые ключи или тела `.env` в пакете. - Каталог под `skills/`, который на самом деле plugin (есть `.claude-plugin/plugin.json` / `.codex-plugin/plugin.json` / `.cursor-plugin/plugin.json` / `plugin.json`), помеченный как skill. - Линия доверия `experimental` без `consent allow`. - Харнесс не в списке совместимости компонента. - «Latest» или имя ветки вместо точных `X.Y` и commit. - Обращение с `ai-stp skill install` так, будто оно опубликовало этот компонент. - Обращение с `author_verified` как с `component_verified`. ??? question "Можно ли skill использовать без публикации" Да. Собственный, импортированный или точно закреплённый skill можно использовать после локальных проверок. Он от этого не становится platform-verified и должен быть показан именно как локальный или закреплённый объект (`local_owner_or_pinned`). ## Чеклист автора 1. Сделайте scaffold с `--type skill --language none` и держите `SKILL.md` в корне пакета (в авторском дереве — под `source/`). 2. Заполните `name` и `description`. Ключи конкретного харнесса кладите в `metadata`. 3. Добавляйте `scripts/`, `references/` и `assets/` только когда workflow без них не работает. Что они делают, объявите в паспорте. 4. Запустите `ai-stp component skill validate --path <package> --json` и исправьте каждый код `SKxxx`. 5. Закрепите точный публичный GitHub commit и подпуть. Секретов в дереве нет. 6. Зарегистрируйте каталог через `ai-stp task start --intent author --idempotency-key author-session-01 --json`. Expert discover/adopt остаются для recovery. 7. `component version release`, чтобы выпустить неизменяемый `X.Y`. 8. Публикуйте через [путь публикации](../publishing/index.md). 9. В сетапе закрепите этот `X.Y`. Позднее обновление — новая версия сетапа. Связанное: [Авторство](../publishing/authoring.md), [Компоненты](index.md), [CLI Agent Skill](../cli/skill.md).