Полное руководство по Agent Skills для AI Agent

По официальной спецификации Agent Skills поле description может содержать до 1 024 символов, а основной файл SKILL.md рекомендуется удерживать менее чем в 500 строках. Это показывает главный принцип: Skill не должен быть огромным системным промптом. Его задача — объявить, когда нужна конкретная способность, загрузить устойчивые инструкции только в подходящий момент и передать внешние действия контролируемым инструментам. (спецификация Agent Skills)

Рекомендация на неделю 17 августа 2026 года: сначала создайте один минимальный Skill для часто повторяемого процесса, проверьте его на положительных и отрицательных примерах, затем добавляйте references/ и scripts/. Не начинайте с большой библиотеки: без проверки триггеров и прав доступа десятки Skill только усложнят поведение AI Agent.

Эта статья предназначена для трёх групп:

разработчиков, которые впервые открывают SKILL.md и хотят понять базовую модель;
пользователей Claude Code, которым нужно переиспользовать командные стандарты и процедуры;
технических руководителей, создающих внутренний каталог Skill с версиями, тестами и правилами безопасности.

Последнее обновление: 17 августа 2026 года. Данные сверены со спецификацией Agent Skills, публичным репозиторием примеров Skill, документацией Claude Code и официальными материалами MCP.

Сначала отделите Skill от Prompt, знаний и инструментов

Главная ошибка при внедрении Agent Skills — считать Skill просто сохранённым Prompt. Prompt обычно задаёт инструкции для одного диалога или конкретного запуска. Skill является каталогом с описанием, правилами выполнения, дополнительными материалами и, при необходимости, исполняемыми файлами.

Разница важна по четырём причинам.

Контекст не должен постоянно разрастаться. Если все правила ревью, деплоя, оформления документов и работы с базой данных постоянно находятся в системном промпте, модель получает длинный набор указаний даже тогда, когда задача относится только к одному процессу.
Нужна выборочная загрузка. Сначала агент видит метаданные Skill, затем читает полный SKILL.md после решения об активации, а подробные ссылки и ресурсы загружает по необходимости. Такая прогрессивная схема описана в официальной спецификации.
Правила должны иметь владельца. Обычный Prompt часто живёт в личной заметке или настройке проекта. Skill можно хранить в репозитории, проверять изменениями и назначать ответственному.
Инструкции не равны полномочиям. Текст Skill может описывать команду, но не выдаёт агенту доступ к файловой системе, терминалу, сети или внешней системе. Реальные права определяются клиентом, политикой разрешений и подключёнными инструментами.

Agent Skills и Prompt — в чём разница?

Prompt — это текстовая инструкция, которую можно вставить в запрос. Skill — структурированный пакет, который помогает агенту обнаружить подходящую процедуру, загрузить её при необходимости и использовать связанные материалы в едином контексте. Поэтому Prompt удобен для краткой настройки поведения, а Skill — для повторяемого процесса с версией, тестами и обслуживанием.

Agent Skills и база знаний — это одно и то же?

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

Соберите минимальную структуру Skill без лишних файлов

Базовый Skill представляет собой каталог, в котором обязательным является файл SKILL.md; каталоги scripts/, references/ и assets/ добавляются только при реальной необходимости. (описание структуры Agent Skills)

Пример структуры:

code-review/
├── SKILL.md
├── references/
│   ├── review-policy.md
│   └── security-checks.md
├── scripts/
│   └── run-static-checks.sh
└── assets/
    └── review-template.md

Назначение компонентов различается:

Имя каталога и поле name — стабильный идентификатор Skill. По спецификации имя должно состоять из строчных букв, цифр и дефисов, а также совпадать с именем родительского каталога.
description — краткое описание назначения и условий применения. Это не рекламная фраза, а основной сигнал для выбора Skill.
SKILL.md — инструкции, порядок выполнения, критерии результата, примеры входных данных и обработка исключений.
references/ — подробные документы, которые не нужно загружать при каждом запуске: стандарты, справочники, соглашения и расширенные примеры.
scripts/ — повторяемый код, который агент может запустить через доступный инструмент, если конкретная реализация это поддерживает.
assets/ — шаблоны, схемы, изображения, заготовки конфигураций и другие статические материалы.

Минимальный SKILL.md может выглядеть так:

---
name: secure-code-review
description: Проверяет изменения в Python-сервисах на типовые ошибки безопасности,
утечки секретов и нарушения внутренней политики. Используйте при ревью
pull request, изменениях аутентификации, авторизации или обработки пользовательского ввода.
---

# Проверка кода

1. Определите изменённые файлы и область риска.
2. Проверьте входные данные, права доступа и обработку ошибок.
3. Запустите доступные статические проверки.
4. Сопоставьте результат с references/security-checks.md.
5. Верните список находок с уровнем риска и способом проверки исправления.

Если данных недостаточно, остановите автоматическое исправление
и запросите конкретный контекст.

Для первого прототипа этого достаточно. Сначала проверяется, способен ли AI Agent правильно выбрать Skill и пройти процедуру. Только после этого стоит переносить длинные материалы в references/, добавлять шаблоны и автоматические проверки.

Что должно быть в SKILL.md?

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

Не следует превращать SKILL.md в энциклопедию. Если правило требуется только для одного редкого случая, его можно сохранить в references/ и указать в основном файле, в каком сценарии этот материал нужно прочитать. Если же без правила агент не может выполнить базовый процесс, его следует оставить в SKILL.md.

Настройте описание так, чтобы Skill не срабатывал случайно

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

Слабый вариант:

description: Помогает работать с кодом и улучшает проекты.

Такое описание пересекается с десятками других Skill. Более точный вариант:

description: Проверяет изменения в Python-сервисах на ошибки авторизации,
небезопасную обработку пользовательского ввода и случайные секреты.
Используйте при ревью pull request, изменениях middleware аутентификации
или подготовке релиза, но не для общего форматирования кода.

Вторая версия содержит:

конкретный объект работы;
типы задач, которые должны запускать Skill;
признаки запроса;
границу, за которой Skill использовать не следует.

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

Проверьте положительные и отрицательные сценарии

Для каждого Skill следует заранее подготовить две группы тестов:

положительные: «проверь новый обработчик платежей», «сравни изменение с политикой авторизации», «подготовь ревью перед релизом»;
отрицательные: «переименуй переменную», «объясни синтаксис цикла», «найди файл конфигурации без проведения ревью».

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

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

Разделите устойчивые правила, динамические знания и действия

Проблема «загрузить всё в Skill» возникает, когда разработчик смешивает три разных слоя.

Устойчивые правила включают порядок действий, обязательные проверки, формат отчёта, критерии остановки и условия эскалации. Их место — в SKILL.md.

Динамические знания включают текущую версию API, список разрешённых сервисов, актуальные идентификаторы, внутренние контакты, изменяющиеся требования и оперативные справочники. Их лучше хранить в обновляемом источнике, а в Skill оставить ссылку и правило проверки актуальности.

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

Именно здесь проходит граница между Skill и MCP. MCP стандартизирует подключение AI-приложений к внешним источникам данных и инструментам, тогда как Skill описывает, как использовать процедуру и когда обращаться к нужному инструменту. (официальное введение в MCP)

Как Agent Skills и MCP работают вместе?

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

Например, Skill для анализа инцидента может:

прочитать локальные инструкции из references/;
запросить логи через MCP-инструмент;
сопоставить события с правилами;
сформировать отчёт;
потребовать отдельного подтверждения перед изменением конфигурации.

Такое разделение уменьшает риск, что текстовая инструкция будет ошибочно воспринята как самостоятельная возможность выполнять операции. Если MCP-инструмент возвращает актуальные данные, Skill не должен дублировать весь источник внутри собственного каталога: достаточно определить способ проверки, формат результата и реакцию на неполные или противоречивые сведения.

Добавляйте скрипты только вместе с ограничениями

Может ли Agent Skill вызывать скрипты?

Да, каталог scripts/ может содержать исполняемый код, а SKILL.md — описывать, когда и как его запускать. Официальные материалы допускают использование Bash, Python и JavaScript, однако фактическая поддержка зависит от конкретного Agent-клиента. Поэтому совместимость нельзя автоматически переносить с одного продукта на другой. (официальные рекомендации по скриптам)

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

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

Безопасный скрипт должен принимать явные аргументы, не выполнять команды из непроверенного пользовательского ввода, не отправлять файлы в сеть без отдельного основания и возвращать понятное сообщение об ошибке. В SKILL.md полезно указывать зависимости, доступные флаги и пример запуска.

Для Claude Code дополнительно следует учитывать разрешения инструментов и режимы подтверждения: командная строка поддерживает списки разрешённых и запрещённых инструментов, ограничение числа ходов и различные режимы разрешений. (документация Claude Code по работе с CLI)

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

Проведите установку через проверяемый контур

Ниже приведён порядок, который подходит для первого внутреннего Skill и для оценки стороннего пакета.

Шаг 1. Опишите одну проверяемую задачу

Не создавайте Skill «для разработки вообще». Выберите процесс с понятным входом и результатом: ревью миграции, подготовка релизной заметки, проверка конфигурации CI/CD или анализ логов.

Шаг 2. Создайте минимальный каталог

Добавьте только каталог и SKILL.md. Проверьте имя, YAML-заголовок и совпадение имени каталога с полем name.

Шаг 3. Сформулируйте условия активации

В description укажите действие, объект и признаки запроса. Добавьте отрицательную границу, если Skill легко путается с соседним процессом.

Шаг 4. Запишите процесс от входа к результату

Каждый этап должен объяснять, что проверить, какой результат получить и когда остановиться. Фразы вроде «сделайте качественно» не являются критериями приёмки.

Шаг 5. Добавьте тестовые запросы

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

Шаг 6. Вынесите объёмные материалы

Если основной файл становится длинным, переносите подробные справочники в references/. Ссылки из SKILL.md должны оставаться простыми и относительными; не следует строить глубокие цепочки вложенных ссылок.

Шаг 7. Подключите скрипты после ручной проверки

Сначала подтвердите, что агент правильно формулирует намерение и выбирает нужную процедуру. Затем добавьте скрипт, ограничьте его аргументы и проверьте работу в изолированной среде.

Шаг 8. Зафиксируйте результат и откат

Сохраните версию Skill в репозитории, добавьте запись об изменениях и определите способ возврата к предыдущей версии. Для командной эксплуатации отсутствие отката является таким же риском, как отсутствие тестов.

При проверке удалённого окружения следует отдельно фиксировать версию клиента, доступные инструменты, расположение каталогов Skill и правила хранения логов. Если используется временная инфраструктура, требования к удалённому Mac и сетевому доступу лучше определить до импорта сторонних файлов. Сведения о возможностях Vuncloud можно сопоставить с задачами команды в описании сервиса Vuncloud. При необходимости отдельной macOS-среды конфигурацию рабочего узла и условия подключения следует оценивать независимо от логики Skill.

Используйте проверочный список перед публикацией

[ ] Задача Skill имеет один измеримый результат.
[ ] В SKILL.md присутствуют корректные name и description.
[ ] Описание объясняет, что делает Skill и когда его нужно использовать.
[ ] Для соседних Skill подготовлены отрицательные тесты.
[ ] Инструкции разделены на вход, действия, проверки и результат.
[ ] Динамические сведения не зашиты в текст без даты или источника обновления.
[ ] Каждый файл из references/ действительно нужен при выполнении отдельных сценариев.
[ ] Скрипты не используют неограниченный ввод командной строки.
[ ] Проверены сетевые обращения, права записи и переменные окружения.
[ ] Указаны зависимости и ожидаемые коды ошибок.
[ ] Для побочных действий предусмотрено подтверждение пользователя.
[ ] Определены владелец, версия, дата изменения и процедура удаления.
[ ] Skill протестирован в том Agent-клиенте, где он будет использоваться.
[ ] Указано, какие функции являются специфичными для конкретной реализации.

Постройте командную библиотеку, а не коллекцию папок

Внутренний каталог Agent Skills начинает приносить пользу не тогда, когда в нём много элементов, а когда каждый элемент имеет владельца и понятную область применения. Для этого нужны простые правила сопровождения:

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

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

Командной библиотеке также нужен процесс изменения. Перед публикацией новой версии ответственный должен указать, что изменилось в логике активации, какие файлы добавлены, какие тесты пройдены и совместима ли версия с прежним клиентом. Если обновление меняет права скрипта или перечень MCP-инструментов, это следует считать не обычной правкой текста, а изменением уровня риска.

Для удалённой разработки особенно важно разделить сам Skill, среду исполнения и канал подключения. Подготовка каталога не заменяет изолированную рабочую среду, контроль SSH-доступа, ограничение файловых путей и журналирование команд. Временная удалённая Mac-среда может быть удобнее локальной машины, когда нужно быстро проверить несколько вариантов конфигурации без изменения основного компьютера; при этом следует заранее оценить длительность задачи, требования к интерфейсам и политику хранения данных.

Не переносите совместимость одного клиента на весь рынок

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

В документации Claude Code также описываются собственные настройки инструментов, разрешений и интеграций. Это не означает, что те же параметры будут распознаны другим AI Agent. В каждом проекте нужно явно зафиксировать:

какой клиент обнаруживает Skill;
где должен находиться каталог;
какие поля frontmatter поддерживаются;
может ли агент запускать скрипты;
какие инструменты доступны;
как запрашивается подтверждение;
где хранятся логи и результаты тестов.

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

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

Для временного тестирования Skill аренда удалённой Mac-среды может дать более предсказуемый контур, чем перестройка основного компьютера, но для постоянной тяжёлой нагрузки, физического доступа к устройствам или строгого хранения данных на собственной инфраструктуре лучше рассматривать собственное оборудование и внутренний контур безопасности. Перед выбором среды следует проверить, нужна ли команде именно macOS, будут ли использоваться локальные инструменты и допускает ли политика проекта передачу тестовых данных на удалённый узел.

На следующем шаге разумно не импортировать большой пакет, а сначала проверить один Skill в изолированной среде, пройти внутренний чек-лист безопасной установки и приёмки и только после этого подключать скрипты или MCP-инструменты. Такой порядок позволяет увидеть реальные границы совместимости до того, как Skill станет частью командного процесса.