Один набор скиллов на двух агентов: как не писать одно и то же дважды

У меня 267 скиллов в папке Claude Code и 32 в общей папке, которую читает ещё и Codex. Вторая цифра важнее первой.

Разберу, почему формат скиллов одинаковый у Claude Code и Codex, где именно лежат файлы, какие лимиты на них накладывает документация Anthropic и почему двести шестьдесят семь скиллов — плохая идея.

Скилл — это папка с одним файлом

Формат простой до неприличия. Папка, внутри SKILL.md, в нём YAML-фронтматтер и обычный markdown.

---
name: seo-audit
description: Проверяет страницу по чек-листу технического SEO. Использовать,
  когда пользователь просит аудит страницы, разбор мета-тегов или проверку
  скорости загрузки.
---

## Что делать
1. Собрать заголовки, мета-описание, canonical...

Два обязательных поля, и у обоих есть жёсткие лимиты. Поле name — до 64 символов, только строчные буквы, цифры и дефисы. Поле description — до 1024 символов, и в нём должно быть написано и что скилл делает, и когда его применять. Второе пропускают чаще всего, а потом удивляются, что скилл не срабатывает.

Тело файла Anthropic просит держать меньше 500 строк. Требование идёт из механики загрузки, а не из вкусовщины по оформлению.

Три уровня загрузки, из-за которых всё и работает

Механика называется progressive disclosure, и понимать её стоит, потому что она объясняет расход контекста.

Первый уровень — метаданные. Имя и описание каждого скилла висят в контексте всегда, примерно по сто токенов на штуку. Модель по ним решает, что подтянуть.

Второй уровень — тело SKILL.md. Грузится, только когда скилл сработал. Рекомендация документации — уложиться в 5000 токенов.

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

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

У Claude Code для таких случаев есть команда /skill-doctor: она показывает скиллы, которые не срабатывают.

Где лежат файлы

Claude Code читает скиллы из четырёх мест: ~/.claude/skills для личных, .claude/skills в проекте, из подключённых плагинов и из папки, переданной флагом --add-dir.

Codex читает из двух: ~/.agents/skills глобально и .agents/skills внутри репозитория.

Формат SKILL.md при этом один и тот же. Файл, написанный для одного агента, читается вторым, вопрос только в том, где он лежит. Что при этом теряется — ниже.

Дальше решение очевидное: держать общие скиллы в ~/.agents/skills и симлинкнуть их в ~/.claude/skills. Одна команда:

ln -s ~/.agents/skills/carousel ~/.claude/skills/carousel

Теперь правка в одном месте меняет поведение обоих агентов. У меня так живут 32 скилла: вёрстка, анимации, дизайн-система, работа с видео.

Что не переносится

Честная часть. Фронтматтер у Claude Code богаче: там есть allowed-tools, model, effort, context: fork, background, argument-hint и ещё несколько полей. Codex эти поля просто не знает.

Скилл от лишних полей не ломается, но и не получает того поведения, которое они дают. Если скилл написан вокруг конкретной модели или вокруг запуска в фоне, кросс-агентным он не будет.

Ещё одна граница проходит по средам. Скиллы не синхронизируются между поверхностями: то, что стоит в терминале, не появится само в приложении или в вебе. И часть встроенных документных скиллов Anthropic — pptx, xlsx, docx — в Claude Code недоступна, они живут только в API.

С чего начать, если скиллов пока ноль

Не с написания скилла. Anthropic в разделе про лучшие практики советует сначала собрать сценарии проверки, минимум три, и только потом писать документацию. Логика та же, что в тестах: без критерия «сработало» ты будешь править формулировки по ощущениям.

Практический маршрут на сегодня выглядит так. Возьми задачу, которую объясняешь агенту третий раз подряд. Запиши в SKILL.md то, что обычно диктуешь голосом, в описание вынеси условие срабатывания. Положи в ~/.agents/skills, симлинкни в ~/.claude/skills, проверь на трёх разных формулировках запроса.

Один скилл, который срабатывает вовремя, полезнее сорока, которые висят мёртвым грузом в контексте. Я шёл в обратном порядке: сначала набрал 267 штук, потом стал разбираться, почему контекст кончается раньше задачи.

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