# Как создать Claude Skill: пошаговое руководство по своим навыкам для Claude > AI Release · @ai_release1 · https://ai-release.org/guides/kak-sozdat-claude-skill-poshagovoe-rukovodstvo-po-svoim.html ## TL;DR - Время выполнения: 25–40 минут (первый навык), 10 минут на каждый следующий. - Уровень сложности: Basic. - Понадобится: терминал (bash на Linux/macOS или PowerShell 7 на Windows), утилита `zip` или `Compress-Archive`, текстовый редактор, аккаунт Claude с доступом к разделу Skills (проверьте наличие пункта в настройках), API-ключ Anthropic — если планируете вызывать навык через API. - Результат: папка навыка с файлом `SKILL.md`, ZIP-архив и работающий тест, где Claude сам подхватывает навык по описанию. Термины коротко. **Skill (навык)** — папка с инструкциями и файлами, которую Claude подгружает, когда задача совпадает с её описанием. **Frontmatter** — блок между двумя строками `---` в начале markdown-файла, где задаются имя и описание. **Progressive disclosure** — принцип, по которому Claude сначала читает только имя и описание, а тело инструкции и вложенные файлы открывает лишь при необходимости. ## Требования и подготовка ![Иллюстрация к разделу «Требования и подготовка»](https://ai-release.org/guides/img/kak-sozdat-claude-skill-poshagovoe-rukovodstvo-po-svoim-ru-1.jpg) - ОС: Linux, macOS или Windows 10/11. Команды ниже даны для обоих вариантов. - Проверьте `zip`: в Linux/macOS — `zip -v`, в Windows — `powershell -Command "Get-Command Compress-Archive"`. Если команды нет, поставьте пакет: `sudo apt install zip` (Debian/Ubuntu). - Python 3.9+ нужен только для навыков со скриптами: `python3 --version`. Минимальную поддерживаемую версию сверьте с документацией. - Доступ к Skills в интерфейсе Claude: откройте Settings и найдите раздел с навыками (Capabilities / Skills — название зависит от клиента, сверьтесь с документацией). - API-ключ, если нужен программный вызов: переменная окружения `ANTHROPIC_API_KEY`. - Свободное место: папка навыка — обычно единицы килобайт, но если кладёте справочники и скрипты, заложите 10–50 МБ. Проверка подготовки одной командой: ```bash mkdir -p ~/skills && cd ~/skills && pwd && python3 --version && zip -v | head -n 2 ``` Ожидаемый вывод: путь вида `/home//skills`, строка версии Python и баннер `Zip 3.0 ...`. Если `pwd` вернул ошибку — папка не создалась, проверьте права на домашний каталог. ## Шаг 1. Соберите каркас навыка **Что сделать:** создайте папку навыка и три элемента внутри: `SKILL.md` (обязательный), `scripts/` (исполняемые файлы, необязательно), `references/` (справочники, необязательно). **Зачем:** Claude ищет точку входа по имени файла `SKILL.md`; без него архив не распознается как навык. Разделение на `scripts/` и `references/` — это и есть progressive disclosure: тяжёлые файлы не попадают в контекст, пока модель их не запросит. **Пример:** навык `server-health-check`, который проверяет состояние сервера по SSH. ```bash mkdir -p ~/skills/server-health-check/scripts mkdir -p ~/skills/server-health-check/references cd ~/skills/server-health-check touch SKILL.md scripts/check_disk.sh references/checklist.md ``` **Как проверить:** выведите дерево каталога. ```bash find . -type f | sort ``` Ожидаемый вывод — ровно три строки: ``` ./SKILL.md ./references/checklist.md ./scripts/check_disk.sh ``` Если файлов меньше — не сработал `touch`, проверьте, что вы находитесь в папке навыка (`pwd`). Если навык должен опрашивать ваш собственный сервер, подготовьте доступы заранее: как поднять сам хост и сервисы, разобрано в гайде [Как подключить ИИ к домашнему серверу](https://ai-release.org/guides/kak-podklyuchit-ii-k-domashnemu-serveru-poshagovoe-ruko.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide). ## Шаг 2. Заполните SKILL.md и упакуйте навык в ZIP **Что сделать:** напишите frontmatter и тело инструкции, затем соберите архив. **Зачем:** имя и описание — единственное, что Claude видит до активации навыка. Именно по описанию он решает, включать навык или нет, поэтому в описании должны быть глаголы и триггеры («проверить», «посчитать», «сформировать отчёт»), а не общие слова вроде «полезный навык». **Пример:** содержимое `SKILL.md`. ```markdown --- name: server-health-check description: Проверяет доступность сервера по SSH, свободное место на диске и нагрузку. Используйте, когда пользователь просит проверить состояние сервера, узнать остаток диска или диагностировать зависший сервис. --- # Проверка состояния сервера ## Когда применять Запросы вида «сервер тормозит», «сколько места осталось», «жив ли сервис». ## Порядок действий 1. Запусти `scripts/check_disk.sh` через инструмент исполнения кода. 2. Сверь результат с `references/checklist.md`. 3. Верни отчёт в трёх строках: диск, память, статус сервиса. ## Ограничения ![Иллюстрация к разделу «Ограничения»](https://ai-release.org/guides/img/kak-sozdat-claude-skill-poshagovoe-rukovodstvo-po-svoim-ru-2.jpg) Не выполняй перезапуск сервисов. Только диагностика. ``` Правила frontmatter: `name` — строчные латинские буквы, цифры и дефисы, без пробелов; `description` — одно-два предложения с явными триггерами. Конкретные лимиты длины полей сверьте с документацией. **Как проверить YAML-валидность** до упаковки: ```bash python3 -c "import sys,yaml;t=open('SKILL.md').read().split('---')[1];print(yaml.safe_load(t))" ``` Ожидаемый вывод — словарь с ключами `name` и `description`: ``` {'name': 'server-health-check', 'description': 'Проверяет доступность сервера по SSH...'} ``` Если вместо этого `yaml.scanner.ScannerError` — в frontmatter лишняя кавычка или двоеточие в описании без кавычек. **Упаковка:** ```bash cd ~/skills/server-health-check zip -r ../server-health-check.zip . -x ".*" -x "__MACOSX/*" unzip -l ../server-health-check.zip ``` Ожидаемый вывод `unzip -l`: в списке есть `SKILL.md` в корне архива, а не внутри вложенной папки. Это критично: если после распаковки получается `server-health-check/SKILL.md`, навык не установится. **Загрузка:** в интерфейсе Claude — Settings → раздел навыков → загрузка архива → выберите `server-health-check.zip`. Через API архив отправляется в эндпоинт управления навыками; точное имя поля и обязательный beta-заголовок сверьте с документацией: ```bash curl https://api.anthropic.com/v1/skills \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: " \ -F "display_title=Server Health Check" \ -F "files[]=@server-health-check.zip" ``` **Как проверить:** ответ должен содержать идентификатор созданного навыка (поле вида `id`, например `skill_...`). Сохраните его — он нужен для вызовов из API. Код ответа `400` означает проблему с архивом, `401` — с ключом. ## Шаг 3. Проверьте, что навык срабатывает ![Иллюстрация к разделу «Шаг 3. Проверьте, что навык срабатывает»](https://ai-release.org/guides/img/kak-sozdat-claude-skill-poshagovoe-rukovodstvo-po-svoim-ru-3.jpg) **Что сделать:** задайте в чате вопрос, который совпадает с описанием, и убедитесь, что Claude открыл `SKILL.md`. Затем повторите вопрос, который с навыком не связан. **Зачем:** навык бесполезен, если модель его не выбирает. Проверка на «горячем» и «холодном» запросе показывает, что срабатывает именно описание, а не случайность. **Пример горячего запроса:** «Проверь сервер, сколько осталось места на диске». Признаки успеха на экране: Claude упоминает использование навыка (строка вида «Using skill: server-health-check» в интерфейсе или блок `tool_use` с именем навыка в ответе API), а ответ содержит три запрошенные строки — диск, память, статус сервиса. **Пример холодного запроса:** «Напиши хайку про осень». Навык не должен активироваться. **Как проверить через API:** передайте идентификатор навыка в запросе к модели. ```bash curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: " \ -H "content-type: application/json" \ -d '{ "model": "<актуальная модель из документации>", "max_tokens": 1024, "container": {"skills": [{"type": "custom", "skill_id": "", "version": "latest"}]}, "messages": [{"role": "user", "content": "Проверь сервер, сколько осталось места на диске"}] }' ``` Ожидаемый результат: в JSON-ответе есть `content` с текстом отчёта, а в логах — обращение к скрипту навыка. Почему это работает: контейнер исполнения кода получает папку навыка целиком, поэтому `scripts/check_disk.sh` доступен по относительному пути. Чек-лист приёмки: - [ ] `SKILL.md` лежит в корне ZIP. - [ ] YAML распарсился без ошибок. - [ ] Горячий запрос активирует навык. - [ ] Холодный запрос навык не активирует. - [ ] Ответ содержит ожидаемые поля отчёта. ## Возможные проблемы и решения **Проблема. Архив загружается, но навык не появляется в списке** - Ошибка: `Invalid skill package: SKILL.md not found at archive root` (формулировка зависит от клиента, сверьтесь с документацией). - Причина: при упаковке вы выполнили `zip -r` из родительского каталога, и `SKILL.md` оказался внутри вложенной папки. - Решение: пересоберите архив изнутри папки навыка и проверьте корень: ```bash cd ~/skills/server-health-check && zip -r ../server-health-check.zip . && unzip -l ../server-health-check.zip | grep SKILL.md ``` В выводе должна быть строка `SKILL.md` без префикса-каталога. **Проблема. Навык не активируется на профильные запросы** - Ошибка: текст ошибки отсутствует, в интерфейсе видно, что ответ дан без обращения к навыку. - Причина: описание в frontmatter слишком общее («помогает с серверами») — модель не находит совпадения с формулировкой пользователя. - Решение: перепишите `description`, добавив глаголы и синонимы запросов, затем загрузите новую версию архива и повторите горячий тест: ```yaml description: Проверяет доступность сервера по SSH, свободное место на диске и нагрузку. Используйте, когда просят проверить состояние сервера, узнать остаток диска, диагностировать зависший сервис или «сервер тормозит». ``` **Проблема. Скрипт навыка падает при запуске** - Ошибка: `Permission denied` или `bash: ./scripts/check_disk.sh: /bin/bash^M: bad interpreter: No such file or directory`. - Причина: у файла нет бита исполнения либо он сохранён в Windows с переводами строк CRLF. - Решение: выдайте права и снимите CRLF: ```bash chmod +x scripts/check_disk.sh sed -i 's/\r$//' scripts/check_disk.sh ``` После правок пересоберите ZIP — изменения в уже загруженный архив не подтягиваются автоматически. ## Резюме и следующие шаги Навык — это папка с `SKILL.md`, корректным frontmatter и, при необходимости, скриптами, упакованная так, чтобы файл инструкции лежал в корне архива. Дальше добавьте второй навык под повторяющуюся задачу и свяжите его с мониторингом по гайду [Как настроить мониторинг VPS через Telegram-бота с Mini App](https://ai-release.org/guides/kak-nastroit-monitoring-vps-cherez-telegram-bota-s-mini.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide). ## FAQ **Чем Skill отличается от обычного промпта?** Промпт вы вставляете в каждый диалог вручную, а навык хранится отдельно и подключается автоматически, когда описание совпало с задачей; внутрь навыка можно положить скрипты и справочники. **Нужен ли API-ключ, чтобы создать навык?** Нет, если вы работаете в интерфейсе Claude и загружаете ZIP вручную. Ключ нужен только для загрузки и вызова навыка программно. **Обязательно ли класть в навык скрипты?** Нет. Минимальный рабочий навык — один `SKILL.md` с инструкцией и критериями применения; `scripts/` и `references/` добавляют, когда нужны вычисления или большие справочники. **Что делать, если после правки файлов навык работает по-старому?** Загрузите архив заново: правки в локальной папке не синхронизируются с уже установленной версией. Перед повторной загрузкой проверьте `unzip -l`, что в архиве новые файлы.