ai_stp

# CLI агент-скилла Это собственный агент-скилл CLI: процедура, которую агент читает, чтобы управлять `ai-stp`. Это **не** компонент вида `skill` внутри сетапа. Это [skill-компоненты](../components/skill.md). Путаница этих двух понятий — это то, как агент перезаписывает файл рабочего процесса пользователя или пропускает установку скилла контрольной плоскости, потому что существует карточка каталога. Скилл — это то, что агент читает, чтобы научиться управлять этим 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`. Он забирает пакет, который эта установка записала. Он не отбрасывает идентичность или локальный реестр. ## Типичный путь ```bash 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`, не устанавливайте поверх. Чтобы забрать только то, что эта установка записала: ```bash ai-stp skill remove --target <dir> --json ai-stp skill status --target <dir> --json ``` ## Два разных слова `skill` | Объект | Страница | Что это | | --- | --- | --- | | CLI агент-скилла | эта страница | процедура управления `ai-stp` | | Компонент вида `skill` | [skill](../components/skill.md) | переносимый рабочий процесс агента внутри сетапа | `skill install` не публикует компонент. `component skill validate` не устанавливает этот файл. Поиск по каталогу вида `skill` не сообщает, принадлежит ли это назначение. ## `skill status` Сообщить, какой агент-скилл находится в назначении и кому он принадлежит. ```bash ai-stp skill status --target <dir> --json ``` Ничего не создаёт, включая директорию назначения. `state` — одно из: | `state` | Значение | | --- | --- | | `absent` | файла скилла там нет | | `owned` | эта установка записала его, и дайджест по-прежнему совпадает | | `foreign` | что-то другое поместило скилл туда; это не наш, чтобы заменять | | `stale` | эта установка записала его, и кто-то отредактировал файл после этого | ## `skill install` Установить канонический агент-скилл в указанное назначение. ```bash ai-stp skill install --target <dir> --json ``` Записывает пакет (`SKILL.md` плюс `references/`) и запись о владении. Отклоняет замену скилла, который эта установка не записывала (`foreign`), и отклоняет перезапись пакета, который правили после этой установки (`stale`). Идемпотентен при назначении `owned`: установка того же пакета снова перезаписывает те же байты, и ответ не меняется. `--harness` ставит нативную проекцию для одного харнесса вместо канонической карты. Проекция всё равно несёт процедуру и не указывает на путь репозитория. `--locale ru` ставит русскую процедуру. Прочитайте дескриптор, прежде чем добавлять любой из флагов. ## `skill remove` Удалить агент-скилл, который эта установка поместила в назначение. ```bash 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 модели; - не записывают таргет харнеса. После того как файл присутствует, агент по-прежнему начинает каждую сессию с: ```bash 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-компоненты](../components/skill.md) | ## Связанные страницы | Страница | Зачем | | --- | --- | | [skill-компоненты](../components/skill.md) | другое значение `skill` | | [Observe](observe.md) | `doctor` и `help --agent` после установки | | [Программа харнеса](harness.md) | программа, которая будет читать этот файл | | [Toolchain](toolchain.md) | другой объект, отсутствующий при первом запуске | | [Команды компонентов](component.md) | adopt и publish вида `skill` | | [Быстрый старт для ИИ-агента](../quickstart/agent.md) | шаг Agent Skill первого запуска | !!! note "Флаги из `ai-stp help --agent --json`" Если `help --agent` расходится с флагом на этой странице, CLI выигрывает. Необязательные флаги здесь не перечислены. Читайте их из дескриптора. Каждая команда здесь требует `--target`.