Ловушка оргструктуры: как организовать 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. Ящик с инструментами — плагин как единица

Плагин упаковывает агентов, скиллы, хуки и MCP-серверы в один устанавливаемый пакет. wshobson/agents раскладывает около двухсот агентов по девяноста четырём плагинам, в среднем по пять-шесть компонентов в каждом, под девизом ставь только то, что нужно. Официальные плагины Anthropic тоже маленькие — от одного до девяти агентов.

Лучший first-party пример скоупинга — security-плагин от 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 не поставляет ни одного файла агента; «Джон, продакт-менеджер» — это скилл, который основной агент надевает, как шляпу, продолжая видеть весь разговор.

6. Рой — агенты, которые общаются друг с другом

На дальнем краю: много агентов, работающих одновременно, переписывающихся друг с другом и разбирающих задачи из общего списка. В Claude Code для этого есть экспериментальный режим agent teams; репозитории вроде ruflo (бывший claude-flow) строят «ульи» с королевой-координатором и общей памятью.

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

Один инженер использовал команду агентов для расследования продакшн-инцидента: 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. Группируй семейства за роутерами. Девять шагов «ежедневного ревью» превращаются в один скилл с девятью reference-файлами.
3. Опасные скиллы — только для ручного вызова. Всё, что тратит деньги или отправляет сообщения, получает disable-model-invocation: true. Заодно освобождается место в списке.
4. Используй плагины как коробки. Домен — скажем, видеопродакшн — становится одним плагином, где агенты и скиллы лежат вместе, и включается там, где нужен.
5. Называй агентов по задачам, а не по должностям. researcher, reviewer, explorer — или роутер, который заходит в другую папку проекта со своими инструкциями. Другая папка — это настоящая граница контекста. «CTO» — нет.
6. Соединяй их как оркестратор → воркеры → ревьюер, с состоянием в файлах. Один пишущий. Воркеры не запускают воркеров.
7. Бери команду, только когда агентам нужно спорить — три конкурирующие теории об аварии, а не разработка фичи.

И ещё одно, позаимствованное из документации: если правило должно выполняться каждый раз, ему вообще не место в скилле. Скилл — это просьба. Хук — это принуждение.

Настоящий урок

Я хотел выяснить, кому должен принадлежать какой скилл. А исследование раз за разом подсовывало другой вопрос: где рвётся контекст?

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

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