Перейти к содержимому
Leonidov.DEV

Навыки для ИИ-агентов: 5 причин брать исходник

Инженерия
Навыки для ИИ-агентов: 5 причин брать исходник

Ассистент знает PHP и не знает мой движок. Дайте ему задачу в незнакомой подсистеме, и он напишет что-то правдоподобное, назовёт метод, которого не было, а платить за находку будет ревьюер. Навыки для ИИ-агентов закрывают этот разрыв документом, а не надеждой.

Код: Atomic-Framework-Skills, лицензия GPL-3.0.

Двенадцать файлов, по одному на область фреймворка, каждый это SKILL.md с заголовком YAML. На то, что в них попало, повлияли пять причин.

Причина 1: исходник это единственный авторитет

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

Правило стоит времени в день написания и экономит его в день чтения. Когда движок переименовывает метод, навык ошибается заметно, а когда догадывается модель, ошибка незаметна.

Причина 2: одна область на файл, потому что контекст конечен

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

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

Причина 3: описание это интерфейс

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

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

Причина 4: пометки о ловушках пишут после ошибки

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

Hook это не Event. apply_filters возвращает значение. Nonce привязан к IP и User-Agent. Каждая из этих строк предотвращает класс неверного кода, которого не предотвращает страница правильной документации.

Причина 5: карта это не ответ

Карта документации перечисляет 44 документа по темам с путём движка, который каждый описывает. Она живёт отдельным навыком, потому что найти авторитетный документ это другая работа, чем ответить на вопрос, и модель, которая нашла нужный файл, читает настоящий текст вместо моего пересказа.

Этот файл стареет быстрее всех: каждый новый документ добавляется руками, а устаревшая карта хуже отсутствующей, потому что отправляет агента в уверенном направлении.

Чего формат не может

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

Он также не делает модель аккуратной. Он делает справку конкретной, и это превращает «правдоподобно» в «проверяемо».

Отдельно стоит помнить про версии: навык, не сверенный после выпуска фреймворка, называет методы со старыми именами и звучит при этом так же уверенно, как верный.

Чему это учит в текстах для агентов

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

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

Навыки выходят под GPL-3.0 и ставятся указанием редактора на папку.