Навыки агента

Создавайте, управляйте и делитесь навыками для расширения возможностей Qwen Code.

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

Предварительные требования

Qwen Code (актуальная версия)
Базовое знакомство с Qwen Code (Краткое руководство)

Что такое навыки агента?

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

Как вызываются навыки

Навыки вызываются моделью — модель самостоятельно решает, когда их использовать, исходя из вашего запроса и описания навыка. Это отличается от команд с косой чертой, которые вызываются пользователем (вы явно вводите /command).

Если вы хотите вызвать навык явно, используйте команду с косой чертой /skills:


/skills <название-навыка>

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

Преимущества

Расширение возможностей Qwen Code для ваших рабочих процессов
Совместное использование экспертизы в команде через Git
Снижение количества повторяющихся запросов
Комбинирование нескольких навыков для выполнения сложных задач

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

Навыки хранятся в виде каталогов, содержащих файл SKILL.md.

Персональные навыки

Персональные навыки доступны во всех ваших проектах. Храните их в каталоге ~/.qwen/skills/:


mkdir -p ~/.qwen/skills/my-skill-name

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

Индивидуальных рабочих процессов и предпочтений
Разработки новых навыков
Персональных инструментов повышения продуктивности

Навыки проекта

Навыки проекта доступны всей команде. Храните их в каталоге .qwen/skills/ внутри вашего проекта:


mkdir -p .qwen/skills/my-skill-name

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

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

Навыки проекта можно добавить в Git — они автоматически станут доступны коллегам.

Создайте файл `SKILL.md`

Создайте файл SKILL.md с YAML-фронтматтером и содержимым в формате Markdown:


---
name: your-skill-name
description: Краткое описание того, что делает этот навык и когда его следует использовать
---
 
# Название вашего навыка
 
## Инструкции
Предоставьте чёткие пошаговые инструкции для Qwen Code.
 
## Примеры
Приведите конкретные примеры использования этого навыка.

Требования к полям

В настоящее время Qwen Code проверяет следующие условия:

name — непустая строка
description — непустая строка

Рекомендуемые соглашения (пока не являются строгими требованиями):

В значении name используйте строчные буквы, цифры и дефисы.
В значении description указывайте конкретную информацию: опишите что делает Skill и когда его следует использовать (включите ключевые слова, которые пользователи естественным образом упомянут при поиске).

Добавьте вспомогательные файлы

Создайте дополнительные файлы в той же директории, что и SKILL.md:


my-skill/
├── SKILL.md (обязательный)
├── reference.md (дополнительная документация, необязательно)
├── examples.md (примеры использования, необязательно)
├── scripts/
│   └── helper.py (вспомогательный утилитарный скрипт, необязательно)
└── templates/
    └── template.txt (шаблон, необязательно)

Ссылайтесь на эти файлы из SKILL.md:


Для расширенного использования см. [reference.md](reference.md).
 
Запустите вспомогательный скрипт:
 
```bash
python scripts/helper.py input.txt
```

Просмотр доступных навыков

Qwen Code обнаруживает навыки в следующих местах:

Персональные навыки: ~/.qwen/skills/
Навыки проекта: .qwen/skills/
Навыки расширений: навыки, предоставляемые установленными расширениями

Навыки расширений

Расширения могут предоставлять пользовательские навыки, которые становятся доступными после включения расширения. Эти навыки хранятся в каталоге skills/ расширения и имеют тот же формат, что и персональные и проектные навыки.

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

Чтобы узнать, какие расширения предоставляют навыки, проверьте файл qwen-extension.json расширения на наличие поля skills.

Чтобы просмотреть доступные навыки, задайте вопрос напрямую Qwen Code:


Какие навыки доступны?

Или изучите файловую систему:


# Список персональных навыков
ls ~/.qwen/skills/
 
# Список навыков проекта (если вы находитесь в каталоге проекта)
ls .qwen/skills/
 
# Просмотр содержимого конкретного навыка
cat ~/.qwen/skills/my-skill/SKILL.md

Тестирование навыка

После создания навыка протестируйте его, задав вопросы, соответствующие вашему описанию.

Пример: если в описании упоминаются «PDF-файлы»:


Можете ли вы помочь мне извлечь текст из этого PDF?

Модель самостоятельно решает использовать ваш навык, если запрос ей соответствует. Явно вызывать навык не требуется.

Отладка навыка

Если Qwen Code не использует ваш навык, проверьте следующие распространённые проблемы:

Сделайте описание более конкретным

Слишком расплывчатое:


description: Помощь с документами

Конкретное:


description: Извлечение текста и таблиц из PDF-файлов, заполнение форм, объединение документов. Используйте при работе с PDF, формами или извлечением данных из документов.

Проверьте путь к файлу

Персональные навыки: ~/.qwen/skills/<название-навыка>/SKILL.md
Навыки проекта: .qwen/skills/<название-навыка>/SKILL.md


 
# Персональные
ls ~/.qwen/skills/my-skill/SKILL.md
 
# Проектные
ls .qwen/skills/my-skill/SKILL.md

Проверка синтаксиса YAML

Некорректный YAML препятствует правильной загрузке метаданных навыка.


cat SKILL.md | head -n 15

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

Открывающие --- находятся на первой строке;
Закрывающие --- расположены перед содержимым Markdown;
Синтаксис YAML корректен (отсутствуют символы табуляции, соблюдена правильная вложенность).

Просмотр ошибок

Запустите Qwen Code в режиме отладки, чтобы увидеть ошибки загрузки навыков:


qwen --debug

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

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

Добавьте навык в каталог .qwen/skills/.
Зафиксируйте изменения и отправьте их в удалённый репозиторий.
Коллеги получат обновления при выполнении git pull.


git add .qwen/skills/
git commit -m "Добавлен командный навык для обработки PDF"
git push

Обновление навыка

Измените файл SKILL.md напрямую:


 
# Персональный навык
code ~/.qwen/skills/my-skill/SKILL.md
 
# Навык проекта
code .qwen/skills/my-skill/SKILL.md

Изменения вступят в силу при следующем запуске Qwen Code. Если Qwen Code уже запущен, перезапустите его, чтобы применить обновления.

Удаление навыка

Удалите каталог навыка:

Персонально

rm -rf ~/.qwen/skills/my-skill

Проект

rm -rf .qwen/skills/my-skill git commit -m “Удаление неиспользуемого навыка”



## Рекомендации

### Сосредоточьте каждый навык на одной задаче

Один навык должен решать одну конкретную задачу:

- Узконаправленный: «Заполнение PDF-форм», «Анализ Excel», «Создание сообщений коммитов Git»
- Слишком общий: «Обработка документов» (разделите его на более мелкие навыки)

### Пишите понятные описания

Помогите модели определить, когда следует использовать навык, указав в описании конкретные триггеры:

```yaml
description: Анализ таблиц Excel, создание сводных таблиц и генерация диаграмм. Используйте при работе с файлами Excel, электронными таблицами или данными в формате .xlsx.

Тестируйте навык вместе с командой

Активируется ли навык в ожидаемых ситуациях?
Понятны ли инструкции?
Есть ли пропущенные примеры или граничные случаи?