skill

Skill-компоненты: повторяемые workflows для агента, отдельно от Agent Skill CLI.

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` | нет |

Соседи

Выбирайте skill, когда агент должен следовать повторяемой процедуре с сопроводительными файлами. Выбирайте instruction, когда нужны только постоянные правила. Выбирайте command, когда человек или агент должен вызвать работу по имени.

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

Из закрытых видов независимая спецификация есть только у skill: Agent Skills Specification. SKILL.md должен лежать в корне пакета. Обёртка payload/SKILL.md не соответствует стандарту для любого читателя, который реализует спецификацию, а не локальный layout.

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>/ для конкретного харнесса, а не всё дерево.

playwright-checks/                 # component-scaffold/6
├── .ai-stp-template.json
├── .gitignore
├── README.md
├── component-passport.json
├── eval-profile.json
└── source/
    └── SKILL.md

Повседневное авторство:

ai-stp task start --intent author --idempotency-key author-session-01 --json

Expert recovery (уже есть digest):

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, который примет валидатор

Ключ верхнего уровня, который стандарт не определяет, сообщается как SK033. Свойства конкретного клиента кладите в metadata. Тело после frontmatter на формат не проверяется: спецификация говорит, что ограничений формата нет.

Проверяйте форму установленного пакета, а не авторское дерево:

ai-stp component skill validate --path ./playwright-checks/source --json

Команда только читает. Она называет каждое отклонение кодом SKxxx. Она не делает adopt, не публикует и не пишет target.

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

• Agent Skills Specification — независимый стандарт. ai-stp component skill validate реализует эту границу, а не внутренний стиль дома.
• Сканеры безопасности, которые используются при публикации, если доступны: NVIDIA SkillSpector и Cisco Skill Scanner. Недоступный движок никогда не становится прохождением. См. Проверки безопасности.

Не выдумывайте дополнительные поля frontmatter только потому, что их показывает UI харнесса. Заметки, специфичные для харнесса, кладите в metadata.

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

Discovery сообщает только объявленные layout. Точные пути на машине даёт конверт intent author. У каждой находки есть layout_source — официальный документ, который объявил layout. Если классификация неясна, покажите это поле; не угадывайте путь соседа.

Из матрицы discovery:

Общие .agents/skills возвращаются один раз, а не дублируются под каждым совместимым харнессом.

nori.json Nori или .agents/.skill-lock.json (версия 3) могут уточнить уже найденный путь. Они не создают skill из отсутствующего каталога и не делают внешний манифест источником подтверждённых фактов паспорта.

Expert recovery — повседневное авторство это intent author:

ai-stp task start --intent author --idempotency-key author-session-01 --json

Не набирайте component discover. Движок сам находит нативное дерево.

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

Опубликованная версия skill неизменяема и имеет вид X.Y. Патч-номера нет. Изменение SKILL.md, скрипта или asset — новая версия. Обновление skill внутри сетапа — новая версия сетапа.

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

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

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

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

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

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

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

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

Только команды, которые существуют. Флаги из continuation argv; старт — ai-stp task intents --json.

Именно этот вид:

ai-stp component skill validate --path <directory> --json

Не этот вид — CLI Agent Skill (см. Agent Skill CLI):

ai-stp skill status --json
ai-stp skill install --target <dir> --json
ai-stp skill remove --target <dir> --json

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

ai-stp task start --intent author --idempotency-key author-session-01 --json
ai-stp task start --intent publish --idempotency-key publish-session-01 --json

Установить:

ai-stp task start --intent install --idempotency-key install-session-01 --json

Expert-просмотр каталога:

ai-stp registry search --kind component --query <name> --json

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

Как 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. Публикуйте через путь публикации.
9. В сетапе закрепите этот X.Y. Позднее обновление — новая версия сетапа.

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