Навыки агента — это код: определите их объем, раскройте информацию, напишите скрипты и протестируйте их.

Файл SKILL.md похож на документацию, однако его редактирование влияет на поведение агента. Это делает его более похожим на код, чем на прозу, и его следует проектировать, определять объём задач и тестировать соответственно.

Навыки — это не документация

Обычная первая реакция при создании навыка для LLM — писать больше: объяснять архитектуру, добавлять примеры, описывать крайние случаи и предоставлять контекст, чтобы модель поняла, почему всё работает именно так. Обычно эта реакция ошибочна.

Навык — это не руководство для разработчика, изучающего вашу систему. Это контекст, вводимый в агента, который занят выполнением задачи. Именно это различие определяет всю структуру проектирования. Полезный вопрос заключается не в том, как объяснить систему модели, а в том, что нужно знать агенту, чтобы правильно принять следующее решение.

С этой точки зрения несколько вариантов становятся проще:

• формулируйте инструкции в виде процедур
• указывайте конкретные условия активации
• постепенно загружайте информацию
• переносите детерминистические операции в скрипты
• тестируйте навыки на реальных задачах

Только процедурные знания

Современные кодинг-агенты уже справляются с удивительно большим объемом задач, связанных с общей инженерией программного обеспечения. Они знают Git и npm, понимают Angular, React, TypeScript, SQL, REST API, фреймворки тестирования и настройку CI. Навык, который лишь повторяет это, практически ничего не добавляет:

When implementing an Angular component, use TypeScript.
Write maintainable code.
Follow Angular best practices.
Add tests.

Он уничтожает контекст, не предоставляя ничего из того, чего не хватало модели. Навыки, которые стоит иметь, включают знания, специфичные для вашей среды:

When modifying an Angular application in this repository:

1. Locate the closest project.json belonging to the affected application.
2. Check whether the project uses Vitest or Karma before generating tests.
3. For applications under apps/trading/, do not import directly from apps/shared/.
4. Run the affected project's test target rather than the workspace-wide test command.
5. Before changing a public interface in libs/order-entry/, search for consumers in
   apps/trading-terminal and apps/blotter.tp

Здесь агент узнаёт что-то, чего он не мог надёжно вывести из публичной документации Angular, а именно то, как следует выполнять работу в определённом репозитории. Именно для этого и нужны навыки.

Формат Agent Skills организует всё это в виде каталога, содержащего файл SKILL.md, а также необязательные скрипты и ресурсы. Метаданные предназначены для поиска, а полные инструкции и вспомогательные файлы загружаются только тогда, когда это необходимо. Формат файла — не главное. Главное — различие между общими возможностями модели и знаниями, которые должна предоставить ваша среда.

Контекст — это своего рода бюджет

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

Предположим, что эти навыки установлены:

angular-testing
angular-migration
jira-workflow
postgres-debugging
release-process
accessibility-review
storybook
incident-response
performance-profiling

Когда задача заключается в устранении сбоя в тесте модуля Angular, у агента нет причин знать процесс выпуска или шаги отладки PostgreSQL. Именно поэтому процесс выявления проблем имеет почти такое же значение, как и сам контент. Сравните два описания: этот случай крайне прост в реализации:

---
name: testing
description: Helps run tests in our repository.
---

Этот вариант гораздо точнее:

---
name: angular-unit-testing
description: >
  Run and debug Angular unit tests in projects using Karma or Vitest.
  Use for Angular unit-test failures and test creation.
  Do not use for Playwright E2E tests, React projects, or backend tests.
---

Второе описание делает гораздо больше, чем просто определяет суть навыка. Оно задаёт границы его применения, не позволяя нерелевантным инструкциям попадать в рабочий контекст. В докладе о проектировании навыков для агентов LLM это подчёркивается ясно: метаданные навыка — это не просто декоративные элементы. Небрежно составленные правила активации приводят к тому, что полезные инструкции попадают в неподходящие задачи, тогда как слишком узкие правила делают навык совершенно недоступным.

Поэтапное раскрытие информации лучше, чем огромный SKILL.md

Частой ошибкой является превращение файла SKILL.md в небольшой внутренний вики. Сначала там двадцать строк, затем кто-то добавляет шаги развертывания, потом инструкции по устранению ошибок, затем примеры, а потом параметры конфигурации. Через три месяца агенту приходится читать 1 500 строк, чтобы изменить всего один файл.

Структурируйте его так же, как вы структурировали бы программное обеспечение:

angular-workflow/
├── SKILL.md
├── testing.md
├── migrations.md
├── architecture.md
└── scripts/
    ├── affected-projects.ts
    └── verify-boundaries.ts

SKILL.md содержит только логику маршрутизации:

# Angular repository workflow

When modifying an Angular project:
1. Identify the affected project.
2. Read `architecture.md` when changing dependencies between projects.
3. Read `testing.md` when creating or modifying tests.
4. Read `migrations.md` when changing Angular versions or framework APIs.
5. Run `scripts/verify-boundaries.ts` after changing imports between projects.

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

Пусть скрипты обеспечивают то, что они могут обеспечить

Ещё один принцип помогает: инструкции предназначены для принятия решений, а скрипты — для выполнения детерминированных операций. Представьте себе навык, который гласит следующее:

Find all applications under apps/.
Check their Angular versions.
Ignore archived applications.
Compare their versions with the root package.json.
Report applications that are behind.

Агент может это сделать, но только путем постоянной проверки каталогов, интерпретации файлов, определения того, что считается архивированным, отслеживания состояния и, вероятно, выполнения множества вызовов инструментов. Когда операция может быть точно описана, запишите её один раз:

node scripts/check-angular-versions.mjs

Затем эта функция просто указывает, когда её запускать и что делать с результатом:

When checking Angular version consistency, run
`node scripts/check-angular-versions.mjs`.

If it reports mismatches, inspect only the projects listed in the output.

Это лучше по нескольким причинам. Скрипт можно протестировать в режиме единицы тестирования, и его поведение всегда будет одинаковым. Для его работы требуется меньше решений от модели, а также чаще меньше вызовов инструментов. Кроме того, при возникновении ошибки её можно воспроизвести, не прося LLM повторить свои рассуждения.

Всё это не означает замены агентов на скрипты. Это означает выбор правильного уровня абстракции. Используйте модель для принятия решений, например, для определения того, какие проекты могут быть затронуты архитектурными изменениями. Используйте код для реализации точных алгоритмов, например, для составления списка проектов, которые импортируют определённый пакет. Агент координирует работу обоих подходов, и такое сочетание эффективнее, чем описание всего рабочего процесса на английском языке.

Инструменты и навыки решают разные проблемы

Инструмент предоставляет агенту действие, в то время как навык учит, когда и как его использовать. Инструмент командной строки может предоставить способ вычисления затронутых проектов:

tr project affected --base main

Инструмент обеспечивает возможность. Соответствующие навыки дают организации знания:

Before modifying a shared library:
1. Run `tr project affected --base main`.
2. If either `trading-terminal` or `blotter` is affected, run their integration suites.
3. If more than five applications are affected, stop and inspect the dependency change
   before proceeding.1

CLI не понимает, почему пять затронутых приложений должны казаться подозрительными, и специалисту не обязательно знать, как работает прослеживание зависимостей. Это четкое разделение обязанностей. Тот же принцип применяется, когда функциональность предоставляется через команду оболочки, веб-API, сервер MCP или любой другой интерфейс: не закапывайте правила управления в инструментах низкого уровня, если они туда не относятся, и не пишите детерминистические алгоритмы в виде простого текста, если это не крайне необходимо.

Большее количество навыков автоматически не делает их лучше

Привлекательным подходом к разработке агентов является сбор навыков, которые кажутся полезными, их установка всеми сразу с предположением, что агент станет более функциональным. Однако данные указывают на необходимость гораздо более выборочного подхода.

SkillsBench включает 86 заданий, охватывающих 11 областей. Согласно первой версии исследования, использование тщательно отобранных навыков повысило средний процент успешного выполнения заданий на 16,2 процентных пункта, причем наблюдались значительные различия между областями. В области инженерии программного обеспечения показатель улучшился всего на 4,5 пункта, а результаты по 16 из 84 заданий ухудшились после добавления навыков. Навыки, сгенерированные самими моделями, не принесли никакого среднего улучшения.

SWE-Skills-Bench изучил 49 публичных навыков, применяемых при решении реальных задач в области инженерии программного обеспечения. У 39 из них не было никакого влияния на процент успешного выполнения заданий, а среднее улучшение составило всего 1,2 пункта. Несколько высокоспециализированных навыков, всего семь, позволили улучшить результаты на 30 пунктов. Ещё три навыка привели к ухудшению результатов на 10 пунктов, поскольку их рекомендации были ориентированы на другую версию, чем та, что использовалась в проекте.

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

When our generated API clients change, regenerate schemas before running typecheck.

У этого есть ценность. У этого она гораздо меньше:

Always think carefully before modifying APIs.

Основное правило: не создавайте навык только потому, что существует задача. Создавайте его тогда, когда агент постоянно упускает какие-то процедурные знания.

Навыки требуют тестирования

Это, возможно, самое значительное концептуальное изменение. Поскольку изменения в файле SKILL.md влияют на поведение агента, последствия схожи с изменениями в коде:

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

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

Upgrade application A from Angular 20 to Angular 21.

с такими ожиданиями:

Expected:
- correct migration command executed
- generated migration changes preserved
- application tests executed
- unrelated applications untouched

Вторая задача:

Upgrade a shared library consumed by applications A and B.

со своими собственными ожиданиями:

Expected:
- consumers discovered
- both affected applications typechecked
- dependency constraints respected

И третье:

Modify a React application in the same monorepo.

Чьим ожидаемым результатом является отсутствие активации:

Expected:
- Angular migration skill is NOT activated

Этот заключительный случай имеет такое же значение, как и любой успешный запуск, поэтому необходимо протестировать оба варианта: навык должен активироваться здесь, а не там. Инструмент под названием SkillGrade основан на этой идее. Определите задачи, неоднократно запустите агента, затем оцените каждый запуск с помощью точных проверок, шкалы оценки на основе LLM для записанной сессии или обоих методов одновременно. Этот принцип можно применять и без него. Главное — рассматривать навык как что-то, что может деградировать. Изменяйте навык, не имея возможности сказать, превосходит ли новая версия старую, и вы будете редактировать производственную логику без тестирования.

Начинайте с неудач, а не с рынка навыков

Самый простой способ создания бесполезных навыков — это задать вопрос о том, какие навыки должен иметь кодинг-агент. Вы получите список тестирования, отладки, ревью кода, документации, архитектуры, рабочих процессов Git, доступности, безопасности и ещё двадцати других тем, которые модель уже довольно хорошо понимает.

Лучшей отправной точкой является собственная история агента. Ищите повторяющиеся сбои. Возможно, агент:

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

Это признаки нехватки навыков. Цикл развития выглядит следующим образом: наблюдение за повторяющимся сбоем, выявление отсутствующих процедурных знаний, создание самого простого полезного навыка, перенос определенных шагов в скрипты, формирование типичных задач для оценки, измерение результатов, а затем сохранение, улучшение или удаление данного навыка. Улучшение ведет к его повторной переработке.

Обратите внимание на последний вариант, поскольку удаление является допустимым действием. Навык, который не влияет на поведение, не является бесполезным — он добавляет дополнительный контекст, увеличивает нагрузку на обслуживание и предоставляет ещё одну инструкцию, которая может впоследствии вступить в конфликт с чем-то другим.

Настоящей абстракцией является контролируемый контекст

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

Хорошо спроектированная среда агента больше похожа на программную систему с несколькими уровнями, чем на один огромный запрос. В ней всегда присутствуют общие знания модели и краткие глобальные инструкции. Специфические навыки для выполнения задачи, условно загружаемые ссылки, детерминистичные инструменты и контекст хранилища во время выполнения подключаются только тогда, когда это необходимо. У каждого уровня есть своя функция. Если эти обязанности смешиваются, контекст увеличивается до такой степени, что поведение агента становится трудно понятным. Если же их разделить, навыки становятся довольно простыми, что является плюсом.

Хороший навык — это не красиво сформулированный запрос. Это компактный фрагмент процедурных знаний, который применяется в подходящей ситуации, использует детерминистичные инструменты там, где это возможно, и проверяется на предмет ситуаций, которые он должен предотвратить.