Это руководство показывает, как создавать, использовать и управлять навыками агентов в Claude Code. Навыки — это модульные возможности, которые расширяют функциональность Claude через организованные папки, содержащие инструкции, скрипты и ресурсы.
Предварительные требования
- Claude Code версии 1.0 или новее
- Базовое знакомство с Claude Code
Что такое навыки агентов?
Навыки агентов упаковывают экспертизу в обнаруживаемые возможности. Каждый навык состоит из файла SKILL.md с инструкциями, которые Claude читает при необходимости, плюс дополнительные поддерживающие файлы, такие как скрипты и шаблоны.
Как вызываются навыки: Навыки вызываются моделью — Claude автономно решает, когда их использовать, основываясь на вашем запросе и описании навыка. Это отличается от слэш-команд, которые вызываются пользователем (вы явно вводите /команда для их активации).
Преимущества:
- Расширяют возможности Claude для ваших специфических рабочих процессов
- Делятся экспертизой в команде через git
- Сокращают повторяющиеся промпты
- Объединяют несколько навыков для сложных задач
Узнайте больше в обзоре навыков агентов.
Создание навыка
Навыки хранятся как директории, содержащие файл SKILL.md.
Персональные навыки
Персональные навыки доступны во всех ваших проектах. Храните их в ~/.claude/skills/:
mkdir -p ~/.claude/skills/my-skill-name
- Ваших индивидуальных рабочих процессов и предпочтений
- Экспериментальных навыков, которые вы разрабатываете
- Личных инструментов продуктивности
Проектные навыки
Проектные навыки делятся с вашей командой. Храните их в .claude/skills/ внутри вашего проекта:
mkdir -p .claude/skills/my-skill-name
- Командных рабочих процессов и соглашений
- Специфической для проекта экспертизы
- Общих утилит и скриптов
Проектные навыки фиксируются в git и автоматически доступны членам команды.
Навыки плагинов
Навыки также могут поступать из плагинов Claude Code. Плагины могут включать навыки, которые автоматически становятся доступными при установке плагина. Эти навыки работают так же, как персональные и проектные навыки.
Написание SKILL.md
Создайте файл SKILL.md с YAML frontmatter и содержимым Markdown:
---
name: Название вашего навыка
description: Краткое описание того, что делает этот навык и когда его использовать
---
# Название вашего навыка
## Инструкции
Предоставьте четкие пошаговые указания для Claude.
## Примеры
Покажите конкретные примеры использования этого навыка.
description критически важно для того, чтобы Claude обнаружил, когда использовать ваш навык. Оно должно включать как то, что делает навык, так и когда Claude должен его использовать.
См. руководство по лучшим практикам для полного руководства по созданию.
Добавление поддерживающих файлов
Создайте дополнительные файлы рядом с SKILL.md:
my-skill/
├── SKILL.md (обязательный)
├── reference.md (дополнительная документация)
├── examples.md (дополнительные примеры)
├── scripts/
│ └── helper.py (дополнительная утилита)
└── templates/
└── template.txt (дополнительный шаблон)
Для продвинутого использования см. [reference.md](reference.md).
Запустите вспомогательный скрипт:
```bash
python scripts/helper.py input.txt
```
allowed-tools для ограничения того, какие инструменты Claude может использовать, когда навык активен:
---
name: Безопасный читатель файлов
description: Читает файлы без внесения изменений. Используйте, когда нужен доступ к файлам только для чтения.
allowed-tools: Read, Grep, Glob
---
# Безопасный читатель файлов
Этот навык предоставляет доступ к файлам только для чтения.
## Инструкции
1. Используйте Read для просмотра содержимого файлов
2. Используйте Grep для поиска внутри файлов
3. Используйте Glob для поиска файлов по шаблону
- Навыков только для чтения, которые не должны изменять файлы
- Навыков с ограниченной областью действия (например, только анализ данных, без записи файлов)
- Рабочих процессов, критичных к безопасности, где вы хотите ограничить возможности
Если allowed-tools не указан, Claude будет спрашивать разрешение на использование инструментов как обычно, следуя стандартной модели разрешений.
allowed-tools поддерживается только для навыков в Claude Code.
Просмотр доступных навыков
Навыки автоматически обнаруживаются Claude из трех источников:
- Персональные навыки:
~/.claude/skills/
- Проектные навыки:
.claude/skills/
- Навыки плагинов: включены в установленные плагины
Чтобы просмотреть все доступные навыки, спросите Claude напрямую:
или
Перечисли все доступные навыки
# Список персональных навыков
ls ~/.claude/skills/
# Список проектных навыков (если в директории проекта)
ls .claude/skills/
# Просмотр содержимого конкретного навыка
cat ~/.claude/skills/my-skill/SKILL.md
Тестирование навыка
После создания навыка протестируйте его, задавая вопросы, которые соответствуют вашему описанию.
Пример: Если ваше описание упоминает “PDF файлы”:
Можете ли вы помочь мне извлечь текст из этого PDF?
Отладка навыка
Если Claude не использует ваш навык, проверьте эти распространенные проблемы:
Сделайте описание конкретным
Слишком расплывчато:
description: Помогает с документами
description: Извлекает текст и таблицы из PDF файлов, заполняет формы, объединяет документы. Используйте при работе с PDF файлами или когда пользователь упоминает PDF, формы или извлечение документов.
Проверьте путь к файлу
Персональные навыки: ~/.claude/skills/skill-name/SKILL.md
Проектные навыки: .claude/skills/skill-name/SKILL.md
Проверьте, что файл существует:
# Персональный
ls ~/.claude/skills/my-skill/SKILL.md
# Проектный
ls .claude/skills/my-skill/SKILL.md
Проверьте синтаксис YAML
Неверный YAML препятствует загрузке навыка. Проверьте frontmatter:
cat SKILL.md | head -n 10
- Открывающий
--- на строке 1
- Закрывающий
--- перед содержимым Markdown
- Верный синтаксис YAML (без табуляций, правильные отступы)
Просмотр ошибок
Запустите Claude Code в режиме отладки, чтобы увидеть ошибки загрузки навыков:
Обмен навыками с командой
Рекомендуемый подход: Распространяйте навыки через плагины.
Чтобы поделиться навыками через плагин:
- Создайте плагин с навыками в директории
skills/
- Добавьте плагин в маркетплейс
- Члены команды устанавливают плагин
Для полных инструкций см. Добавление навыков в ваш плагин.
Вы также можете делиться навыками напрямую через репозитории проектов:
Шаг 1: Добавьте навык в ваш проект
Создайте проектный навык:
mkdir -p .claude/skills/team-skill
# Создайте SKILL.md
Шаг 2: Зафиксируйте в git
git add .claude/skills/
git commit -m "Add team Skill for PDF processing"
git push
Шаг 3: Члены команды получают навыки автоматически
Когда члены команды получают последние изменения, навыки сразу становятся доступными:
git pull
claude # Навыки теперь доступны
Обновление навыка
Редактируйте SKILL.md напрямую:
# Персональный навык
code ~/.claude/skills/my-skill/SKILL.md
# Проектный навык
code .claude/skills/my-skill/SKILL.md
Удаление навыка
Удалите директорию навыка:
# Персональный
rm -rf ~/.claude/skills/my-skill
# Проектный
rm -rf .claude/skills/my-skill
git commit -m "Remove unused Skill"
Лучшие практики
Держите навыки сфокусированными
Один навык должен решать одну возможность:
Сфокусированный:
- “Заполнение PDF форм”
- “Анализ данных Excel”
- “Сообщения коммитов Git”
Слишком широкий:
- “Обработка документов” (разделите на отдельные навыки)
- “Инструменты данных” (разделите по типу данных или операции)
Пишите четкие описания
Помогите Claude обнаружить, когда использовать навыки, включив конкретные триггеры в ваше описание:
Четкое:
description: Анализирует электронные таблицы Excel, создает сводные таблицы и генерирует диаграммы. Используйте при работе с файлами Excel, электронными таблицами или анализе табличных данных в формате .xlsx.
Тестируйте с вашей командой
Пусть товарищи по команде используют навыки и предоставляют обратную связь:
- Активируется ли навык, когда ожидается?
- Понятны ли инструкции?
- Есть ли недостающие примеры или крайние случаи?
Документируйте версии навыков
Вы можете документировать версии навыков в содержимом вашего SKILL.md для отслеживания изменений со временем. Добавьте раздел истории версий:
# Мой навык
## История версий
- v2.0.0 (2025-10-01): Критические изменения в API
- v1.1.0 (2025-09-15): Добавлены новые функции
- v1.0.0 (2025-09-01): Первоначальный выпуск
Устранение неполадок
Claude не использует мой навык
Симптом: Вы задаете релевантный вопрос, но Claude не использует ваш навык.
Проверьте: Достаточно ли конкретно описание?
Расплывчатые описания затрудняют обнаружение. Включите как то, что делает навык, так и когда его использовать, с ключевыми терминами, которые пользователи бы упомянули.
Слишком общее:
description: Помогает с данными
description: Анализирует электронные таблицы Excel, генерирует сводные таблицы, создает диаграммы. Используйте при работе с файлами Excel, электронными таблицами или файлами .xlsx.
# Просмотр frontmatter
cat .claude/skills/my-skill/SKILL.md | head -n 15
# Проверка распространенных проблем
# - Отсутствующие открывающие или закрывающие ---
# - Табуляции вместо пробелов
# - Нецитированные строки со специальными символами
# Персональные навыки
ls ~/.claude/skills/*/SKILL.md
# Проектные навыки
ls .claude/skills/*/SKILL.md
Навык имеет ошибки
Симптом: Навык загружается, но работает неправильно.
Проверьте: Доступны ли зависимости?
Claude автоматически установит необходимые зависимости (или попросит разрешение на их установку), когда они ему понадобятся.
Проверьте: Имеют ли скрипты права на выполнение?
chmod +x .claude/skills/my-skill/scripts/*.py
scripts/helper.py
Неправильно: scripts\helper.py (стиль Windows)
Несколько навыков конфликтуют
Симптом: Claude использует неправильный навык или кажется запутанным между похожими навыками.
Будьте конкретны в описаниях: Помогите Claude выбрать правильный навык, используя отличительные триггерные термины в ваших описаниях.
Вместо:
# Навык 1
description: Для анализа данных
# Навык 2
description: Для анализа данных
# Навык 1
description: Анализирует данные продаж в файлах Excel и экспортах CRM. Используйте для отчетов о продажах, анализа воронки и отслеживания доходов.
# Навык 2
description: Анализирует файлы логов и данные системных метрик. Используйте для мониторинга производительности, отладки и системной диагностики.
Примеры
Простой навык (один файл)
commit-helper/
└── SKILL.md
---
name: Генерация сообщений коммитов
description: Генерирует четкие сообщения коммитов из git diff. Используйте при написании сообщений коммитов или просмотре подготовленных изменений.
---
# Генерация сообщений коммитов
## Инструкции
1. Запустите `git diff --staged` для просмотра изменений
2. Я предложу сообщение коммита с:
- Резюме менее 50 символов
- Подробное описание
- Затронутые компоненты
## Лучшие практики
- Используйте настоящее время
- Объясняйте что и почему, а не как
Навык с разрешениями инструментов
code-reviewer/
└── SKILL.md
---
name: Рецензент кода
description: Проверяет код на лучшие практики и потенциальные проблемы. Используйте при рецензировании кода, проверке PR или анализе качества кода.
allowed-tools: Read, Grep, Glob
---
# Рецензент кода
## Чек-лист рецензирования
1. Организация и структура кода
2. Обработка ошибок
3. Соображения производительности
4. Проблемы безопасности
5. Покрытие тестами
## Инструкции
1. Читайте целевые файлы с помощью инструмента Read
2. Ищите шаблоны с помощью Grep
3. Находите связанные файлы с помощью Glob
4. Предоставляйте подробную обратную связь о качестве кода
Многофайловый навык
pdf-processing/
├── SKILL.md
├── FORMS.md
├── REFERENCE.md
└── scripts/
├── fill_form.py
└── validate.py
---
name: Обработка PDF
description: Извлекает текст, заполняет формы, объединяет PDF. Используйте при работе с PDF файлами, формами или извлечении документов. Требует пакеты pypdf и pdfplumber.
---
# Обработка PDF
## Быстрый старт
Извлечение текста:
```python
import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
text = pdf.pages[0].extract_text()
```
Для заполнения форм см. [FORMS.md](FORMS.md).
Для подробного справочника API см. [REFERENCE.md](REFERENCE.md).
## Требования
Пакеты должны быть установлены в вашей среде:
```bash
pip install pypdf pdfplumber
```
Перечислите необходимые пакеты в описании. Пакеты должны быть установлены в вашей среде до того, как Claude сможет их использовать.
Следующие шаги
