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

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

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

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

Qwen Code (новая версия)
Базовое знакомство с Qwen Code (Быстрый старт)

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

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

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

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

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


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

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

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

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

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

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

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

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


mkdir -p ~/.qwen/skills/название-моего-навыка

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

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

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

Навыки проекта доступны для вашей команды. Сохраните их в папке .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

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

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

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

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


qwen --debug

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

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

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


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”
Слишком общий: “Обработка документов” (разделите на более мелкие навыки)

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

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


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

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

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