Перейти к основному содержимому

Навыки (Skills)

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

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

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

Навык представляет собой директорию с файлом SKILL.md, который содержит:

  1. Метаданные (YAML frontmatter) — информация для принятия решений об активации
  2. Тело навыка (Markdown) — подробные инструкции по выполнению задачи
  3. Ресурсы (опционально) — дополнительные файлы, скрипты, шаблоны

Структура навыка​

Пример SKILL.md:

---
name: processing-excel-files
description: "Анализирует Excel-файлы, создаёт сводные таблицы и графики. Используйте при работе с .xlsx файлами, табличными данными, анализом данных."
when-to-use: |
  - Пользователь просит проанализировать Excel-файл
  - Нужно создать сводную таблицу или график
  - Пользователь говорит "этот файл" и файл является таблицей
user-invocable: true
disable-model-invocation: false
argument-hint: "[имя-файла] — опционально. Если не указано, навык запросит файл."
---

# Processing Excel Files

Этот навык предоставляет инструкции по анализу Excel-файлов и созданию визуализаций.

## Когда использовать этот навык

- Требуется работы с файлами форматов .xlsx или .xls файл
- Требуется анализ табличных данных
- Нужно создать сводную таблицу или график

## Рабочий процесс

### Шаг 1 — Чтение файла

Используйте инструмент `read_file` для загрузки Excel-файла.

### Шаг 2 — Анализ данных

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

### Шаг 3 — Визуализация

Создайте графики или сводные таблицы на основе данных.

## Анти-паттерны

- Не пытайтесь читать бинарные файлы как текст
- Всегда проверяйте размер файла перед обработкой

Пример структуры навыка с ресурсами:

processing-excel-files/
├── SKILL.md
├── scripts/
│   └── build-pivot-table.go
├── assets/
│   └── sales-report-template.md
└── references/
    └── chart-style-guide.md

Ресурсы — это любые дополнительные файлы рядом с SKILL.md, которые помогают выполнить навык, но не должны всегда попадать в основной текст инструкции. При активации навыка Nestor передаёт агенту список таких файлов относительными путями, а их содержимое агент читает только при необходимости. Папки scripts/, references/ и assets/ не обязательны для рантайма — это соглашение для понятной организации: скрипты для повторяемых операций, справочники и подробные инструкции, шаблоны и заготовки для итогового результата.

Пути к ресурсам указывайте относительно директории навыка, то есть папки, где лежит SKILL.md. В SKILL.md достаточно явно указать, когда и какой ресурс использовать, например: "если нужно построить сводную таблицу, запустите go run <skill-dir>/scripts/build-pivot-table.go" или "для отчёта используйте шаблон <skill-dir>/assets/sales-report-template.md".

Поля метаданных​

ПолеТипОбязательноеОписание
namestring✅Уникальное имя навыка (lowercase, цифры, дефисы, макс. 64 символа)
descriptionstring✅Что делает навык и когда его использовать. Указывайте конкретные триггерные фразы
when-to-usestring❌Дополнительные условия активации, edge cases
user-invocableboolean❌Может ли пользователь вызывать навык напрямую (по умолчанию true)
disable-model-invocationboolean❌Отключить автоматическую активацию моделью (по умолчанию false)
argument-hintstring❌Подсказка по аргументам навыка

Правила для поля description​

  • ✅ Всегда от третьего лица ("Анализирует Excel-файлы…", а не "Я могу проанализировать…")
  • ✅ Должно включать что делает навык и когда его использовать
  • ✅ Перечисляйте конкретные триггерные фразы
  • ✅ Будьте настойчивы в активации — модели склонны недо-активировать навыки

Примеры:

✅ Хорошо:

description: "Генерирует conventional-commit сообщения из staged git diffs. Используйте когда пользователь просит commit message, говорит 'commit this', просматривает staged changes или вставляет diff."

❌ Плохо:

description: "Помогает с коммитами"  # Слишком размыто
description: "Я могу создать commit message"  # От первого лица
description: "Создаёт commit сообщения"  # Нет условий активации

Где хранятся навыки​

Навыки загружаются из трёх уровней:

1. Встроенные навыки​

Поставляются с плагином, доступны всем пользователям.

Пример: Встроенный навык create-skill для создания новых навыков.

2. Глобальные навыки (пользовательские)​

~/.agents/skills/<skill-name>/SKILL.md
~/.claude/skills/<skill-name>/SKILL.md
~/.cline/skills/<skill-name>/SKILL.md
~/.roo/skills/<skill-name>/SKILL.md

Доступны во всех проектах пользователя.

3. Локальные навыки (воркспейс)​

<workspace>/skills/<skill-name>/SKILL.md
<workspace>/.skills/<skill-name>/SKILL.md

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

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

Как использовать навыки​

Упоминание в чате​

Используйте синтаксис упоминаний для явного указания навыка:

@skill:skill-name

Как это работает:

  1. Введите @skill: в поле ввода сообщения
  2. Появится список доступных навыков с поиском
  3. Выберите нужный навык или продолжите ввод для фильтрации
  4. Упоминание автоматически преобразуется в формат @skill:skill-name

Демо

Автоматическая активация​

Модель может автоматически активировать навыки на основе:

  • Контекста задачи
  • Упоминаний в сообщении
  • Анализа содержимого файлов

Навыки с disable-model-invocation: false (по умолчанию) могут активироваться моделью без явного запроса пользователя.

Создание навыков​

Использование навыка create-skill​

Проект включает встроенный мета-навык create-skill для создания новых навыков.

Как активировать:

@skill:create-skill

Или попросите агента: "Создай навык для [описание задачи]".

Ручное создание навыка​

Шаг 1 — Выберите расположение​

  • Глобальный навык: ~/.agents/skills/<skill-name>/
  • Локальный навык: <workspace>/.skills/<skill-name>/

Шаг 2 — Создайте директорию​

mkdir -p ~/.agents/skills/processing-excel-files

Шаг 3 — Создайте SKILL.md​

Используйте шаблон:

---
name: skill-name
description: "Что делает навык. Когда использовать. Триггерные фразы."
when-to-use: |
  - Условие 1
  - Условие 2
user-invocable: true
disable-model-invocation: false
---

# Skill Name

Краткое описание навыка.

## Когда использовать этот навык

- Условие активации 1
- Условие активации 2

Не активируйте для: [случаи, которые не относятся к этому навыку].

## Рабочий процесс

### Шаг 1 — <название>

Что делать и почему.

### Шаг 2 — <название>

Что делать и почему.

### Шаг 3 — Проверка

Как подтвердить правильность результата.

## Анти-паттерны

- [Распространённая ошибка 1 и почему это неправильно]
- [Распространённая ошибка 2]

Шаг 4 — Проверка​

Убедитесь, что:

  • Имя в name совпадает с именем директории
  • Frontmatter корректен (прямые кавычки, нет табов, закрывающий ---)
  • Описание понятное и конкретное
  • Если навык использует ресурсы, в SKILL.md указано, что пути к ним считаются от директории навыка

Лучшие практики​

Написание описания​

Делайте:

  • Объясняйте почему, а не только что
  • Используйте императив в инструкциях ("Прочитайте файл", "Проверьте вывод")
  • Сохраняйте консистентную терминологию
  • Приводите конкретные примеры ввода/вывода
  • Избегайте чувствительных ко времени формулировок ("после августа 2025…")

Не делайте:

  • Стены MUST / NEVER / ALWAYS без объяснений
  • Перечисление всех возможных библиотек/подходов
  • Размещение условий активации только в теле (используйте when-to-use)
  • Преждевременное разделение на много файлов

Размер навыка​

  • Цель: менее 500 строк в SKILL.md
  • Тело навыка загружается в контекст при активации
  • Ресурсы загружаются только при явном чтении

По умолчанию используйте один файл SKILL.md. Разделяйте на несколько файлов только если:

  • Тело превышает ~400 строк и имеет явные линии декомпозиции
  • Один и тот же код генерируется каждый раз (вынесите в скрипт)
  • Есть шаблон вывода, который нужно воспроизводить (вынесите в ассет)

Именование​

Правила:

  • Lowercase буквы, цифры, дефисы
  • Максимум 64 символа
  • Без зарезервированных слов (anthropic, claude)
  • Предпочтительно герундий (processing-pdfs, analyzing-spreadsheets)
  • Избегайте vague-имён (helper, utils, tools)

Примеры использования​

Пример 1: Анализ кода​

Пользователь: @skill:code-review проанализируй этот PR

Агент активирует навык code-review, который содержит:
- Чеклист для ревью
- Распространённые уязвимости
- Стилевые соглашения проекта

Пример 2: Работа с API​

Пользователь: Нужно добавить новый endpoint для пользователей

Агент: @skill:api-patterns
Использует навык api-patterns для генерации кода по стандартам проекта

Пример 3: Обработка данных​

Пользователь: @skill:excel-analysis вот файл с продажами

Агент загружает навык и:
1. Читает Excel-файл
2. Создаёт сводные таблицы
3. Генерирует графики

Анти-паттерны​

  • ❌ Размытые описания вроде "Помогает с документами" — не будут надёжно активироваться
  • ❌ Описание от первого лица ("Я могу помочь…") — описание инжектится как контекст, первое лицо ломает discovery
  • ❌ Стены MUST/NEVER в caps — бумага без объяснения причин; перефразируйте и объясните почему
  • ❌ Перечисление всех библиотек — выберите дефолт, упомяните escape hatch один раз
  • ❌ Условия активации только в теле — только frontmatter (description + when-to-use) используется при активации
  • ❌ Преждевременное разделение на файлы — single-file навыки проще поддерживать; разделяйте только когда тело >400 строк