Ассистент знает 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 и ставятся указанием редактора на папку.