Logo
Overview

Как написать свой Skill для Claude Code: гайд на примере анализа требований

November 4, 2026
8 min read
claude-code claude-skills skill-md agent-skills ii prompt-inzhiniring sistemnyj-analiz analiz-trebovanij

На прошлой неделе я третий раз за день скопировал один и тот же промпт для ревью требований. Открыл чат с Claude Code, вставил 15 строк чек-листа, дописал контекст проекта, отправил. Через час — снова. Вечером психанул и запихнул всё в SKILL.md. Написание заняло 20 минут. С тех пор ни одной копипасты.

Обзорная статья про Claude Skills для системного аналитика собрала топ-10 готовых сценариев. Здесь — пошаговый разбор, как написать свой навык с нуля. На примере, который реально экономит время: навык ревью требований.

Не надо быть программистом. Надо понимать свою рутину и уметь описать её словами.

Чем навык отличается от хорошего промпта

Промпт живёт один диалог. Навык — всегда. В этом вся разница.

Когда вы пишете промпт, вы объясняете Claude, что делать, в начале каждого чата. Дважды в день — терпимо. Пять раз — бесит. Навык описывается один раз и подгружается автоматически по триггеру — фразе в description, которая совпадает с запросом пользователя.

Сравните. Промпт: «Проверь эти требования на полноту, противоречия, NFR, критерии приёмки. Формат — таблица с колонками проблема/серьёзность/исправление.» Каждый раз руками.

Навык: пишете это в SKILL.md. Дальше пишете «отревьюй ТЗ» — Claude сам знает, что делать.

Технически навык — это файл SKILL.md в папке .claude/skills/<имя-навыка>/. Claude Code сканирует папку при старте, читает YAML-заголовок каждого навыка и держит в памяти. Когда ваш запрос семантически совпадает с description, он инжектит инструкцию в системный промпт. Без вашего участия.

Анатомия SKILL.md для ревью требований

Давайте разберу реальный файл. Не абстрактный шаблон, а тот, что у меня в проекте лежит.

---
name: review-requirements
description: >
  Ревью функциональных требований: проверка полноты,
  непротиворечивости, прослеживаемости к бизнес-целям,
  наличия нефункциональных требований и критериев приёмки.
  Формат выдачи: таблица с колонками «проблема», «серьёзность»,
  «предлагаемое исправление», «пункт ТЗ».
---

Всё, что выше ---, — YAML-frontmatter с двумя обязательными полями: name (машинное имя, lowercase, kebab-case) и description (триггер — самое важное поле).

Ниже идёт тело навыка — markdown с инструкциями. Вот как выглядит мой:

Ты — senior системный аналитик, который проводит ревью технического задания.
Твоя задача: найти пробелы, противоречия и неоднозначности до того, как
их найдёт разработчик.


## Чек-лист ревью (12 пунктов)


Обязательные проверки:
1. Все функциональные блоки описаны? Нет разделов «будет позже»?
2. Для каждого требования указан приоритет (MoSCoW)?
3. Есть хотя бы один нефункциональный блок (производительность, надёжность, безопасность)?
4. Все интеграции перечислены с протоколами и форматами?
5. Роли пользователей определены и не дублируются?
6. Для каждого экрана/интерфейса описано поведение при ошибках?
7. Критерии приёмки измеримы? Нет формулировок «работает быстро»?
8. Термины используются единообразно? Нет синонимов одного понятия?
9. Граничные случаи описаны? Пустой ввод, максимальные значения, таймауты?
10. Конфликтующие требования: проверь, не противоречат ли пункты друг другу?
11. Прослеживаемость: каждая фича связана с бизнес-целью?
12. Ограничения платформы указаны? Браузеры, ОС, версии API?


## Формат ответа


Выдай результат в виде таблицы:


| # | Проблема | Серьёзность | Предлагаемое исправление | Пункт ТЗ |
|---|----------|-------------|-------------------------|----------|


Серьёзность:
- Критичная: блокирует разработку, противоречие в логике
- Высокая: отсутствует ключевая спецификация (NFR, интеграции)
- Средняя: неоднозначность, можно трактовать по-разному
- Низкая: стиль, терминология — не влияет на разработку


После таблицы — сводка: сколько проблем каждого уровня, общая оценка ТЗ
и рекомендация: можно в разработку / требует доработки / сырое.

Пятнадцать минут писанины. Две недели экономии. Считайте сами.

Жизненный цикл навыка: от идеи до стабильной работы

Написать SKILL.md — это 30% работы. Остальные 70% — итерации после тестов. Вот как выглядит процесс целиком:

100% 
flowchart TD
  A["Определение задачи<br/>для автоматизации"] --> B["Создание папки<br/>.claude/skills/имя-навыка/"]
  B --> C["Написание SKILL.md<br/>с YAML-заголовком"]
  C --> D{"Проверка description:<br/>достаточно конкретный?"}
  D -->|"Нет"| E["Уточнить триггеры<br/>и формат ответа"]
  E --> C
  D -->|"Да"| F["Добавление ресурсов:<br/>шаблоны, таблицы, спеки"]
  F --> G["Перезапуск Claude Code"]
  G --> H["Тестирование на<br/>реальной задаче"]
  H --> I{"Результат<br/>удовлетворяет?"}
  I -->|"Нет"| J["Анализ ошибок<br/>и доработка SKILL.md"]
  J --> C
  I -->|"Да"| K["Коммит в репозиторий<br/>и использование"]
  K --> L["Итеративное улучшение<br/>по мере накопления опыта"]
  L --> H
  style A fill:#4a90d9,stroke:#2c5f8a,color:#fff
  style B fill:#7b68ee,stroke:#5a4db2,color:#fff
  style C fill:#7b68ee,stroke:#5a4db2,color:#fff
  style D fill:#f0a500,stroke:#c88400,color:#fff
  style E fill:#f0a500,stroke:#c88400,color:#fff
  style F fill:#50c878,stroke:#3a9a5c,color:#fff
  style G fill:#7b68ee,stroke:#5a4db2,color:#fff
  style H fill:#50c878,stroke:#3a9a5c,color:#fff
  style I fill:#f0a500,stroke:#c88400,color:#fff
  style J fill:#f0a500,stroke:#c88400,color:#fff
  style K fill:#4a90d9,stroke:#2c5f8a,color:#fff
  style L fill:#e0e0e0,stroke:#999,color:#333

Синие блоки — старт и финиш. Фиолетовые — создание контента. Жёлтые — точки принятия решений. Зелёные — активная работа. Серый — фоновая итерация.

Два цикла на схеме. Первый — уточнение description (самого частого источника проблем). Второй — доработка инструкции после тестирования. На практике каждый цикл проходится один-два раза, редко больше.

Ключевая точка — ромб «Результат удовлетворяет?». Если навык пропускает проблемы или генерирует шум — возвращаетесь к SKILL.md, правите чек-лист, добавляете критерии. Без этого навык остаётся сырым.

Как это работает под капотом: от запроса до отчёта

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

100% 
sequenceDiagram
  participant A as Аналитик
  participant CC as Claude Code
  participant S as Skill (SKILL.md)
  participant LLM as Claude (LLM)
  A->>CC: "Отревьюй ТЗ"
  CC->>S: Поиск навыка по description
  S->>CC: Загрузка инструкций в контекст
  CC->>LLM: Запрос + инструкции Skill
  LLM->>LLM: Проверка по чек-листу
  LLM->>CC: Отчёт с замечаниями
  CC->>A: Результат ревью
  Note over A,LLM: Полный цикл: 5-10 секунд

Весь путь занимает 5–10 секунд. Claude Code матчит запрос пользователя с description навыка, подгружает содержимое SKILL.md в системный промпт, и модель работает так, будто вы вручную вставили инструкцию в начало диалога.

Отсюда практический вывод: description должен быть конкретным. Не «помощь с требованиями» — Claude не поймёт, когда активировать. А «ревью функциональных требований: проверка полноты, непротиворечивости, прослеживаемости и критериев приёмки» — поймёт. Разница между «сработало один раз из трёх» и «срабатывает всегда».

Пишем навык: пошагово

Шаг 1. Выберите задачу

Не пытайтесь автоматизировать всё сразу. Возьмите одну повторяющуюся операцию, которую делаете минимум дважды в неделю. Ревью ТЗ, генерация User Story, проверка API-контракта, составление словаря терминов.

Признак хорошего кандидата: у вас есть мысленный (или записанный) чек-лист для этой задачи. Если вы каждый раз придумываете критерии заново — сначала формализуйте процесс, потом упаковывайте в навык.

Шаг 2. Создайте структуру

project/
└── .claude/
    └── skills/
        └── review-requirements/
            └── SKILL.md

Папка .claude/skills/ в корне проекта. Один навык — одна подпапка. Имя подпапки = name в YAML.

Если навыку нужны дополнительные файлы (шаблоны документов, примеры спек, CSV-таблицы терминов) — кладите их рядом с SKILL.md. Claude Code подгружает всю папку при активации.

Шаг 3. Напишите description

Самый ответственный шаг. description — это одновременно триггер и документация для коллег.

Плохо:

description: Помощь с ревью требований

Хорошо:

description: >
  Ревью функциональных требований: проверка полноты,
  непротиворечивости, прослеживаемости к бизнес-целям,
  наличия нефункциональных требований и критериев приёмки.
  Формат выдачи: таблица «проблема / серьёзность / исправление».

Формула: глагол + объект + контекст + формат выдачи. Не «помощь с X», а «делает Y в формате Z».

Шаг 4. Опишите инструкцию

Тело SKILL.md — это не промпт. Вы не просите модель что-то сделать, вы описываете, как она должна себя вести при активации навыка. Формулировки: «ты делаешь X», «формат выдачи — Y», «при обнаружении Z — сообщи отдельно».

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

Конкретные форматы выдачи обязательны. Если вы пишете «выдай результат», модель решит сама — и в 40% случаев формат не устроит. «Выдай таблицу с колонками A, B, C, D» — формат фиксирован.

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

Шаг 5. Протестируйте и доработайте

Возьмите реальный документ, который навык должен обработать. Дайте запрос, который должен активировать навык. Смотрите на результат.

Типичные проблемы первой итерации:

  • Навык не активируется. description слишком общий. Сузьте, добавьте ключевые слова из запроса.
  • Пропускает очевидные проблемы. Чек-лист неполный. Добавьте пункт, который навык пропустил.
  • Генерирует шум. Слишком много замечаний низкой серьёзности. Добавьте инструкцию «игнорировать стилистику, если не влияет на понимание».
  • Формат ответа плывёт. Не указан жёстко. Пропишите точный формат с примерами колонок.

После 2–3 итераций навык устаканивается. Дальше — только точечные правки при изменении процесса.

Ошибки, которые я совершил (чтобы вы не совершали)

Слишком общий description. Мой первый навык назывался «помощник аналитика». Claude Code активировал его на каждый второй запрос, включая «сколько сейчас времени». Сузьте до конкретной операции.

Один навык = одна задача. Не надо пихать ревью ТЗ, генерацию User Story и рисование диаграмм в один SKILL.md. Claude Code теряется в триггерах, и навык не срабатывает ни на что. Разделяйте.

Нет примеров формата. Модель понимает «таблица» по-своему. Иногда выдаёт markdown-таблицу, иногда — JSON, иногда — текстовый список. Если формат важен, покажите пример прямо в инструкции.

Навык без тестирования. Написали → закоммитили → коллега запустил → навык сломался на реальном документе. Тестируйте на боевых данных. Желательно на том документе, который вы ревьюили вручную — сравните результаты.

Игнорирование команды. Навык лежит в .claude/skills/, но никто кроме вас о нём не знает. Документируйте назначение в description (его читают коллеги в списке навыков) и упомяните в CLAUDE.md проекта.

Связка с другими инструментами

Навык не обязан работать в изоляции. Он может ссылаться на MCP-серверы, внешние файлы и другие навыки.

Практичный пример. В проекте настроен MCP-доступ к Jira. Навык ревью может начинаться с инструкции: «запроси через MCP все User Story эпика PROJ-42, сверь с ТЗ на соответствие». Claude Code идёт в Jira, вытаскивает стори, сравнивает с вашим документом.

Навык + MCP = замкнутый цикл. Без вашего участия.

Если вы ещё не работали с MCP — статья про AI-ассистента аналитика на MCP разбирает подключение к Jira, Confluence и базам данных.

Ещё вариант: навык ссылается на шаблоны в репозитории. Например, папка templates/ с файлом user-story-template.md. В SKILL.md: «используй шаблон из templates/user-story-template.md для форматирования». Claude Code читает файл и применяет структуру.

Чек-лист для аналитика

  • Выделите 1 повторяющуюся операцию — ту, на которой теряете минимум час в неделю
  • Формализуйте её в чек-лист с конкретными критериями и форматом выдачи
  • Создайте папку `.claude/skills/<имя>/SKILL.md`
  • Напишите description по формуле «глагол + объект + контекст + формат»
  • Протестируйте на реальном документе — не на выдуманном примере
  • Доработайте по результатам теста (обычно 1–2 итерации)
  • Закоммитьте — команда пусть знает, что ревью теперь делает робот (и делает неплохо)