Пастка оргструктури: як організувати AI-скіли та агентів

Є один баг-репорт, який ніяк не йде мені з голови. Людина мала в Claude Code непогану колекцію скілів — невеличких інструкцій, кожна з яких вчить AI добре робити якусь конкретну роботу. Вона попросила виконати одну з цих робіт. І замість того, щоб відкрити інструкцію, написану саме під це, Claude з нуля накидав новий одноразовий скрипт — ніби скіла взагалі не існувало.

А з погляду моделі його й не було. Список скілів переріс бюджет, який інструмент під нього відводить, і описи — єдине, що модель читає, перш ніж обрати, — мовчки обрізалися. Скіл лежав на диску. Просто в нього більше не було бейджика з іменем. (anthropics/claude-code#64606)

У цій історії вся проблема в мініатюрі. Ми збираємо скіли, як застосунки на телефоні, а агентів будуємо так, ніби наймаємо компанію: CTO, голова маркетингу, коуч, стратег. Виглядає організовано. І тихенько працює проти нас.

Почав я з простої здогадки. Хіба не було б чистіше, якби скіли не були доступні всім, а належали конкретним агентам — так, як інструменти належать конкретній майстерні? Тож я зробив те, що тепер роблю з кожним подібним питанням: паралельно відправив трьох агентів-дослідників. Один склонував і прочитав тринадцять найпопулярніших агентних сетапів на GitHub. Другий перерив практичні розбори й треди на Hacker News. Третій порівняв, як великі агентні фреймворки вирішують ту саму задачу, і витягнув цифри з бенчмарків.

Здогадка виявилася наполовину правильною. Ось що вони принесли.

Спершу: як скіл узагалі потрапляє до моделі

Скіл — це папка з файлом SKILL.md. Угорі — короткий заголовок:

---
name: release-notes
description: Write release notes from merged PRs. Use when the user asks
  for a changelog, release notes, or "what shipped this week".
---

На початку кожної сесії модель не бачить твоїх скілів. Вона бачить список: назву й опис кожного скіла. Повні інструкції підвантажуються лише тоді, коли модель вирішує, що скіл підходить. Це називається progressive disclosure, і це гарний дизайн — сотня інструкцій коштує тобі сотню коротких рядків, а не сотню документів.

Але в списку є бюджет. У Claude Code це приблизно 1% контекстного вікна, і кожен запис обмежений 1 536 символами. Коли список переповнюється, першими викидаються описи скілів, якими ти користуєшся найрідше. Назви лишаються. Сенс зникає. (docs)

Як швидко це б'є? В одному невеликому експерименті поставили 160 скілів-пустушок: Claude Code зберіг описи лише для приблизно 20 із них, а модель знайшла нуль із трьох скілів, що лишилися в списку тільки з назвою (Rulestack). Вибірка крихітна, назви синтетичні — але це збігається з баг-репортами. Vercel провели чистіший eval на документації власного фреймворку і з'ясували, що у 56% випадків скіл так і не викликався (Vercel).

Отже, правило номер один: скіл без опису — це скіл, якого не існує.

Є три перемикачі, які вирішують, хто бачить скіл:

Зверни увагу на пастку в середньому рядку. Якщо сховати скіл від себе, список моделі коротшим не стане. Якщо твоя мета — фокус, то важить останній перемикач. Або просто не ставити скіл узагалі.

Шість сетапів, які люди реально використовують

Кожен популярний репозиторій, який я прочитав, обрав один із них — часто навіть цього не проговорюючи. Жоден не є хибним. Кожен ламається передбачувано.

1. Шухляда — усе глобально

Ти знаходиш класний каталог, запускаєш інсталятор — і тепер у тебе триста скілів. Звідси стартує більшість великих колекцій: каталоги з інсталяторами, мега-бандли з профілями «встановити все».

Плюси: думати не треба. Усе на відстані одного слеша. Мінуси: список переповнюється, описи обрізаються, і модель перестає знаходити потрібне. Ти платиш за скіли, яких ніколи не читав. Один коментатор на Hacker News сказав прямо — люди пачками ставлять бандли на п'ятдесят тисяч токенів, яких не розуміють (HN).

Показово, що найбільші бандли тепер самі себе застерігають. Один із найзірковіших сетапів, із сотнями скілів, постачається з профілями встановлення — minimal, core, developer — і радить почати зі спільних правил плюс одного пакета, яким ти реально користуєшся (ECC).

2. Роутер — одні вхідні двері

Замість того, щоб показувати в списку сімдесят скілів, ти показуєш один: хаб, який знає, де живуть решта.

---
name: gstack
description: Router for the gstack skill suite.
triggers:
  - gstack
  - which gstack skill
---

Це з garrytan/gstack, і там це поміряли: перелік усіх скілів займав близько 18 000 символів і обрізався; режим роутера — близько 6 700. BMAD-METHOD робить те саме з хаб-скілом bmad.

Плюси: список лишається коротким; один хороший опис веде до багатьох скілів. Мінуси: один зайвий крок, і роутер треба тримати актуальним. Клади підскіли в папку references/, на яку посилається роутер, а не вставляй їх списком — як зазначають у gstack, вставлений список застаріває.

3. Майстерня — скіли, що носять власних агентів

Це було найближче до моєї початкової здогадки — і найелегантніше з усього, що я знайшов. Одна з найзірковіших колекцій скілів на GitHub, obra/superpowers, постачається з нулем визначень агентів. Натомість субагенти живуть усередині скіла, який ними користується:

skills/subagent-driven-development/
  SKILL.md                 ← the controller: one fresh worker per task
  implementer-prompt.md    ← an "agent" that exists only here
  task-reviewer-prompt.md  ← and its reviewer

Скіл запускає свіжого виконавця на кожну задачу, потім рев'юера, а передача контексту пишеться у файли, а не вставляється в розмову. Власний skill-creator від Anthropic робить так само: оцінювач, порівнювач і аналізатор — приватні файли, які скіл читає лише тоді, коли вони потрібні.

Плюси: агенти справді приватні. Ніхто інший їх не бачить, і в жодній іншій сесії вони нічого не коштують. Мінуси: їх не можна перевикористати між скілами, і ти втрачаєш приємні фічі справжнього визначення агента — власний список інструментів, модель, дозволи.

У нотатках superpowers є два уроки, які варто вкрасти. Один запуск займав 42 000 символів, і 99% із них — вставлена історія; тож артефакти передаються файлами. А воркерам заборонено запускати власних рев'юерів, бо кожен такий рев'юер просто дублював рев'ю, яке контролер і так проводив.

4. Ящик з інструментами — плагін як одиниця

Плагін пакує агентів, скіли, хуки й сервери інструментів в один пакет, який можна встановити. wshobson/agents розбиває приблизно двісті агентів на дев'яносто чотири плагіни, у середньому по п'ять-шість компонентів у кожному, з девізом install only what you need. Офіційні плагіни Anthropic теж невеликі — від одного до дев'яти агентів у кожному.

Найкращий first-party приклад скоупінгу — плагін безпеки від Anthropic. Скіл чітко оголошує, яких агентів він може викликати:

# skills/claude-security/SKILL.md
allowed-tools:
  - Agent(claude-security:scan-inventory, claude-security:scan-verifier, ...)

а агент-верифікатор оголошує, що може викликати він:

# agents/scan-verifier.md
description: Restricted read-only verifier ... not for direct invocation.
tools: Read, Glob, Grep, Bash, Agent(claude-security:explore)

Плюси: це справжній скоупінг. Скіл живе в одній коробці з агентами, які ним користуються, і ти вмикаєш і вимикаєш цілі коробки під кожен проєкт. Мінуси: тепер ти підтримуєш пакети. І дрібний шрифт усе ще змінюється: у відкритих issues пишуть, що вкладені allowlist-и Agent(...) іноді ігноруються (#92259), а налаштування для приховування скілів поки не діють на скіли з плагінів (#98220).

Пара слів про очевидну альтернативу. В агентів Claude Code є поле skills:, і виглядає воно саме як той скоупінг, якого я хотів:

---
name: release-manager
skills: [release-notes, changelog-style]
---

Але ні. Воно попередньо завантажує повний текст цих скілів в агента на старті — і нікого іншого їх не позбавляє. У документації сказано, що воно керує попереднім завантаженням, а не доступом (docs), agent teams його повністю ігнорують, а запит приховати скіл від головної сесії досі висить відкритим issue (#12633). У тринадцяти репозиторіях, які я прочитав, я не знайшов жодного реального використання.

5. Оргструктура — агенти з посадами

Це сетап, який усі будують першим, бо він накладається на те, як ми вже думаємо про роботу. Агент-CTO. Агент-маркетолог. Продакт-менеджер. Коуч.

---
name: cto
description: Chief Technology Officer. Owns architecture, code quality,
  deployments and engineering decisions.
---

Це відчувається як делегування. Дані кажуть, що здебільшого це не так.

Власна настанова Anthropic від січня — пряма: ділити роботу за межею контексту, а не за роллю. Розподіл на планувальника, виконавця й тестувальника перетворювався на зіпсований телефон, де кожна передача губила деталі (Anthropic). На Hacker News люди, які пробували персони PM і бекенд-розробника, писали, що ті працювали гірше за одного звичайного агента, а один коментар підсумував це так: будуй агентів навколо задач, а не посад (HN). Один автор, який запустив сім рольових агентів, виявив, що вони видавали пристойні чернетки, які ніколи не бачили роботи одне одного: продуктовий агент викинув фічу, на яку модель даних досі розраховувала, а зводити суперечності довелося людині. Найціннішим із семи виявився агент-опонент, який усе рев'юїв (Rezvani).

Чому так? Оргструктура — це рішення для людських обмежень: ми не можемо тримати в голові всю компанію, тож ділимо її за експертизою. Модель уже має експертизу. Її обмеження інше — це контекст. Поділ за посадами ріже контекст саме там, де не треба.

Плюси: легко пояснити, легко маршрутизувати («спитай CTO»). Мінуси: поверхові спеціалісти, втрачений контекст, суперечності, які доводиться зводити самому.

Якщо ти любиш персони, є дешевший спосіб їх зберегти: зроби їх скілами. BMAD не постачає жодного файлу агента; «John, the Product Manager» — це скіл, який головний агент вдягає, як капелюх, і вся розмова при цьому лишається перед очима.

6. Рій — агенти, що спілкуються між собою

На протилежному краю: багато агентів, що працюють одночасно, пишуть одне одному й розбирають задачі зі спільного списку. У Claude Code для цього є експериментальний режим agent teams; репозиторії на кшталт ruflo (колишній claude-flow) будують hive-mind із координатором-королевою і спільною пам'яттю.

Іноді це вражає. В Anthropic шістнадцять агентів написали компілятор C взагалі без оркестратора — кожен брав lock-файл на задачу і мерджився через git. Це коштувало близько $20 000 у токенах, а найбільший урок полягав у тому, що все спрацювало лише завдяки майже ідеальному набору тестів. Коли всі агенти працювали над одним великим завданням, вони всі впиралися в той самий баг і перезаписували роботу одне одного (Anthropic).

Один інженер використав agent team для розслідування продакшн-інциденту: root cause приблизно за десять хвилин замість очікуваних тридцяти-сорока п'яти, ціною втричі-вчетверо більших витрат (magarcia). Для аварії — варто того. Для одруківки — ні.

Плюси: справжній паралелізм; агенти можуть оскаржувати гіпотези одне одного. Мінуси: токени ростуть разом із кількістю агентів, на будь-чому послідовному координація з'їдає весь виграш, і, як сказано в одному огляді популярного swarm-фреймворку, вузьким місцем стає дизайн (Maggie Appleton). Навіть фреймворки відступають: один популярний сетап прибрав свій swarm-скіл на користь малих команд і видалив міст між командами, бо ним ніхто ніколи не користувався (oh-my-claudecode).

Як з'єднувати агентів

Якщо зняти брендинг, кожен фреймворк — Claude Code, Agents SDK від OpenAI, LangGraph, CrewAI, ADK від Google — пропонує ті самі чотири форми:

Цифри про те, коли це окупається, напрочуд узгоджені:

• Мультиагентна дослідницька система Anthropic обійшла одного агента на 90% у дослідницьких задачах — використовуючи приблизно в 15× більше токенів, ніж звичайний чат. Більшість кодингу вони вважають поганим кандидатом (Anthropic).
• Google протестували 180 конфігурацій: центральний координатор дав +81% на паралельних задачах, але кожен мультиагентний варіант ставав на 39–70% гіршим на послідовному плануванні. Незалежні агенти підсилювали помилки до 17×; центральний координатор тримав це на рівні близько 4× (Google Research).
• Дослідження понад 1 600 мультиагентних трейсів показало, що найефективніший окремий фікс — додати крок верифікації: +15,6% (MAST).
• Cognition, які свого часу гучно написали «Don't Build Multi-Agents», у квітні оновили свою позицію: це працює, коли запис лишається однопотоковим, а додаткові агенти дають мислення — рев'юер із чистим контекстом, сильніша модель для ескалації (Cognition).

І форма, яка постійно повторюється в репозиторіях, що працюють: тонкий оркестратор, воркери зі свіжим контекстом, стан у файлах і гейт рев'ю. Ось як get-shit-done оголошує воркера — зверни увагу, тут сказано, хто має право його запускати:

---
name: gsd-executor
description: Executes plans with atomic commits. Spawned by the
  execute-phase orchestrator.
tools: Read, Write, Edit, Bash, Grep, Glob
---

Увесь стан проєкту живе в .planning/STATE.md і ROADMAP.md — ніколи лише в чаті. Будь-який агент може померти, а наступний підхопить роботу з файлу.

Якщо тобі потрібен оркестратор, який може викликати лише конкретних воркерів, Claude Code дозволяє це прописати, коли він працює як головна сесія:

---
name: coordinator
tools: Agent(researcher, implementer, reviewer), Read, Grep
---

Сетап, з якого я почав би сьогодні

Якби я налаштовував усе з нуля, знаючи те, що знаю зараз:

1. Тримай глобальний список малим — двадцять-тридцять скілів, якими ти реально користуєшся, кожен з описом, що починається зі слів, які сказав би користувач. Перевір, що інструмент показує насправді (/doctor у Claude Code оцінює вартість списку).
2. Збирай родини скілів за роутерами. Дев'ять кроків «daily review» стають одним скілом із дев'ятьма reference-файлами.
3. Небезпечні скіли — лише для користувача. Усе, що витрачає гроші або надсилає повідомлення, отримує disable-model-invocation: true. Заодно це звільняє місце в списку.
4. Використовуй плагіни як коробки. Домен — скажімо, відеопродакшн — стає одним плагіном зі своїми агентами й скілами разом, і вмикається там, де він потрібен.
5. Називай агентів за задачами, а не за посадами. researcher, reviewer, explorer — або роутер, що переходить в іншу папку проєкту з власними інструкціями. Інша папка — це справжня межа контексту. «CTO» — ні.
6. З'єднуй їх як оркестратор → воркери → рев'юер, зі станом у файлах. Один автор. Воркери не запускають воркерів.
7. Бери команду лише тоді, коли агентам треба сперечатися — три конкурентні теорії про аварію, а не розробка фічі.

І ще одне, запозичене з документації: якщо правило має виконуватися щоразу, йому взагалі не місце в скілі. Скіл — це прохання. Хук — це примус.

Справжній урок

Я хотів з'ясувати, кому має належати який скіл. А дослідження раз у раз давало відповідь на інше питання: де рветься контекст?

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

Будуй менше агентів. Пиши кращі описи. Тримай стан там, де його може прочитати будь-хто. І нехай перо тримає одна рука.