Что нужно, чтобы создать первый Agent Skill?
Выберите одну повторяемую задачу, создайте отдельную папку и положите в неё SKILL.md с полями name и description, рабочими шагами, ограничениями и критериями готового результата. Скрипты, шаблоны и большие справочники добавляйте только при реальной необходимости.
Agent Skill — не длинный универсальный промпт. Это небольшой переносимый пакет для конкретной работы: например, проверить текст по редакционному стандарту или подготовить отчёт по заданной структуре. Чем уже первый сценарий, тем проще понять, сработал ли навык и помог ли он агенту.
Если сначала нужно разобраться с термином, прочитайте что такое Agent Skills. Здесь мы сразу переходим к созданию.
Как выбрать задачу для первого навыка?
Берите работу, которая повторяется, имеет понятный вход и наблюдаемый результат. Не начинайте с задачи «помогать во всём проекте»: её границы невозможно надёжно проверить.
- Задача повторяется хотя бы несколько раз в месяц.
- Люди уже объясняют её похожими словами или используют чек-лист.
- Можно перечислить обязательные входные данные.
- Можно показать хороший результат и назвать типовые ошибки.
- Внешние действия можно отделить от подготовки черновика.
Как выглядит минимальная папка навыка?
Для первой версии достаточно папки с понятным именем и одного файла SKILL.md. Имя папки пишите строчными буквами через дефисы; внутренние материалы подключайте относительными ссылками.
| Элемент | Нужен сразу | Назначение |
|---|---|---|
| SKILL.md | Да | Метаданные и основной маршрут работы |
| references/ | По необходимости | Большие правила и справочники |
| scripts/ | По необходимости | Повторяемые детерминированные операции |
| assets/ | По необходимости | Шаблоны и файлы для итогового результата |
Когда основной файл становится тяжело читать, используйте отдельную схему разделения SKILL.md.
Как создать SKILL.md с нуля за один рабочий проход?
Сначала зафиксируйте одну задачу и ожидаемый результат, затем создайте папку навыка, заполните name и description, опишите маршрут и ограничения, после чего проверьте прямой, отрицательный и пограничный сценарии.
- 1. Назовите одну работу
Сформулируйте результат одним предложением и исключите соседние задачи.
- 2. Создайте папку и SKILL.md
Используйте стабильное имя строчными буквами через дефисы и добавьте YAML-frontmatter.
- 3. Опишите выбор навыка
В description укажите действие и характерные формулировки запроса, не обещая лишнего.
- 4. Запишите маршрут и границы
Добавьте входные данные, обязательные шаги, точки остановки и формат результата.
- 5. Проведите три теста
Проверьте правильное срабатывание, отказ на чужой задаче и безопасное поведение при нехватке данных.
Если вы ещё выбираете между skill, постоянной инструкцией и внешним инструментом, сначала откройте сравнение AGENTS.md, CLAUDE.md, SKILL.md и MCP.
Что написать в name и description?
name задаёт стабильное машинное имя, а description объясняет, какую работу выполняет навык и по каким формулировкам его выбирать. Не обещайте результат, которого инструкция не обеспечивает.
В базовой спецификации SKILL.md начинается с YAML-frontmatter. Поле name должно соответствовать имени папки, а description — быть конкретным и достаточно отличимым от описаний соседних навыков.
Формулы, негативные примеры и проверка конфликтов собраны в отдельной статье как написать description для SKILL.md.
Как выглядит короткий валидный SKILL.md?
Минимальный SKILL.md начинается и заканчивается YAML-разделителем, содержит name и description, а ниже — короткую инструкцию с входом, шагами и форматом результата.
| Строка | Назначение |
|---|---|
| --- | Открывает YAML-frontmatter |
| name: review-draft | Совпадает с именем папки навыка |
| description: Проверяет черновик по редакционному чек-листу. | Объясняет конкретную работу и условие выбора |
| --- | Закрывает YAML-frontmatter |
| # Проверка черновика | Начинает рабочую инструкцию |
| 1. Прочитайте текст и чек-лист. 2. Верните замечания с примерами. 3. Не редактируйте исходник без подтверждения. | Задаёт маршрут, результат и границу действия |
Как написать рабочую инструкцию?
Опишите входы, обязательный порядок действий, условия ветвления, проверки, формат результата и ситуации, когда агент должен остановиться. Пишите командами, а не общими пожеланиями.
- 1. Зафиксируйте вход
Перечислите, что нужно получить до начала: файл, цель, аудиторию, ограничения или пример.
- 2. Задайте маршрут
Разделите работу на короткие шаги и укажите, что делать при недостающих данных.
- 3. Поставьте границы
Отдельно отметьте запреты, внешние действия и точки подтверждения человека.
- 4. Опишите результат
Назовите формат ответа и проверяемые признаки готовности.
Какими тремя запросами проверить первый skill?
Используйте прямой запрос, близкий отрицательный запрос и пограничный сценарий с неполными данными. Так вы проверите не только выполнение, но и правильность выбора навыка.
| Сценарий | Что должно произойти |
|---|---|
| Прямой | Навык выбирается и проходит весь маршрут |
| Отрицательный | Похожая, но чужая задача не запускает навык |
| Пограничный | Агент запрашивает критичные данные или безопасно останавливается |
Для оценки пользы после первых запусков используйте методику проверки эффективности Agent Skill.
Какие ошибки чаще всего портят первый навык?
- Слишком широкое назначение и несколько несвязанных работ в одном пакете.
- Description повторяет название, но не объясняет условия выбора.
- Инструкция описывает тему, а не последовательность действий.
- Нет критерия готового результата и поведения при ошибке.
- Сразу добавлены зависимости и скрипты, хотя задачу решает инструкция.
Когда первая версия готова к использованию?
Первая версия готова, когда структура валидна, прямой сценарий воспроизводится, чужая задача не активирует навык, а ограничения и результат понятны другому человеку без устных пояснений.
Сохраните папку в системе контроля версий и зафиксируйте три тестовых запроса рядом с проектом. После каждого реального сбоя добавляйте регрессионный сценарий. В команде назначьте владельца, который принимает изменения и следит за актуальностью.
Порядок репозитория, ревью и релизов описан в материале как управлять Agent Skills в команде.