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

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

Делиться

1. Введение

Экосистема Claude Code Skill стремительно расширяется. По состоянию на март 2026 года репозиторий anthropics/skills набрал более 87 000 звезд на GitHub, и каждую неделю все больше людей создают и делятся своими навыками.

Как структурированно создать навык с нуля? В этой статье подробно описаны этапы проектирования, создания и распространения навыка с нуля. В качестве примера я буду использовать свой собственный опыт запуска навыка для написания отзывов в интернет-магазине (ссылка).

2. Что такое навык Клода?

Навык Claude — это набор инструкций, обучающих Claude выполнению конкретных задач или рабочих процессов. Навыки — один из самых эффективных способов настройки Claude под ваши конкретные потребности.

Навыки строятся на основе поэтапного раскрытия информации. Клод получает информацию в три этапа:

• Метаданные (название + описание): Всегда в контексте Клода. Около 100 токенов. Клод принимает решение о загрузке навыка, основываясь исключительно на этих данных.
• Тело файла SKILL.md: Загружается только при срабатывании триггера.
• Встроенные ресурсы (scripts/, references/, assets/): Загружаются по запросу, когда это необходимо.

Благодаря такой структуре вы можете установить множество навыков, не перегружая контекстное окно. Если вы постоянно копируете и вставляете один и тот же длинный запрос, просто преобразуйте его в навык.

3. Навыки против MCP против субагентов

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

• Навыки учат Клода, как себя вести — аналитические рабочие процессы, стандарты кодирования, фирменные руководства.
• Серверы MCP предоставляют Клоду новые инструменты — отправку сообщений в Slack, запросы к базе данных.
• Суб-агенты позволили Клоду вести независимую работу в отдельном контексте.

Мне помогла следующая аналогия: MCP — это кухня — ножи, кастрюли, ингредиенты. Навык — это рецепт, который объясняет, как их использовать. Их можно комбинировать. Например, навык проверки кода Sentry определяет рабочий процесс анализа запросов на слияние в рамках одного навыка и получает данные об ошибках через MCP. Но во многих случаях для начала достаточно одного навыка.

4. Планирование и проектирование

В первый раз я сразу же приступил к написанию файла SKILL.md и столкнулся с проблемами. Если описание плохо продумано, навык даже не сработает. Я бы посоветовал потратить время на дизайн, прежде чем писать подсказки или код.

4a. Начните с вариантов использования.

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

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

Это стало отправной точкой. Вместо того чтобы создавать универсальный «навык анализа данных», я определил его следующим образом: «Навык, который принимает данные CSV-файлов с заказами, декомпозирует KPI в древовидную структуру, обобщает результаты с указанием приоритетов и генерирует конкретный план действий».

Здесь важно представить, как пользователи будут формулировать свои запросы на самом деле:

• «Проведите проверку моего магазина, используя файл orders.csv»
• «Проанализировать данные о продажах за последние 90 дней, выяснить причины снижения выручки».
• «Сравнить 3-й и 4-й кварталы и определить 3 главных момента, которые мне следует исправить».

Когда вы сначала формулируете конкретные задачи, подобную этим, структура навыка становится понятной. Входные данные — CSV-файл. Ось анализа — декомпозиция KPI. Выходные данные — отчет об обзоре и план действий. Пользователь — не специалист по анализу данных, а человек, управляющий бизнесом, и он хочет знать, что делать дальше.

Такой уровень детализации определяет все остальное: название навыка, описание, форматы файлов, формат вывода.

Вопросы, которые следует задавать при определении вариантов использования:

• Кто будет им пользоваться?
• В какой ситуации?
• Как они сформулируют свою просьбу?
• Что является входными данными?
• Какой ожидаемый результат?

4b. Вводная часть YAML

После того, как сценарии использования станут ясны, напишите название и описание. От этого зависит, будет ли ваш навык действительно срабатывать.

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

Чтобы еще больше усложнить ситуацию, Клод склонен самостоятельно справляться с простыми задачами, не обращаясь к навыкам. По умолчанию он не срабатывает. Поэтому ваше описание должно быть достаточно конкретным, чтобы Клод понял: «Это задача для навыка, а не для меня».

Поэтому описание должно быть несколько «настойчивым». Вот что я имею в виду.

 # Bad — too vague. Claude does not know when to trigger. name: data-helper description: Helps with data tasks # Good — specific trigger conditions, slightly "pushy" name: sales-data-analyzer description: > Analyze sales/revenue CSV and Excel files to find patterns, calculate metrics, and create visualizations. Use when user mentions sales data, revenue analysis, profit margins, churn, ad spend, or asks to find patterns in business metrics. Also trigger when user uploads xlsx/csv with financial or transactional column headers.

Самое важное — четко указать, что именно делает навык и какие входные данные он ожидает: «Анализ CSV- и Excel-файлов с данными о продажах/доходах» не оставляет места для двусмысленности. После этого перечислите ключевые слова-триггеры. Вернитесь к подсказкам по сценариям использования, которые вы написали в пункте 4a, и выделите слова, которые пользователи действительно произносят: данные о продажах, анализ доходов, рентабельность, отток клиентов. Наконец, подумайте о случаях, когда пользователь не упоминает ваш навык по имени. Фраза «Также срабатывать, когда пользователь загружает xlsx/csv-файлы с заголовками столбцов, содержащими финансовые или транзакционные данные» выявляет такие скрытые совпадения.

Ограничения следующие: имя — до 64 символов, описание — до 1024 символов (согласно спецификации API навыков агентов). Вам достаточно места, но отдавайте приоритет информации, непосредственно влияющей на срабатывание.

5. Модели реализации

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

5a. Структура файлов

Физическая структура навыка проста:

 my-skill/ ├── SKILL.md # Required. YAML frontmatter + Markdown instructions ├── scripts/ # Optional. Python/JS for deterministic processing │ ├── analyzer.py │ └── validator.js ├── references/ # Optional. Loaded by Claude as needed │ ├── advanced-config.md │ └── error-patterns.md └── assets/ # Optional. Templates, fonts, icons, etc. └── report-template.docx

Требуется только файл SKILL.md. Этого достаточно для корректной работы навыка. Старайтесь, чтобы SKILL.md не превышал 500 строк. Если он станет длиннее, переместите содержимое в каталог references/ и укажите Клоду в SKILL.md, где искать нужные файлы. Клод не будет читать файлы ссылок, если вы не укажете ему путь к ним.

Для навыков, которые подразделяются по областям знаний, хорошо подходит вариантный подход:

 cloud-deploy/ ├── SKILL.md # Shared workflow + selection logic └── references/ ├── aws.md ├── gcp.md └── azure.md

Клод считывает только соответствующий справочный файл в зависимости от контекста пользователя.

5b. Шаблон A: Только подсказка

Простейший шаблон. Только инструкции в формате Markdown в файле SKILL.md, никаких скриптов.

Подходит для: фирменных руководств, стандартов кодирования, контрольных списков проверки, форматирования сообщений коммитов, контроля стиля написания.

Когда использовать: Если языковых способностей и умения принимать решения Клода достаточно для выполнения задачи, используйте этот шаблон.

Вот краткий пример:

 --- name: commit-message-formatter description: > Format git commit messages using Conventional Commits. Use when user mentions commit, git message, or asks to format/write a commit message. --- # Commit Message Formatter Format all commit messages following Conventional Commits 1.0.0. ## Format ():  ## Rules - Imperative mood, lowercase, no period, max 72 chars - Breaking changes: add `!` after type/scope ## Example Input: "added user auth with JWT" Output: `feat(auth): implement JWT-based authentication`

Вот и всё. Никаких скриптов, никаких зависимостей. Если для решения задачи достаточно суждения Клода, то это всё, что вам нужно.

5c. Шаблон B: Подсказка + Сценарии

Инструкции по разметке Markdown и исполняемый код находятся в каталоге scripts/.

Подходит для: преобразования/проверки данных, обработки PDF-файлов/Excel-файлов/изображений, создания документов на основе шаблонов, составления числовых отчетов.

Поддерживаемые языки : Python и JavaScript/Node.js. Вот пример структуры:

 data-analysis-skill/ ├── SKILL.md └── scripts/ ├── analyze.py # Main analysis logic └── validate_schema.js # Input data validation

В файле SKILL.md указывается, когда следует вызывать каждый скрипт:

 ## Workflow 1. User uploads a CSV or Excel file 2. Run `scripts/validate_schema.js` to check column structure 3. If validation passes, run `scripts/analyze.py` with the file path 4. Present results with visualizations 5. If validation fails, ask user to clarify column mapping

В файле SKILL.md определяются «когда» и «почему». Скрипты отвечают за «как».

5d. Шаблон C: Навык + MCP / Субагент

Этот шаблон вызывает серверы MCP или субагентов из рабочего процесса навыка. Он хорошо подходит для рабочих процессов, включающих внешние сервисы — например, создание задачи → создание ветки → исправление кода → открытие запроса на слияние. Чем больше переменных, тем больше задач для отладки, поэтому я бы рекомендовал сначала освоить шаблон A или B.

Выбор правильного шаблона

Если вы не уверены, какой узор выбрать, следуйте этому порядку:

• Необходима связь в режиме реального времени с внешними API? → Да → Шаблон C
• Необходима детерминированная обработка, например, вычисления, проверка или преобразование файлов? → Да → Шаблон B
• Языковые способности и рассудительность Клода позволят ему справиться с этим в одиночку? → Да → Вариант А

Если сомневаетесь, начните с варианта А. Добавить скрипты позже и перейти к варианту Б несложно. Но упростить слишком сложный навык гораздо труднее.

6. Тестирование

Написание файла SKILL.md — это ещё не конец. Качество навыка определяется тем, насколько тщательно вы его тестируете и совершенствуете.

6a. Задания для письменных тестов

В данном контексте «тестирование» не означает модульные тесты. Это означает отправку реальных запросов к навыку и проверку его корректной работы.

Единственное правило для тестовых подсказок: пишите их так, как говорят реальные пользователи.

 # Good test prompt (realistic) "ok so my boss just sent me this XLSX file (its in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage. The revenue is in column C and costs are in column D i think" # Bad test prompt (too clean) "Please analyze the sales data in the uploaded Excel file and add a profit margin column"

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

6b. Цикл итерации

Базовый цикл тестирования прост:

1. Запустите навык с помощью тестовых подсказок.
2. Оцените, соответствует ли полученный результат тому, что вы определили как качественный результат в пункте 4а.
3. При необходимости исправьте файл SKILL.md.
4. Вернуться к 1

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

6c. Оптимизация описания

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

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

7. Распределение

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

Как донести свои навыки до пользователей

Для большинства людей все проблемы решаются двумя методами:

Загрузка ZIP-архива (claude.ai): Заархивируйте папку Skill в ZIP-архив и загрузите её через Настройки > Настройка > Навыки. Один нюанс — ZIP-архив должен содержать саму папку в корне, а не только её содержимое.

Каталог .claude/skills/ (Claude Code): Разместите навык в репозитории вашего проекта в каталоге .claude/skills/. Когда члены команды клонируют репозиторий, все получают один и тот же навык.

Помимо этого, по мере роста ваших потребностей в распространении появляются и другие варианты: Plugin Marketplace для распространения открытого исходного кода, Anthropic Official Marketplace для более широкого охвата, npx skills add от Vercel для кросс-агентских установок и Skills API для программного управления. Я не буду подробно останавливаться на каждом из них — документация хорошо их описывает.

Перед отправкой проверьте три вещи: папка в ZIP-архиве должна находиться в корневом каталоге (а не только содержимое), в метаданных имя и описание должны быть в пределах допустимого количества символов, и не должно быть жестко закодированных ключей API.

И ещё одно — увеличьте поле версии при обновлении. Иначе автоматическое обновление не сработает. Рассматривайте отзывы пользователей типа «это не сработало при этом запросе» как новые тестовые случаи. Цикл итерации из раздела 6 не заканчивается запуском.

Заключение

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

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

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

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

Хадзиме Такеда Посмотреть все работы Хадзиме Такеды

Источник: towardsdatascience.com