В этой статье расскажу как настроить и автоматизировать процесс обучения скилл. Статья базируется на моем опыте и документации, которую пришлось изучить.

С чего все началось

Дайте одному и тому же ai‑агенту одни и ту же задачу и получите разный результат. В одном случае будут соблюдены архитектурные границы, правила, лучше практики, а в другом он сделает первый попавший рабочий вариант и в добавок забудет дописать тесты. Думаю многие из вас сталкивались с подобным поведением и я не исключение.

Примерно год назад мой опыт работы с ИИ можно было описать так: «он любви до ненависти один шаг». Но видя, что он может делать правильные решения, я хотел приручить ИИ и сделать результат его работы более предсказуемым и подчиненным явным правилам.

Сначала я писал под каждую микро задачу правильный промт, но порой такой подход занимал больше времени чем если бы я решил ее без ИИ. Затем повторяющиеся инструкции стал выносить в отдельные правила, но с ростом каталога агент всё менее последовательно собирал контекст и результат становился еще хуже. Следующим шагом стали Agent Skills — подключаемые пакеты инструкций и ресурсов, но готового набора под свои задачи я не нашёл поэтому начал собирать собственные скиллы.

Если агент ошибался, я руками, или с помощью ИИ, исправлял соответствующие правило или дописывал новое. Такой подход стал более эффективным, но иногда он ослаблял предыдущие правила или входил с ними в конфликт, а я замечал это только после того как задача была выполнена. В итоге скилл менялся, но не всегда становился лучше. На этом фоне родилась идея «сделать обучение агента с подкреплением». Эта идея не нова и применяется в обучении моделей: наблюдение → решение → действие → результат → награда → снова наблюдение. Дальнейший опыт показал, что это оказал вполне рабочий подход, хоть и в измененном виде.

Об этом подходе я буду рассказывать в этой статье и постараюсь ответить на вопросы:

• Как отличить дефект скилла от обычной ошибки при выполнении задачи?

• Что такое память скилла?

• Как система фиксирует ошибку AI‑агента и формирует наблюдение?

• В какой момент дефект превращается в новое правило скилла?

• Какие проверки не позволяют новому правилу нарушить или ослабить прежние?

• Почему накопление знаний не перегружает контекст?

• Для каких задач подходит такой процесс, а в каких случаях он будет избыточным?

Пример проблемы: тесты проходили, дефект оставался

Для наглядности проблемы начну с одной из ситуации, которая была в моем опыте.

Скрубер — функция, которая очищает запись перед отправкой в хранилище логов. В моем случае ей нужно было удалить секреты (пароли и чувствительные данные), но оставить свойства счетчиков, по которым проводился аудит эффективности работы системы. Требование описывала задачу слишком широко: «сохранять все свойства счётчиков», а правило скилла описывала тест как «тест не должен проходить до исправления и не должен зависеть от случайностей» и при этом ни где не звучало что такой граничный (крайний) случай и откуда его брать.

Как следствие агент, который писал код, свёл требование к списку из трёх свойств: promptTokens, completionTokens и totalTokens, а агент, который писал тесты, взял эти свойства и написал к нем тесты. В итоге, тесты проходят, тестовое покрытие почти 100%, и мутационные тесты проблем то же не находят. Но провайдер присылал еще свойство totalTokenCount, которое не попадала в логи, и агент не создавал тесты с новыми, неизвестными свойствами. Данная ситуация порождала два вывода:

1. тесты нужно писать перед написанием кода и формировать их на основе требований и спецификаций.

2. нужно не увеличивать количество тестовых сценариев, а качество описывать граничные случаи.

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

Также в тексте я буду прибегать и к другим примерам, которые лучше раскроют проблематику, описанную в статье.

Как ошибка в проекте становится наблюдением: от проверок до вердикта триажа

Данный подход построен на фундаментальных правилах методологии SRE Postmortem Culture: Learning from Failure — Google SRE и адаптирован под цикл разработки при помощи AI

На этом этапе фиксируется предположение, что дефект скорее всего находится в скилле.

Как устроен рабочий цикл и где в нём появляется признак дефекта скилла

Напомню в общих чертах как выглядит цикл харнесса (подробно он разобран в статье от anthropic Building effective agents):

• сначала он собирает контекст задачи, загружает правила и подходящие скиллы;

• затем запускает агентов, которые пишут тесты и код;

• после этого агенты проверки проводят тесты, гейты, ревью, а в отчётах фиксируют результаты и обнаруженные проблемы;

• далее агент принимает решение: принять работу, вернуть её на доработку или передать оператору (human‑in‑the‑loop).

Оркестратор (агент главно сессии) работает как диспетчер, который маршрутизирует работу субагентов, то есть не принимает ни каких решений. Поскольку статья не об этом я его исключу из процессов, что бы он не создавал лишний шум и не увеличивал когнитивную нагрузку. Пример: я пишу «агент‑кодер передал работу агенту‑ревьюеру», вы держите в голове, что агент‑кодер закончил работу, сформировал отчет, который находится только в рамках сессии, и передал это оркестратору. Оркестратор посмотрел «маршрутный лист», прочитал, что нужно вызвать агента‑ревьюера, вызвал его и передал ему отчет от предыдущего агента.

После того как агент‑кодер (или агенты) закончил свою работу он передает её следующим двум агентам:

• агенту‑привратнику (gatekeeper), тот запускает детерминированные операции (тесты, линтеры и тому подобное) и гейты;

• агенту‑ревьюеру.

Если они нашили ошибку, то задача передается агенту на анализ (в моем случае агент, который пишет код её же и анализирует)

Анализ проходит на основе списка триггеров, который состоит из следующих пунктов:

Если хотя бы один из этих триггеров сработал, то создается наблюдение и работа переходит на следующий этап «триаж», если нет, то задача возвращается на доработку. В противном случае создается отчет о проделанной работе и задача закрывается.

Пример: опечатка в тексте исключения не является ошибкой скилла, поэтому ни один триггер не сработал.

throw new StorageError(‘Не удалось сохранить ПРОФИЬ пользователя’);

Как формируется файл наблюдения

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

• собрать доказательства: вывод проверки, цитату правила, сценарий воспроизведения;

• копить независимые случаи в одном файле, а не плодить новые;

• держать состояние: open, awaiting-recurrence, transferred, closed-local, closed-fixed, rejected;

• остаться первоисточником для обобщения, которое из этого случая вырастет;

• доказать, что цикл сработал: сбой, правка, новая версия, повторный прогон;

• данные которые послужат основание для правки скилла;

• донести работу до ревьюера через итерации (отчёты агентов живут в сессии и до неё не доживают);

В моих проектах на каждое наблюдение создается файл с идентификатором вида OBS-20260521-003.md в каталоге observations

Скрытый текст

На момент исследований и внедрения этого подхода докуметации для стандарта файла наблюдения я не встретил, поэтому ИИ в лице Opus 4.8 сформировал его сам. Он базируется на стандарте скилла (SKILL.md) и имеет две части: заголовок с метаданными и тело в формате markdown. В мое случае заголовк состоит из следующих полей:

Свойство	Описание	Значение в примере
id	Уникальный идентификатор наблюдения. Позволяет ссылаться на него в отчётах, коммитах и связанных записях.	OBS-20260521-003 — первое наблюдение, зарегистрированное 21 мая 2026 года.
status	Текущее состояние наблюдения в его жизненном цикле.	open — открыта, необходимо устранить.
observed_at	Дата первоначального обнаружения проблемы. Не заменяется датой ревью или закрытия.	2026-07-21.
skill	Идентификатор скилла, который предположительно содержит дефект.	python-coding.
skill_version	Версия скилла, для которой зафиксировано итоговое состояние наблюдения. Если в процессе исправления версия изменилась, это должно быть явно согласовано с остальными полями записи.	1.1.0.
source_commit	Коммит проекта, на котором проблема была обнаружена или воспроизведена. Обеспечивает воспроизводимость исходного состояния.	f3278c...a18.
task	Задача, проверка или отчёт, в ходе которых возникло наблюдение. Может содержать идентификаторы связанных находок.	Аудит документации FP-47, находка S8-01.
proposed_class	Предварительный класс изменения, назначенный при разборе наблюдения. Определяет дальнейший маршрут обработки; допустимые значения — C1—C5.	C3 — кандидат на изменение скилла.
related_rule	Правила, инструкции или разделы скилла, с которыми связано наблюдаемое поведение. Помогает определить предполагаемый источник дефекта.	Раздел Purpose и три файла базы знаний скилла.
occurrences	Количество подтверждённых проявлений одной и той же проблемы. Это не число предположений, а число найденных и проверенных случаев.	7 проявлений.
evidence	Список проверяемых доказательств: файлов, строк, каталогов, логов или результатов команд. Каждый элемент должен позволять независимо проверить утверждение.	Ссылки на строки документации скилла и содержимое каталога data/ скилла.
reviewed_by	Идентификатор агента или оператора, который проверил наблюдение и подтвердил решение по нему.	HC-AGENT-003.
reviewed_at	Дата завершения проверки наблюдения.	2026-07-22.
hub_ref	Ссылка на соответствующую запись в скиле или библиотеке скиллов и на доставленное исправление: наблюдение, pull request, коммит и изменение версии скилла. Обеспечивает сквозную прослеживаемость.	Запись hub:OBS-20260724-001, PR№ 10, итоговый коммит и переход 1.0.0 → 1.1.0.
transferred_note	Пояснение нестандартного способа переноса исправления в библиотеку скиллов. Фиксирует отклонение от штатного маршрута и действия оператора.	Агент не имел прав записи, поэтому оператор вручную открыл и слил PR с тем же содержимым.
closure_verification	Многострочный отчёт о заключительной проверке. Содержит установку исправленной версии, повтор исходного сценария, результаты проверок и основание для закрытия наблюдения.	Подтверждены обновление до 1.1.0, устранение неработающих ссылок.

Тело файла наблюдения — человекочитаемая часть записи в формате Markdown. Оно объясняет, что произошло, чем фактическое поведение отличается от ожидаемого, как воспроизвести проблему и почему её источник может находиться в скилле, а не только в коде проекта.

Раздел	Описание
Context	Контекст обнаружения: какая задача выполнялась, какой скилл использовался и при каких условиях появилось нежелательное поведение. Здесь фиксируются только сведения, необходимые для понимания наблюдения.
Expected behavior	Ожидаемое поведение агента или результат применения скилла. Ожидание должно опираться на правило скилла, контракт, проверяемое требование или явно заданное ограничение.
Actual behavior	Фактически полученное поведение и его отличие от ожидаемого. Раздел описывает наблюдаемый результат, а не предполагаемую причину.
Minimal reproduction	Минимальный сценарий, при котором проблема повторяется. В контексте скилла это сокращённая задача, необходимые входные данные, версия скилла и последовательность действий агента, достаточные для повторного получения того же результата.
Universality check	Проверка переносимости наблюдения. Она показывает, возникает ли проблема из‑за особенностей одного проекта или может повторяться в других проектах, использующих то же правило скилла.
Suggested fix	Предлагаемое направление исправления: какое правило, пример, шаблон или проверку скилла следует изменить. Это предварительное предложение, а не утверждённая реализация.

Допустимые значения поля status во фронтматтере файла наблюдения на стороне проекта.

Значение	Что означает	Кто ставит	Что снимает статус
open	запись заведена и работа по ней не закончена; вердикт может быть уже вынесен, а исправление ещё нет	агент‑кодер при создании	исправление по своему классу или отклонение
awaiting-recurrence	класс C3 вынесен, порог подтверждения не взят — один случай и нет сценария воспроизведения вне проекта	ревьюер после триажа	второй независимый случай или приложенный сценарий воспроизведения
transferred	класс C3 вынесен, порог подтверждения пройден, задача передана агенту, который будет заниматься ей в библиотеке скиллов	агент улучшения скиллов	выпуск новой версии скилла и повторная проверка на проекте
closed-local	исправление сделано внутри проекта — код, правила проекта, настройки харнесса; библиотека не затронута	агент улучшения скиллов	ничего, конечное состояние для C1, C2, C4, C5
closed-fixed	скилл исправлен, новая версия установлена, исходный сценарий прогнан заново, проверки прошли без новых регрессий	агент улучшения скиллов	ничего, конечное состояние для C3
rejected	отклонено: ревьюером при разборе или человеком при отказе принять изменение; хранится как история решения	ревьюер или оператор	ничего, конечное состояние

Схематично процесс выглядит следующим образом:

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

В какой момент наблюдение становится дефектом скилла

Триаж — это сортировка задач по значимости, риску, зоне ответственности и тому подобное перед передачей ответственным специалистам.

В данном контексте задача триажа обозначить место первопричины, подтвердить его и передать нужно агенту, то есть или вернуть его в цикл разработки, или запустить процесс улучшения скилла, или отдать оператору, или вовсе закрыть из‑за слабой доказательно базы.

Для этого ревьюер (агент, который отвечат за процесс триажа) классифицирует наблюдения по пяти классам C1–C5 на основе артефактов:

• сопоставление ожидаемого и фактического поведения

• версия скилла

• воспроизводит ошибку на основе наблюдения

• сверяет требования задачи и правил проекта

Агент на предыдущем шаге может предложить класс, но на этом этапе для агента‑ревьюера он будет как дополнительная информация, а не руководство к действию.

Агент‑ревьюер может присвоить класс только из доступных значений таблица классов:

Процесс присваивания класса наблюдению называется вердиктом триажа.

На диаграмме это выглядит так:

Получаем, что класс C3 говорит о том, что дефект скорее всего в скилле, а это не однозначный вывод на основе которого можно запускать процесс исправления. Если реагировать на каждый класс C3, то во‑первых будет перерасход токенов, во‑вторых общее время на работу будет увеличиваться и в‑третьих из скилла получиться помойка.

Именно поэтому для перехода на следующих этап нужны доказательства, которые будут в одном из двух правил:

• наблюдение повторяется в разных задачах либо файлах (в моем случае это три независимых наблюдения);

• оно детерминировано и воспроизводится не зависимо от окружения или проекта.

Это называется порогом подтверждения. Как только он пройден у наблюдения меняется статус на transferred и цикл запускает процесс точечного анализа и исправления на стороне скилла.

Как устроена память скилла

Память скилла не папка с правилами, а цепочка «происхождение → решение → проверка → версия». Она должна не только зафиксировать новое, но и защищать уже проверенные правила.

Что задаёт стандарт и чего в нём нет

Стандарт Agent Skills и документация от Microsoft задаёт формат в котором должен быть каталог с обязательным SKILL.md, инструкциями, скриптами, ресурсами и примерами.

1. Агент всегда видит только name и description из YAML‑фронтматтера SKILL.md.

2. Тело загружается, когда описание совпало с задачей.

3. Остальные файлы открываются по ссылкам из SKILL.md только при необходимости.

Стандарт задаёт формат SKILL.md, общие каталоги и послойную загрузку. Но он не разделяет наблюдения, проверенные знания и правила, не определяет версию и историю развития скилла. Всё перечисленное ниже один из возможных вариантов архитектуры, а не требование стандарта.

Структура скилла в виде дерева

Каталоги скилла на диске

skills/имя-скилла/
├── SKILL.md            обязателен — фронтматтер, порядок работы, маршрутизация
├── ORIGIN.yaml         происхождение, лицензия, политика обновления (по сути служит для лицензирования)
├── README.md           для человека, выбирающего скилл; агенту в работе не нужен
├── agents/             адаптеры под конкретные харнессы; SKILL.md остаётся нейтральным
├── references/         развёрнутые правила по темам
├── scripts/            детерминированные скрипты
├── assets/             статические файлы, которые скилл отдаёт как есть
│
├── knowledge/          проверенные обобщения: приёмы и ограничения, а не обязательные правила
│   ├── INDEX.md        обязателен — при каком условии какой файл читать
│   ├── patterns.md     повторяющиеся приёмы; у каждого условие применимости и ссылка на источник
│   └── pitfalls.md     известные ограничения инструментов, стека и как их распознать
│
├── data/               обезличенные входы и ожидаемые результаты для воспроизведения
│   ├── README.md       обязателен — контракт данных: назначение, формат, источник, лицензия
│   ├── fixtures/       входы для проверок библиотеки; в проект не устанавливаются
│   └── examples/       калибровочные пары «запрос → результат», доступные агенту
│
└── observations/       зафиксированные случаи из реального применения скилла
    ├── INDEX.md        обязателен — правила чтения слоя и перечень принятых записей
    ├── candidates/     записи до ревью; в проект не устанавливаются
    ├── accepted/       прошедшие ревью: доказательства, дата, версия скилла
    └── rejected/       отклонённые; хранятся для истории, в проект не устанавливаются

Обязателен только SKILL.md, остальная структура растёт вместе с содержимым, а место каждой новой записи определяется её обязательностью и уровнем подтверждения.

Два вопроса, которые определяют место записи

Записи разбиты на категории: обязательное правило, проверенное обобщение и зафиксированный случай. Место записи определяется двумя вопросами: «подлежит ли запись исполнению?» и «чем она подтверждена?».

Примеры для TypeScript

Пример 1 — запись обязательная к исполнению

«Не подавляй типчекер и линтер, чтобы проверка прошла: @ts-ignore, @ts-nocheck и eslint-disable запрещены. Но если нужно применить отключить проверку, то его разрешается сделать только на одну строчку и рядом в комментариях описать причину»

• Обязана исполняться? Да. Агент держит это правило каждый раз, когда пишет код по этому скиллу.

• Чем подтверждена? Ничем внутри самой записи. Правило не ссылается на случай из эксплуатации: его правильность держится на ревью изменения и на прогонах самого скилла.

• Где лежит: тело SKILL.md или references/, а в SKILL.md на него ссылается.

Пример 2 — запись не обязана исполняться, но подтверждена

«Модификатор private не доживает до рантайма: при компиляции он стирается, поле остаётся перечисляемым и попадает в JSON.stringify. Если приватность нужна во время выполнения, использовать #field»

• Обязана исполняться? Нет. Исполнять здесь нечего: это свойство языка. Агент открывает запись, когда решает, чем закрыть поле с секретом.

• Чем подтверждена? Ссылкой на разбор последствий структурной типизации в references/type-design.md. Без этой ссылки запись остаётся гипотезой, а гипотезам в knowledge/ места нет.

• Где лежит: knowledge/pitfalls.md.

Пять ступеней памяти

Подробно рассмотрим observations/, knowledge/, data/

Разберём каждый на одном сквозном примере — скилле, который пишет сообщение коммита по git diff.

observations/ — дефекты, которые были определены на этапе триажа в проекте

Роль в памяти. Эпизодическая память: хранит историю дефектов, которые появлялись в процессе эксплуатации скилла. Новое правила попадает только через этот слой и одновременно являются архив доказательств для уже принятых правил.

Что хранится. Записи о конкретных случаях: описание, дата, точная версия и коммит скилла, ссылки на доказательства. Три подкаталога — это три статуса. candidates/ — зафиксированный, но еще не подтвержденный дефект, сюда он попадает как только агент берет его в работу; accepted/ — подтверждённый дефект с описанием и примерами; rejected/ — отклонённый, сохранённый для истории. Статус задаёт сам каталог: команда записи умеет создавать только кандидатов, для переноса в accepted/ требуется проверка.

Когда используется. При диагностике проблемы скилла и при работе над его улучшением. В обычной задаче агент сюда не ходит.

Как используется. Как протокол дефекта:

Агент применил скилл, скрипт классифицировал удаление ошибочного обходного кода как refactor, триаж определил это как дефект скилла. Агент записывает в candidates/: «было удалено пять строк и добавлена одна; предложено refactor, но нужно было fix; версия скилла 1.2.0, вот сами изменения...». После проверки кандидат переносится в accepted/. После исправления у записи в knowledge/pitfalls.md есть первоисточник, на который она ссылается.

В данном слое дефект только фиксируется, что бы он стал правилом его нужно подтвердить (этот процесс будет описано в следующих разделах).

knowledge/ — проверенные обобщения

Роль в памяти. Семантическая память: это подтвержденные справочные данные, которые могут помогать принять решение агенту использующему данный скилл.

Что хранится. Утверждения, у каждого из которых есть три части: сам вывод, область применимости и ссылка на источник — файл правил, фикстуру или принятое наблюдение. В библиотеке слой делится на patterns.md — повторяющиеся приёмы «в такой ситуации работает так...» и pitfalls.md — известные ограничения «здесь инструмент ошибается, распознать можно следующим образом...». INDEX.md задаёт условие чтения каждого файла.

Когда используется. Слой читается не всегда, а по условию из knowledge/INDEX.md. В файле pitfalls.md содержится справочник для ситуаций, когда агент не уверен в ответе скрипта, а в файле patterns.md для ситуаций когда у скилла уже есть отработанный прием.

Как используется. Как справка при принятии решения:

Скрипт предложил текст для коммита refactor(cache): update cache.py. Агент видит, что изменения в основном связано с удалением код, сомневается и открывает pitfalls.md. Там запись: «Удаление скрипт читает как refactor, но обрати внимание на то, что удалено: если убран код, из‑за которого программа работала неверно и поведение исправлено, это fix» — со ссылкой на фикстуру. Агент ставит fix(cache): update cache.py.

Скрипт предложил текст для коммита refactor(cache): update cache.py. Агент видит, что в изменениях только переносы строк, а логика и архитектура кода не изменилась. В этом он узнаёт типовой случай и открывает patterns.md в котором записано: «Применяется, когда наблюдаемое поведение не изменилось: style — для чисто оформительской правки, refactor — когда менялась структура кода» — со ссылкой на справочник типов. Агент ставит style(cache): update cache.py.

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

data/ — данные для воспроизведения

Роль в памяти. Это «опора» остальных слоёв: если observations/ — “что случилось”, а knowledge/ отвечает «что мы поняли», то data/ отвечает «на чём это можно повторить». Благодаря этому слою дефект можно воспроизвести и увидеть наглядные доказательства и сравнить с ожидаемым результатом.

Что хранится. Обезличенные синтетические входные данные и ожидаемые результаты, без кода проекта и без секретов. fixtures/ — набор условий для проверок самим скиллом, по одному нарушению на каждое правило скрипта; examples/ — пример «запрос → результат» в минимальном объёме, которые наглядно показывают, что считать правильным результатом.

Когда используется. fixtures/ — при проверке скилла в библиотеке: каждое правило скрипта подтверждается входом, на котором оно обязано сработать. examples/ — агентом в проекте, когда нужно свериться с ожидаемым форматом.

Как используется. Как эталонный вход с известным ответом:

Запись из knowledge/pitfalls.md — “удаление скрипт читает как refactor, но если убран код, из‑за которого программа работала неверно, это fix” — ссылается на фикстуру data/fixtures/mixed_change.diff. Это маленький синтетический diff, где исправление в основном удаляет код: прогнав на нём скрипт, любой может воспроизвести ошибочный вердикт refactor и убедиться, что утверждение записи верно. На этой же фикстуре проверяют, что новая версия скилла закрывает дефект. Рядом в examples/ — пара для штатной работы: feature_change.diff → feat(src): update feature.py, обычный вход и правильный ответ.

Как три слоя работают вместе

Один и тот же дефект отражается во всех трёх слоях, но в разных представлениях.

Убери любой слой и память деградирует: без observations/ пропадает история происхождения нового правила; без data/ их нельзя перепроверить; без knowledge/ агент будет заново выдавать дефекты, проект будет формировать новые наблюдение и тратить ресурсы на исправления ошибок.

Происхождение, версия и где записана метаинформация скилла

Для корректной работы «обучения на дефектах» нужно исключить ситуации, когда скилл в проекте был исправлен руками, в проекте установлена предыдущая версия скилла, или есть конфликт имен. Поэтому номер версии не лежит в самом скилле и находится на уровне библиотеки, а при установках формируется lock‑файл в проекте, с метаданными скилла. Именно из него берутся данные для фронтмапера при формировании файла наблюдения.

В таблице приведена вся метаинформация и где она находится:

Как дефект превращается в правило скилла

Что бы из дефекта сделать правило ему нужно пройти через несколько этапов проверки. Этап может состоять из нескольких шагов или один шаг может охватывать несколько этап. Тут главное понять принцип работы.

Маршрут целиком выглядит так:

Дальше каждый шаг разобран отдельно.

1. Пройти входной контроль

Аген связывает четыре условия:

• вердикт вынес ревьюер на стороне проекта и присвоил класс C3;

• пройден порог подтверждения (минимум три независимых повторения или один детерминированный случай);

• наблюдение привязано к версии и коммиту скилла;

• доказательства воспроизводятся без кода проекта.

Пример. Вернёмся к скруберу из начала статьи. Агент писал и код и тесты в рамках одной задачи, а граничные случае в одном файле тестов. Триаж выносил правильный вердикт, но для перехода на этап исправления не хватало разных и независимых повторений. Я заметил это наблюдение, провел анализ и сверился с документацией провайдера. После этого в документации проекта явно указал totalTokenCount и запустил промт на проверку. Именно это помогло сформировать детерминированный случай и пройти входной контроль.

Если контроль не проходит, работа завершается.

2. Зафиксировать дефект в качестве кандидата

Агент записывает кандидата на дефект и сценарий воспроизведения в observations/candidates/OBS-YYYYMMDD-NNN.md, а данные для воспроизведения в data/fixtures/<произвольное-название.md/.py>

Пример. В observations/candidates/OBS-20260726-001.md записывается дефект: «Тестовые случаи созданы из реализации скрубера, а не из спецификации провайдера. Тесты проверяют три свойства, описанные в коде, и не проверяют четвёртое — totalTokenCount, объявленное в спецификации». Рядом в data/fixtures/case_provenance.py кладётся код для воспроизведения: урезанный пример с ALLOWED = {"promptTokens", "completionTokens", "totalTokens"}, тесты, созданные на основе этого перечисления, и запись спецификации из четырёх свойств. Прогон на этой фикстуре показывает только 3 сценария для перечислений из кода, но сценария для свойства из документации нет — это и есть доказательство дефекта.

3. Сформулировать правило и определить его адрес

На этом этапе из наблюдения, созданного на предыдущем шаге, создается минимальное правило. Определяется какому скиллу он принадлежит и в каком месте должно находится это правило.

Пример. «Перечень проверяемых свойств выводится из спецификации, а не из реализации». Ни totalTokenCount, ни скрубер в него не входят иначе правило стало бы правилом одного проекта. Правило не зависит от языка и фремворка, поэтому оно попадает в скилл тестирования. Место записи определяется в references/.

Важно. Созданное правило не записывается в файлы и держится только в сессии агента.

4. Доказать дефект заведомо непроходящей проверкой

По аналогии с TDD, перед тем как вносить изменения в скилл нужно создать кейсы, которые он не будет проходить. Для текстового правила обычно нужны две формы:

Что бы приступить к внесению исправлений в скилл хотя бы одна из перечисленных проверок не должна пройти. Если все проверки проходят значит дефект не доказан, создается файл с описанием в observations/rejected/ и работа завершается.

5. Изменить правила в скилле

Агент добавляет в правила текст в скилл, который был сформирован на третьем шаге. Так же он добавляет тесты, которые проверяют его целостность, и правила, и скилла.

После этого запускает тесты и eval‑кейсы. Если все тесты и кейсы прошли, переходит на следующих шаг, если нет, то меняет формулировку правила и еще раз их прогоняет.

6. Прогнать все сценарии и тесты для этого скилла

На предыдущем шаге прогонялись тесты и кейсы только для нового правила, на этом прогоняются все тесты и кейсы, что бы убедиться в правильной работе остальных правил.

7. Зафиксировать версию и передать на ревью оператору

Если правила скилла изменились, то меняется его версия и записывает в CHANGELOG описание изменений. Далее агент создает коммит и PR, на этом его работа завершается.
Человек, он же оператор, проверяет изменения и есть замечаний нет, то их заливает в ветку main.

Примечание. Процесс может быть другой, тут важно подчеркнуть, что в нем участвует человек.

8. Проверить исправление в проекте, где дефект был найден

Работа над дефектом заканчивается только тогда, когда он закрыт и это подтверждено там где он был найден, то есть проблема больше не повторяется. Для этого скилл нужно обновить до последней версии и попросить агента еще раз прогнать сценарий. Только после того как он перестает воспроизводиться, наблюдение получает статус closed‑fixed. Если исходный сценарий не проходит или появляется новая регрессия, наблюдение переоткрывается с новыми данными и процесс запускается заного.

Условие для шагов с проверками: тот же вендор и модель, что в проекте где установлен скилл

У каждого вендора (anthropic, deepseek, openai, YandexGPT) свои рекомендации по формулировке инструкций, и местами они расходятся между собой. Поэтому скилл должен «обучаться» на той же модели и на том же усилии, что при работе в проекте.

Чем приходится расплачиваться

Увеличивает ли скилл собранный на таких правилах потребляемые ресурсы?

Нет. Скилл, базируется на правилах «загрузка по требованию» и весь основной функционал соответствует требованию стандарта. Подробно этот процесс описан в статьях: Effective context engineering for AI agents, где описана тема контекст, и в спецификации Agent Skills, где описано как устроен скилл и как агент собирает только нужные правила из скилла для эффективной работы.

Увеличивает ли процесс триажа потребления ресурсов?

Да. Эта цена за качество к проекту. На мой взгляд процесс триажа имеет смысл подключать если у вас проект чуть выше простого и от него требуется надежность, масштабируемость и удобство сопровождения. Он убережет от разногласий правил, неточных формулировок и деградаций в AI.

Увеличивает ли процесс обучения скилл потребления ресурсов?

Да. Эта цена за высокие требования к его навыкам. Поэтому не всегда нужно использовать такой подход.

Выводы

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

Этот подход будет оправдан когда сойдутся три условия:

• одна и та же ошибка агента повторяется в разных задачах и файлах;

• правила нужны больше чем одному проекту;

• цена пропущенного дефекта выше стоимости одного цикла(проверки линтера, тесты, гейты и так далее).

Если у Вас один проект и скилл нужно «обучать», то можно не выносить его в отдельный репозиторий, будет достаточно рядом со скиллом хранить короткий CHANGELOG и каталога наблюдений. Я начал именно с такого подхода, но столкнулся с тем, что такой процесс сложнее контролировать и поэтому перешел к отдельному репозиторию, в добавок этот опыт нужно было переносить и на другие проекты.

Что я понял

В моменте данный подход может увеличивать и время и расход токенов, но на дистанции получаешь тонко настроенный скилл, который со временем начинает выполнять более точные инструкции, что в свою очередь будет способствовать быстрому закрытию задач и экономии токенов. Сейчас на просторах github можно найти много разных наборов скиллов, поэтому создавать свои имеет смысл только когда у вас свои строгие требования к задачам и проектам.

Примеры из личного опыта

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

1. В процессе работы агента, заметил, что он создает «магические» строки. Спросил его об этом, приведя пример. Он подтвердил, что это проблема агента, который писал код, завел наблюдение, сам вернулся на этап триажа, проанализировал и вернул на доработку.

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

P. S.

Не буду лукавить и говорить, что я полностью придумал данный подходи и сам его реализовал. Во многом мне помогали нейросети, но мысли о такой идеи у меня зарождались еще более полугода назад. К данной реализации приступил еще в марте, прошел через ряд неудач, выложил вторую версию скиллов на github и в этой статье постарался описать свой опыт. Статью постарался сделать лаконичной и в то же время раскрыть тему, но если у вас возникли вопросы, задавайте, постараюсь на все ответить.