Асистент знає 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 і ставляться вказівкою редактора на теку.