Как устроена система скиллов

MCP даёт агенту доступ к продукту. Скиллы — правила, по которым он этим доступом пользуется. Как их поставить, описано отдельно; что делает каждый — в справочнике. Здесь про то, почему их много и как они складываются в одно целое.

Скилл — часть продукта, а не документация о нём

Скилл — Markdown-файл, который агент читает и исполняет буквально: какой инструмент вызвать, в каком порядке, что записать в тикет, когда остановиться. Без скиллов доступ остаётся, а поведение исчезает: агент по-прежнему может создавать ноды, но будет делать это как придётся и терять контекст между сессиями.

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

Как скилл вызывается

Двумя способами, и второй в жизни используется чаще.

Слэш-командой — когда вы точно знаете, какой скилл нужен:

/execute-task AF-TASK-42

Обычной просьбой — скилл подхватывается сам, по описанию. У каждого во фронтматтере перечислены триггеры: и формулировки задачи, и слова, которыми о ней просят, на двух языках. Поэтому всё это работает без имени скилла:

возьми AF-TASK-42

надо добавить экспорт в CSV, разбей на задачи

подключи этот репозиторий к Flownix

Отсюда две практические вещи. Называть скилл не нужно — достаточно сказать, что вы хотите получить; список скиллов полезен, чтобы понимать, что вообще умеет продукт, а не чтобы выбирать из него перед каждой просьбой. И триггером бывает отказ сервера: flownix-write-spec вызывается в том числе на упоминании proposal_not_approved, а spec-first-change — на spec_first_not_approved, поэтому агент, упёршийся в гейт, находит нужную инструкцию сам.

Кто чем владеет

Скиллов много не потому, что процедура сложная, а потому что у каждого куска процедуры один владелец.

Правило одного владельца

Формат спеки описан в одном скилле, flownix-write-spec. Остальные на него ссылаются и не пересказывают.

Это не аккуратность, а вывод из ошибки. Формат однажды оказался продублирован в пяти скиллах, и дальше произошло предсказуемое: копии разъехались, а читают всегда разъехавшуюся. Поэтому у каждого правила один дом, и в остальных местах стоит ссылка — даже там, где пересказать было бы удобнее для читателя.

Передача управления

Скиллы не образуют жёсткого конвейера, но между ними есть переходы, и один из них важен.

plan-feature читает политику проекта до того, как создаст первую ноду. Если включён spec-first, он не разворачивает дерево задач, а передаёт работу spec-first-change. Порядок проверки именно такой не случайно: узнать про режим после того, как дерево создано, поздно — а именно так и было бы, если бы скилл читал политику в середине процедуры.

Тот же принцип в execute-task: упёршись в отказ гейта, он не подбирает обход, а отправляет агента назад к change. Отказ, который не называет выход, агент попробует обойти — и это тоже проверено.

Что меняется от политики проекта

Три политики спеки (подробно) меняют не только поведение сервера, но и то, какой скилл ведёт работу:

Политика доезжает до агента двумя путями: он читает её вызовом get_project_policy и видит в файле .flownix, который пишется при подключении проекта. Второй путь существует затем, чтобы правило было известно до первого вызова, а не после первого отказа.

Свои скиллы рядом с продуктовыми

Скилл — обычный Markdown, и ваши собственные лежат в том же каталоге. Синхронизация их не трогает: в отчёте sync-skills они попадают в раздел LOCAL_ONLY и остаются как есть.

Смысл разделения в том, что продуктовые скиллы описывают, как работает Flownix, а ваши — как работает ваша команда. Первые обновляются вместе с продуктом, вторые живут своей жизнью, и мешать их в один файл значит потерять либо одно, либо другое при следующем обновлении.

Если агент ведёт себя не так

По порядку, от самого частого:

1. Скиллы устарели — /sync-skills. Отдельно проверьте, что снятые скиллы удалены: переименованный скилл иначе остаётся лежать рядом с новой версией, и агент читает устаревшую инструкцию, ничем себя не выдавая.
2. Агент не читал flownix-basics — остальные скиллы предполагают его прочитанным, и без него агент не знает ни про компоненты, ни про то, что тикет служит памятью.
3. Политика не та, что вы думаете — get_project_policy отдаёт её вместе с человекочитаемым объяснением, что она требует. Сверьте с тем, что лежит в .flownix: расхождение означает, что файл устарел.
4. Скилл прочитан, но не тот — при включённом spec-first процедуру ведёт spec-first-change, а не plan-feature; если агент разворачивает дерево задач, он читает второй.

Дальше

• Установка скиллов — четыре способа поставить и один держать в актуальном состоянии
• Справочник скиллов — что делает каждый
• Режимы спеки — три политики
• Режим spec-first — порядок работы, которым владеет spec-first-change