Система навыков

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

Что такое навык

По сути, навык — это файл, содержащий YAML frontmatter и тело в формате Markdown:

---
name: Code Review Standards
description: Unified code review standards and checklist for the project
---

# Code Review Standards

## Required Checks

1. Does the code follow naming conventions?
2. Are there any unused imports?
3. Does the file exceed the line limit?
4. Are there any leftover `console.log` statements?

## Review Template

**File**: `{filename}`
**Issues found**: {N}
**Severity**: High / Medium / Low

| # | Issue | Location | Suggestion |
|---|-------|----------|------------|
| 1 | ... | L42 | ... |

Агент использует инструмент list_skills, чтобы просмотреть доступные навыки, а затем инструмент read_skill — чтобы получить содержимое конкретного навыка и обращаться к нему при выполнении задачи.

Места обнаружения навыков

Навыки обнаруживаются и загружаются в следующем порядке:

Приоритет	Расположение	Путь	Метка источника	Описание
1	Рабочее пространство	.claude/skills/<name>/SKILL.md	workspace	Только для текущего проекта
2	Проект	<projectRoot>/.claude/skills/<name>/SKILL.md	project	Общий для всего проекта
3	Личный	~/.claude/skills/<name>/SKILL.md	personal	Доступен глобально для пользователя
4	Плагин	~/.elftia/plugins/skills/<name>/SKILL.md	plugin	Навыки, установленные сообществом
5	Встроенный	Встроен в приложение	builtin	Предустановленные навыки Elftia

Если несколько навыков имеют одинаковое имя, приоритет имеет тот, у которого он выше.

Инструменты для работы с навыками

Агенты взаимодействуют с системой навыков через два встроенных инструмента:

list_skills

Отображает все доступные навыки и их описания.

Параметры: отсутствуют

Пример вывода:

Available skills:
- code-standards (workspace): Project coding standards and best practices
- architecture-index (workspace): Project architecture index and file location guide
- build-optimization (personal): Build optimization standards

read_skill

Читает полное содержимое указанного навыка.

Параметры:

Параметр	Тип	Обязателен	Описание
name	string	Да	Имя навыка

Возвращает: полное Markdown-содержимое файла навыка.

Сообщество SkillHub

SkillHub — это сообщество для обмена навыками, где вы можете искать и устанавливать навыки, которыми поделились другие пользователи.

Поиск навыков

Агенты могут использовать инструмент skillhub_search для поиска навыков сообщества:

Search for skills related to "React best practices"

Установка навыков

Найдя нужный навык, используйте инструмент skillhub_install для его локальной установки:

Install the skill "react-best-practices" to the personal directory

Установленные навыки сохраняются в ~/.elftia/plugins/skills/ и доступны во всех проектах.

Привязка навыков к агенту

Существует два способа привязать навыки к агенту:

Способ 1: Объявление в конфигурации агента

Используйте поле skills во frontmatter агента:

---
name: Code Assistant
skills:
  - code-standards
  - architecture-index
---

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

Способ 2: Чтение во время выполнения

В процессе выполнения агент может активно вызывать list_skills и read_skill для получения содержимого навыков:

User: Please review this code according to the project standards
Agent: Let me check the available skills first... [calls list_skills]
Agent: Found the code-standards skill, let me read it... [calls read_skill]
Agent: Based on the standards, I found the following issues...

Создание пользовательских навыков

Шаги

1. Выберите место хранения навыка:

   • Специфичный для проекта → .claude/skills/<name>/SKILL.md
   • Глобально доступный → ~/.claude/skills/<name>/SKILL.md

2. Создайте директорию и файл:

mkdir -p .claude/skills/my-skill

3. Напишите файл SKILL.md:

---
name: My Skill
description: One-sentence description of the skill's purpose
---

# Skill Title

Detailed skill content...

Справка по формату SKILL.md

Базовый формат

---
name: Skill name
description: Brief description of the skill
---

Skill body content (Markdown format)

Полный формат (с расширенными метаданными)

---
name: Skill name
description: Skill description
always: false
allowedTools:
  - Read
  - Grep
  - Glob
metadata:
  always: false
  emoji: "📋"
  os:
    - win32
    - darwin
    - linux
  requires:
    bins:
      - node
      - npm
    env:
      - GITHUB_TOKEN
---

Skill body...

Справка по полям frontmatter

Поле	Тип	Описание
name	string	Отображаемое имя навыка
description	string	Краткое описание
always	boolean	Всегда ли добавлять в системный промпт (по умолчанию: false)
allowedTools	string[]	Разрешённый список инструментов при использовании навыка
metadata.always	boolean	То же, что always (вложенный формат)
metadata.emoji	string	Иконка отображения
metadata.os	string[]	Ограничение по платформе (пусто = все платформы)
metadata.requires.bins	string[]	Необходимые CLI-инструменты
metadata.requires.env	string[]	Необходимые переменные среды

Постоянно активные навыки

Навыки с always: true автоматически загружаются в системный промпт при каждом запуске агента — без необходимости объявлять их в конфигурации агента. Это удобно для базовых стандартов на уровне проекта.

Разрешённый список инструментов

Поле allowedTools позволяет ограничить набор инструментов, доступных агенту при использовании данного навыка. Это полезно в сценариях с повышенными требованиями к безопасности, например:

allowedTools:
  - Read
  - Grep
  - Glob

Это ограничивает доступные агенту инструменты только инструментами для чтения.

Лучшие практики написания навыков

Чёткая структура

---
name: API Design Standards
description: RESTful API design guide and naming conventions
---

# API Design Standards

## Naming Rules
- URLs use kebab-case
- Query parameters use camelCase

## Status Code Usage
- 200: Success
- 201: Created
- 400: Bad request parameters

## Checklist
- [ ] Does the URL conform to RESTful conventions?
- [ ] Is there appropriate error handling?
- [ ] Is pagination supported?

Практические советы

1. Фокусируйтесь на одной теме — один навык решает один класс задач
2. Приводите конкретные примеры — включайте фрагменты кода и шаблоны
3. Используйте чек-листы — это позволяет агенту системно выполнять задачу
4. Укажите область применения — опишите предварительные условия и ограничения навыка
5. Соблюдайте краткость — избегайте чрезмерно длинного содержимого навыка, которое занимает слишком много места в контекстном окне

Часто задаваемые вопросы

Проблема	Причина	Решение
Агент не может найти навык	Файл навыка находится не по правильному пути или имя не совпадает	Используйте list_skills, чтобы проверить доступные имена навыков
Содержимое навыка не добавлено в системный промпт	Навык не объявлен в конфигурации агента, а always равно false	Добавьте его в поле skills или установите always: true
Инструменты, требуемые навыком, недоступны	Разрешённый список инструментов агента не включает необходимые инструменты	Добавьте необходимые инструменты в конфигурацию агента
Ограничение по платформе делает навык недоступным	metadata.os ограничивает текущую платформу	Измените поле os или установите необходимые зависимости на текущей платформе
Содержимое навыка слишком длинное и снижает производительность	Содержимое навыка занимает слишком много контекстного окна	Разделите на несколько небольших навыков и загружайте по требованию
Поиск в SkillHub не даёт результатов	Ключевые слова поиска не совпадают	Попробуйте другие ключевые слова или поиск на английском языке

Связанные ссылки

• Обзор агентов — общий обзор системы агентов
• Создание пользовательских агентов — настройка навыков в агенте
• Разрешения инструментов и безопасность — механизм разрешённого списка инструментов