CLI агент-скилла¶

Это собственный агент-скилл CLI: процедура, которую агент читает, чтобы управлять ai-stp. Это не компонент вида skill внутри сетапа. Это skill-компоненты. Путаница этих двух понятий — это то, как агент перезаписывает файл рабочего процесса пользователя или пропускает установку скилла контрольной плоскости, потому что существует карточка каталога.

Скилл — это то, что агент читает, чтобы научиться управлять этим CLI, поэтому установка, которая несёт бинарник, но не процедуру, доставила половину продукта. После того как скилл присутствует, агент по-прежнему начинает каждую сессию с task intents --json.

Назначение именуется, а не обнаруживается. Где каждый харнес ищет свой нативный скилл — это факт о том харнесе. Эта группа команд не будет искать на диске подходящую папку. Если вы не знаете директорию, спросите документацию харнеса, а не этот CLI.

Команды¶

Команда	Мутабельность	Подтверждение	Когда
`ai-stp skill install`	`apply`	`none`	Установить канонический агент-скилл в указанное назначение.
`ai-stp skill status`	`read`	`none`	Сообщить, какой агент-скилл находится в назначении и кому он принадлежит.
`ai-stp skill remove`	`apply`	`none`	Удалить агент-скилл, который эта установка поместила в назначение.

--target обязателен для всех трёх. Это директория, из которой харнес читает свой нативный скилл. Настроенного fallback нет. CLI не угадывает директорию скилла харнеса.

remove — это apply, а не destructive. Он забирает пакет, который эта установка записала. Он не отбрасывает идентичность или локальный реестр.

Типичный путь¶

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

<dir> — это директория, из которой харнес читает свой нативный скилл, не корень проекта и не директория управляемой toolchain. Точная структура — это факт о том харнесе. Выдумывание этих путей было бы догадкой, выданной за поддержку.

Если status сообщает owned, всё готово. Если сообщает absent, установите. Если сообщает foreign или stale, не устанавливайте поверх.

Чтобы забрать только то, что эта установка записала:

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

Два разных слова `skill`¶

Объект	Страница	Что это
CLI агент-скилла	эта страница	процедура управления `ai-stp`
Компонент вида `skill`	skill	переносимый рабочий процесс агента внутри сетапа

skill install не публикует компонент. component skill validate не устанавливает этот файл. Поиск по каталогу вида skill не сообщает, принадлежит ли это назначение.

`skill status`¶

Сообщить, какой агент-скилл находится в назначении и кому он принадлежит.

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

Ничего не создаёт, включая директорию назначения.

state — одно из:

`state`	Значение
`absent`	файла скилла там нет
`owned`	эта установка записала его, и дайджест по-прежнему совпадает
`foreign`	что-то другое поместило скилл туда; это не наш, чтобы заменять
`stale`	эта установка записала его, и кто-то отредактировал файл после этого

`skill install`¶

Установить канонический агент-скилл в указанное назначение.

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

Записывает пакет (SKILL.md плюс references/) и запись о владении. Отклоняет замену скилла, который эта установка не записывала (foreign), и отклоняет перезапись пакета, который правили после этой установки (stale).

Идемпотентен при назначении owned: установка того же пакета снова перезаписывает те же байты, и ответ не меняется.

--harness ставит нативную проекцию для одного харнесса вместо канонической карты. Проекция всё равно несёт процедуру и не указывает на путь репозитория. --locale ru ставит русскую процедуру. Прочитайте дескриптор, прежде чем добавлять любой из флагов.

`skill remove`¶

Удалить агент-скилл, который эта установка поместила в назначение.

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

Удаляет только то, что заявляет запись о владении. Файл, который этот CLI не записывал, остаётся нетронутым и сообщается (AI_STP_CONFLICT). Локальный реестр и всё, что пользователь настроил, — это другое и никогда не затрагивается: это контрольная плоскость, а не их данные.

Удаление при назначении absent — успешный no-op: state остаётся absent.

Что содержит успешный конверт¶

Все три команды возвращают одинаковую форму результата в data:

Поле	Что это
`state`	`absent`, `owned`, `foreign` или `stale`
`target`	директория назначения, как отображается
`digest`	дайджест пакета, или `null`
`harness`	проекция, которая была установлена, или `null` для канонической
`locale`	`en` или `ru`, если эта установка записала пакет
`files`	принадлежащие относительные пути пакета
`available_harnesses`	харнесы, для которых эта сборка может проецировать
`schema_version`	мажорная версия схемы этого отчёта

Конверт также несёт ok, warnings, next_actions, request_id, operation_id и schema_version.

foreign может появиться при успешном status. Это не успех при install или remove: те отклоняют с AI_STP_CONFLICT.

Что эти команды никогда не делают¶

не устанавливают skill-компонент в сетап;
не угадывают директорию скилла харнеса, когда --target отсутствует;
не перезаписывают foreign или stale файл;
не затрагивают локальный реестр, паспорта или кэшированные байты каталога;
не запускают сессию агента и не вызывают API модели;
не записывают таргет харнеса.

После того как файл присутствует, агент по-прежнему начинает каждую сессию с:

ai-stp task intents --json

Скилл говорит ему делать это. Установка файла — не замена компактного списка intent.

Типичные отказы¶

Что вы видите	Что это значит	Что делать
`AI_STP_VALIDATION_ERROR` отсутствует `--target`	директория назначения обязательна	передайте `--target <dir>`
`AI_STP_VALIDATION_ERROR` неизвестный харнес	для этого имени не поставлена проекция	`capabilities --json` и используйте поддерживаемый харнес
`AI_STP_CONFLICT` при install, `foreign`	скилл, которым эта установка не владеет, уже там	`skill status --target <dir> --json`; не перезаписывайте его
`AI_STP_CONFLICT` при install, `stale`	установленный скилл был отредактирован после того, как эта установка записала его	`skill remove --target <dir> --json`, только если вы намерены отбросить эти правки
`AI_STP_CONFLICT` при remove	этот скилл не был установлен этой установкой	оставьте его; это не ваше, чтобы удалять
поиск в каталоге для skill	это вид `skill`, компонент	skill-компоненты

Связанные страницы¶

Страница	Зачем
skill-компоненты	другое значение `skill`
Observe	`doctor` и `help --agent` после установки
Программа харнеса	программа, которая будет читать этот файл
Toolchain	другой объект, отсутствующий при первом запуске
Команды компонентов	adopt и publish вида `skill`
Быстрый старт для ИИ-агента	шаг Agent Skill первого запуска

Флаги из ai-stp help --agent --json

Если help --agent расходится с флагом на этой странице, CLI выигрывает. Необязательные флаги здесь не перечислены. Читайте их из дескриптора. Каждая команда здесь требует --target.