Руководство: как настроить самообучающиеся навыки (AI Skills) в Claude Code

Руководство: как настроить самообучающиеся навыки (AI Skills) в Claude Code

Разработка с помощью искусственного интеллекта переходит от простых промптов в сторону модульных систем. Компания Anthropic представила концепцию AI Skills (навыков ИИ) для своего терминального помощника Claude Code. Навык — это не просто набор инструкций, а обособленный модуль, который объединяет правила поведения, примеры идеального результата, контур тестирования и долгосрочную память о прошлых ошибках.

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

Подготовка и архитектура навыка

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

Рекомендуемая структура папки навыка:

my-custom-skill/
  SKILL.md             # Основной файл инструкций и правил вызова
  examples.md          # База примеров идеального выполнения
  evals.md             # Критерии оценки и тесты (эвалы)
  memory.md            # Журнал памяти об ошибках и исправлениях

Обратите внимание на оговорку о конфиденциальности от Anthropic: функция Agent Skills не попадает под действие политики нулевого хранения данных (ZDR — Zero Data Retention). Данные сессий сохраняются на серверах провайдера. Поэтому никогда не добавляйте в файлы навыка конфиденциальные данные клиентов, пароли или секретные API-ключи.

Шаг 1: Создание основного файла SKILL.md и метаданных

Основной файл навыка должен называться строго SKILL.md. Он должен располагаться в корне папки навыка.

1. Служебный блок метаданных (YAML frontmatter): В самом начале файла SKILL.md необходимо разместить служебный блок настроек, выделенный тремя дефисами. Правила Anthropic Extend Claude with skills накладывают на этот блок жесткие ограничения:
   • Поле name является обязательным, его длина не должна превышать 64 символов. Допускаются только строчные латинские буквы, цифры и дефисы. Запрещено использовать XML-теги и зарезервированные слова anthropic и claude.
   • Поле description является обязательным, его максимальный объём — 1024 символа. Описание должно быть написано в третьем лице и чётко объяснять, когда именно Claude должен активировать этот навык.
   
   Пример заголовка файла SKILL.md:

   ---
   name: copy-editor
   description: Edits draft blog posts and marketing copy to remove AI slop, reduce filler words, and match the style guide. Use when asked to polish Russian text.
   ---
   

2. Содержимое файла: Опишите подробную пошаговую инструкцию выполнения задачи. Укажите входные данные, ожидаемый формат результата и список запрещённых действий. Официальная рекомендация от Anthropic советует держать объём файла SKILL.md в пределах 500 строк. Все крупные сопутствующие материалы (описания API, руководства по стилю) выносите в отдельные файлы, чтобы не перегружать контекстное окно ИИ при каждом вызове.

Шаг 2: Формирование базы примеров (examples.md)

Примеры качественного выполнения задачи работают эффективнее абстрактных правил. Создайте файл examples.md (или разделите его на несколько файлов, например example-before-after.md) и разместите там лучшие образцы работы.

• Укажите исходный текст (или код) и покажите идеальный результат после обработки.
• Объясните в комментариях, почему именно этот результат считается эталонным.
• Не перегружайте файл примерами — достаточно 3–5 качественных разборов разного уровня сложности. Claude обратится к этому файлу только при необходимости, экономя ваши токены.

Шаг 3: Настройка контура тестирования (evals.md)

Для автоматического контроля качества работы навыка создаётся файл evals.md. В терминологии ИИ-разработки тесты для оценки моделей называют эвалами (evals).

1. Бинарный подход к оценке: При оценке качества текстового или логического вывода используйте строго бинарный подход: «Пройдено» (Pass) или «Не пройдено» (Fail). Языковые модели плохо различают соседние субъективные оценки.
2. Типы тестов (Graders): Согласно руководству Anthropic Demystifying evals for AI agents, тесты делятся на три категории:
   • Кодовые тесты (Code-based): проверка регулярными выражениями, статический анализ линтером, запуск юнит-тестов. Они дешёвые, объективные и быстрые, идеально подходят для проверки жестких рамок.
   • Модельные тесты (Model-based): оценка качества выполнения другой, независимой языковой моделью на основе заданной рубрики. Этот способ дороже и медленнее, но позволяет проверять сложные стилистические критерии.
   • Человеческая оценка (Human-based): ручная проверка экспертом. Самый дорогой и медленный, но самый надёжный способ калибровки автоматических тестов.
3. Изоляция оценщика: Важнейшее правило: модель, которая выполняет задачу, не должна оценивать саму себя в той же сессии. Для тестирования запускайте отдельный экземпляр Claude в чистом контексте (clean context window) — новой сессии без истории переписки. Это гарантирует беспристрастность оценки.

Пример структуры файла evals.md:

# Критерии оценки навыка copy-editor

Каждый проверенный текст должен соответствовать следующим правилам:
1. [Бинарный] Текст написан на русском языке. (Pass/Fail)
2. [Бинарный] Отсутствуют запрещённые слова-маркеры ИИ (например, «уникальный», «революционный»). (Pass/Fail)
3. [Бинарный] Вводный абзац сразу переходит к сути проблемы без пространных вступлений. (Pass/Fail)

Шаг 4: Организация долгосрочной памяти (memory.md)

Файл memory.md служит журналом работы над ошибками. Без него ИИ-ассистент будет раз за разом совершать одни и те же логические сбои при изменении контекста.

• Записывайте в файл memory.md краткие отчёты о замеченных сбоях в обратном хронологическом порядке.
• Формат записи: описание ошибки, предпринятое действие для исправления инструкции и результат повторного тестирования.
• Перед выполнением задачи Claude автоматически считывает файл памяти, что позволяет ему корректировать свои действия с учётом накопленного опыта.

Пример записи в memory.md:

- **2026-06-10**: Модель проигнорировала ограничение на длину заголовка в примере №3.
  *Исправление*: Добавлено жёсткое правило проверки длины регулярным выражением в блок `evals.md`. Повторный тест пройден успешно.

Шаг 5: Тестирование и запуск самообучающегося цикла (Observe-Refine-Test)

После подготовки всех файлов запустите цикл непрерывного улучшения навыка (observe-refine-test loop), описанный в рекомендациях Anthropic Skill authoring best practices:

1. Создайте базовый тест: запустите задачу без использования созданного навыка и сохраните результат.
2. Активируйте навык: запустите выполнение той же задачи через Claude Code с подключённым навыком. Убедитесь, что модель распознала описание в SKILL.md и активировала нужный модуль.
3. Оцените результат: запустите тесты из evals.md во второй сессии ИИ.
4. Внесите правки: если тест возвращает статус Fail, изучите лог работы ИИ, найдите слабое место, обновите инструкции в SKILL.md или дополните примеры. Зафиксируйте опыт в memory.md.
5. Проверьте регрессию: периодически запускайте проверку на старых, ранее успешно пройденных задачах, чтобы убедиться, что новые изменения в правилах не сломали старую логику.

Сводный чеклист по созданию навыка

• Файл называется строго SKILL.md и лежит в корне папки.
• Блок метаданных YAML оформлен корректно, название name содержит менее 64 символов в нижнем регистре, без тегов.
• Описание description содержит условия запуска ("Use when...") и написано в третьем лице.
• В правилах отсутствуют завязки на текущую дату или временные события, способные устареть.
• База примеров вынесена в отдельные файлы и не раздувает размер основного файла.
• Контур оценки evals.md использует бинарные критерии и запускается в изолированном контексте.
• Все зависимости от сторонних библиотек или скриптов задокументированы, в файле правил приведены команды для их установки.
• Внутри файлов нет конфиденциальных ключей доступа, токенов или личных данных пользователей.

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