Как создать навык для ИИ агентов: руководство по формату SKILL.md

Использование готовых навыков — хороший старт. Но кастомный навык под ваш проект, стандарты команды и рабочий процесс дает более релевантный результат, чем универсальное решение.

Это руководство описывает создание навыка с нуля по официальному формату документации Anthropic: от написания правил до тестирования и публикации.

Структура навыка по формату SKILL.md

Навык — это папка с файлом SKILL.md в качестве точки входа. Файл содержит YAML-фронтматтер и markdown-инструкции:

my-skill/
├── SKILL.md           # Основные инструкции (обязательно)
├── template.md        # Шаблон для заполнения (опционально)
├── examples/
│   └── sample.md      # Пример вывода (опционально)
└── scripts/
    └── validate.sh    # Скрипт для выполнения (опционально)

Структура SKILL.md:

---
name: api-conventions
description: API design patterns for this codebase. Use when writing or reviewing API endpoints.
---

When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation

Поле name становится слэш-командой /api-conventions. Поле description критично — по нему Claude определяет, когда загружать навык автоматически.

Шаг 1. Определите область навыка

Перед написанием правил решите, что охватывает навык — и что не охватывает.

Узкая специализация работает лучше. Навык по «лучшим практикам TypeScript» эффективнее, чем «все стандарты кодирования». Навык по «паттернам тестирования Vitest» лучше, чем «тестирование вообще».

Примеры удачной области:

• Typography and color tokens for a specific design system
• REST API error handling conventions
• React component structure and naming patterns
• Database migration workflow for PostgreSQL

Примеры слишком широкой области:

• Everything about web development
• All best practices for JavaScript
• General coding guidelines

Шаг 2. Настройте Frontmatter

YAML-фронтматтер управляет поведением навыка. Это шапка в MD файлах, которая пишется как YAML конфигурация.

Ключевые поля:

---
name: my-skill
description: What this skill does and when to use it
disable-model-invocation: true
allowed-tools: Read, Grep, Bash(npm *)
context: fork
---

name — отображаемое имя и слэш-команда. Только lowercase, цифры и дефисы.

description — что делает навык. Claude использует это для автоматической загрузки.

disable-model-invocation — true запрещает автозагрузку. Используйте для воркфлоу с побочными эффектами типа /deploy.

allowed-tools — инструменты, которые Claude может использовать без запроса разрешения при активном навыке.

context — fork запускает навык в контексте субагента для изоляции.

user-invocable — false скрывает навык из меню /. Подходит для фоновых знаний.

Поле description требует внимания. Грамотное описание гарантирует загрузку навыка когда нужно — и игнорирование когда нет.

Шаг 3. Пишите конкретные правила

На этом этапе большинство авторов допускают ошибки. Эффективные правила имеют несколько характеристик:

Конкретность. Сравните:

• Плохо: «Используйте хорошие соглашения по именованию»
• Хорошо: «Используйте camelCase для переменных и функций, PascalCase для компонентов и типов, UPPERSNAKECASE для констант и переменных окружения»

Проверяемость. Вы должны иметь возможность проверить вывод агента на соответствие правилу. «Код должен быть читаемым» — не проверяется. «Функции не должны превышать 30 строк» — проверяется.

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

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

- Always use `const` for variable declarations unless reassignment is required
  (even `let` signals to reviewers that the value changes, so avoid it when the
  value is stable)

Шаг 4. Добавьте примеры кода

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

Включите примеры для наиболее распространенных паттернов в вашей области. Обычно достаточно трех-пяти хорошо подобранных примеров.

Шаг 5. Составьте списки «делай» и «не делай»

Явные ограничители предотвращают конкретные ошибки:

## Do
- Use semantic HTML elements (nav, main, article, section)
- Include aria-labels on interactive elements without visible text
- Destructure props in the function signature

## Don't
- Don't use divs for navigation or main content areas
- Don't use inline styles — use Tailwind classes instead
- Don't import from barrel files (index.ts re-exports)
- Don't nest ternary expressions

AI-агенты склонны к типовым ошибкам — чрезмерное использование div, инлайн-стили для быстрых исправлений, генерация текста-заполнителя. Явные запреты ловят эти паттерны.

Шаг 6. Добавьте вспомогательные файлы

Официальная документация рекомендует держать SKILL.md до 500 строк. Для длинных навыков переместите подробный материал в отдельные файлы:

my-skill/
├── SKILL.md (обязательно - обзор и навигация)
├── reference.md (подробные API-документы - загружаются по необходимости)
├── examples.md (примеры использования - загружаются по необходимости)
└── scripts/
    └── helper.py (утилитный скрипт - выполняется, не загружается)

Ссылайтесь на вспомогательные файлы из SKILL.md:

## Additional resources
- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)

Шаг 7. Тестируйте на разных агентах

Навык, который работает в Claude Code, может иначе вести себя в Cursor или Codex CLI. Для каждого агента выполните одинаковый тест:

1. Начните сессию только с вашим загруженным навыком
2. Дайте агенту представительную задачу
3. Проверьте вывод на соответствие каждому правилу навыка
4. Отметьте, какие правила соблюдены, а какие проигнорированы

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

Где опубликовать навык

Когда навык стабильно работает, поделитесь им с сообществом:

skills.sh — каталог навыков агентов индексирует навыки из репозиториев GitHub. Создайте публичный репозиторий с правильным SKILL.md по стандарту Agent Skills, и он станет доступен для установки через npx skills add your-name/your-skill.

awesome-claude-skills — форкните репозиторий и отправьте pull request по правилам contributing. Репозиторий популярен, поэтому навык получит видимость.

awesome-design-skills — кураторская коллекция навыков для дизайн-задач. Если навык охватывает UI-паттерны, дизайн-системы, типографику, цветовые токены или визуальные соглашения, разместите его здесь.

Публикуете вы навык или храните для себя, процесс создания углубляет понимание ваших собственных стандартов. Записывая неявные правила, вы вынуждены задуматься, почему следуете им — эта ясность полезна даже без AI-агента.