Скилл — пакет процесса, а не промпт в папке
Вид skill — повторяемая процедура агента: триггер, шаги, справка и необязательные скрипты. Это не AGENTS.md, не slash-команда и не CLI Agent Skill.
- component
- skill
Вид skill отвечает на один вопрос: как агент должен делать этот класс задач? Это переносимый процесс. Обычно в пакете есть SKILL.md и по необходимости references/, assets/, scripts/ и примеры. Агент не держит всю библиотеку в контексте. Сначала он видит имя и описание. Только после выбора загружает процедуру, и только потом тяжёлые файлы.
Это противоположность инструкции на три тысячи строк. Постоянные правила — вид instruction. Именованный ярлык — вид command. Внешний интерфейс инструмента — вид mcp. Отдельная роль — вид agent.
Два разных объекта с именем skill
Вид skill из каталога входит в сетап. У CLI отдельно есть Agent Skill, который учит агента управлять самим ai-stp. Его ставят командой ai-stp skill install, смотрят через ai-stp skill status и снимают через ai-stp skill remove. Это не компонент каталога. ai-stp component skill validate — не этот установщик.
Если эти два объекта смешать, вы начнёте искать в сетапе то, чего там нет, или попытаетесь опубликовать CLI-помощник как скилл каталога.
Что на самом деле делает description
Агент выбирает скилл по описанию, а не по красоте тела. Helps with code — шум. Рабочее описание говорит, какую задачу он закрывает, какими словами его триггерить, какие входы нужны, что вернуть и когда его нельзя включать.
Progressive disclosure — причина, почему скиллы масштабируются. В SKILL.md остаётся короткая процедура. Длинные политики, заметки по API, JQL, шаблоны и примеры живут в references/ и assets/. Если главный файл стал новым Confluence, вы написали инструкцию и назвали её скиллом.
Скрипты внутри скилла — часть пакета. Это ещё и поверхность доверия: скрытые побочные эффекты, незакреплённые зависимости и сетевые вызовы должны быть видны в плане установки, а не сюрпризом после apply.
Как это выглядит на диске
Точные нативные пути даёт ai-stp component discover --json. У каждой находки есть layout_source. Не копируйте папку соседнего харнесса только потому, что слово skills кажется знакомым.
Общие .agents/skills не принадлежат одному харнессу. Discovery возвращает их один раз, с harness_id=null. Плагин может *содержать* скиллы; эти члены остаются видом skill. Обёртка вокруг них — вид plugin.
Единственный kind-specific валидатор в CLI — ai-stp component skill validate. Структурная готовность к публикации по-прежнему ai-stp component passport validate. Флаги, схемы и next_actions берутся из ai-stp help --agent --json, а не из этой статьи.