# Настройка скиллов для агентов

Сделай так, чтобы AI-скиллы из поставки [Testo](https://github.com/php-testo/testo) стали доступны агентам, которые работают над этим проектом. Иди по шагам по порядку и отчитайся о результате.

В пакете Testo лежит по скиллу на сценарий: написание тестов, провайдеры данных, тестовые дублёры, асинхронные тесты, бенчмарки, покрытие, мутационное тестирование, миграция с PHPUnit, разработка плагинов, правка `testo.php`. `llms.txt` говорит, *что* умеет API, а скилл — *когда* к чему тянуться и где подводные камни; к некоторым приложены готовые скрипты. Лежат они внутри установленного пакета, поэтому агент увидит их только после того, как их разложат туда, куда он смотрит.

Этим и занимается Composer-плагин [`llm/skills`](https://packagist.org/packages/llm/skills).

## 1. Собери каталоги агентов

Claude Code читает `.claude/skills/`, Cursor — `.cursor/skills/`, у других агентов свои привычные пути. Спроси, какие агенты работают над проектом, и посмотри, что уже есть в репозитории: из этих путей получатся алиасы.

Целевая раскладка: одна настоящая папка (`.agents/skills`, не привязанная к конкретному агенту) и по ссылке на неё для каждого агента, чтобы все читали одни и те же файлы. В проекте с единственным агентом целью можно сделать сразу его собственный путь.

## 2. Заранее разреши плагин

Composer спрашивает разрешение на запуск плагина, а шелл агента — неподходящее место, чтобы наткнуться на интерактивный вопрос. Добавь запись в `composer.json` до установки:

```json
{
    "config": {
        "allow-plugins": {
            "llm/skills": true
        }
    }
}
```

## 3. Установка и настройка одной строкой

```bash
composer require --dev llm/skills
composer skills:init --quick --no-interaction \
    --target=.agents/skills --alias=.claude/skills --alias=.cursor/skills
```

`skills:init` создаёт `skills.json` в корне проекта и сразу синхронизирует скиллы, а флаги решают, что попадёт в файл:

- `--quick` берёт все оставшиеся ответы из обнаруженной раскладки проекта и спрашивает одно подтверждение; `--no-interaction` делает решение окончательным — то, что нужно для запуска из скрипта.
- `--target=PATH` — настоящий каталог со скиллами (по умолчанию `.agents/skills`).
- `--alias=PATH` — повторяемый флаг, по одному на путь агента; если он передан хоть раз, обнаруженный список заменяется целиком.
- `--trust=PATTERN` — повторяемый, для собственных вендоров проекта, которые везут скиллы. Testo есть во встроенном списке доверенных, как и любой пакет, подключённый напрямую, так что для голой настройки Testo он не нужен.
- `--no-auto-sync` — отказ от повторной синхронизации после `composer install` / `update`. Авто-синхронизация включена по умолчанию; оставь её включённой, чтобы скиллы соответствовали установленным версиям.
- `--no-discovery` — учитывать только пакеты, которые объявили `extra.skills`. Обнаружение включено по умолчанию, благодаря ему подхватывается пакет, который просто везёт файлы `SKILL.md`.
- `--force` — перезапуск поверх существующего `skills.json`. Без него команда откажется перезаписывать файл, так что сначала проверь, есть ли он, и доложи, что в нём лежит, вместо того чтобы продавливать перезапись.

Если ничего не делать, в проекте без конфигурации плагин сам предложит то же самое при следующем `composer install` / `update` — одним подтверждением. Но для этого нужен интерактивный терминал, поэтому запускай команду явно.

## 4. Проверка

```bash
composer skills:show             # что синхронизируется, что пропущено и почему
composer skills:update           # ручная пересинхронизация; --dry-run покажет без записи
```

Шаг закончен, когда в целевом каталоге лежат каталоги скиллов `testo-*`, а каждый путь-алиас ведёт в цель. Строка `[skip] not trusted` называет донора, которому не хватает шаблона в `--trust`; каталог, где уже лежат собственные файлы, будет показан в отчёте, а не заменён ссылкой — такой случай разбирается вручную.

Локальные правки переживают синхронизацию: перезаписываются только файлы, которые действительно приходят от донора, так что положенный рядом со скиллом `local.md` останется на месте.

## 5. Конфиг — в git, содержимое — в `.gitignore`

`skills.json` место в репозитории рядом с `composer.json`: именно он делает настройку воспроизводимой для всей команды. Целевой каталог и ссылки-алиасы генерируются из `vendor/` и пересобираются авто-синхронизацией, поэтому порекомендуй добавить их в `.gitignore`; спроси, прежде чем коммитить их вместо этого, — команде, которой скиллы нужны без запуска Composer, удобнее держать их под контролем версий.

## 6. Отчёт

Отчитайся: что объявлено в `skills.json`, какие пути агентов ведут в цель, лежат ли на месте скиллы `testo-*` и что `skills:show` пропустил и по какой причине.