Cli

---
title: "CLI агент-скилла"
description: "Установить, проверить и удалить канонический Agent Skill ai-stp в указанном назначении, не компонент вида skill."
---

# 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`.