skill

skill — переносимый агентский workflow. Обычно он содержит SKILL.md, инструкции, references, assets и иногда scripts, которые помогают агенту выполнить специализированную задачу без угадывания процесса.

Skill отвечает на вопрос: как агент должен делать этот класс задач?

Он не отвечает «какой именованный shortcut набрать?» (command), «какой внешний tool подключён?» (mcp) и «какой пакет расширяет харнесс?» (plugin).

Два разных объекта с именем skill

Эта страница — вид компонента skill, который входит в сетап.

CLI также поставляет один канонический Agent Skill, который учит агента управлять самим ai-stp. Этот объект ставится командой ai-stp skill install, проверяется через 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.

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

Поле	Обязательно	Ограничение
name	да	1–64 символа; строчные буквы, цифры и дефисы; не начинается и не заканчивается дефисом; без двойных дефисов; совпадает с именем каталога
description	да	1–1024 символа, непустое
license	нет	стандарт не задаёт дополнительного лимита
compatibility	нет	1–500 символов
metadata	нет	отображение строк в строки
allowed-tools	нет	строка через пробел; experimental

Ключ верхнего уровня, который стандарт не определяет, сообщается как 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:

Харнесс	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:

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 безвреден. Обязательные проверки, которые провалились или не смогли запуститься, блокируют публикацию.

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

Проверка	Почему важно
Есть ли scripts	скрипты могут действовать вне Markdown
Есть ли references или assets	агенту нужен весь комплект, не только SKILL.md
Совместим ли харнесс	одинаковое имя skill не гарантирует одинаковый формат
Кто автор	verified-автор не делает содержимое автоматически безопасным
Какой X.Y закреплён	обновление skill создаёт новую версию сетапа
Линия доверия	experimental требует явного согласия

Связанные команды 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

АвторКаталогСборщикProvider

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

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

Сборщик проверяет, что skill можно встроить в выбранный сетап и что его файловая структура подходит проекции 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.

Можно ли 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.