Навыки агента (экспериментальная функция)

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

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

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

• Qwen Code (последняя версия)
• Запуск с включенным экспериментальным флагом:

qwen --experimental-skills

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

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

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

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

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

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

• Расширение возможностей 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
```

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

Когда включена опция --experimental-skills, Qwen Code обнаруживает навыки из:

• Персональные навыки: ~/.qwen/skills/
• Навыки проекта: .qwen/skills/

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

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

Или проверьте файловую систему:

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

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

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

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

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

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

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

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

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

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

description: Helps with documents

Конкретно:

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

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

• Персональные навыки: ~/.qwen/skills/<skill-name>/SKILL.md
• Навыки проекта: .qwen/skills/<skill-name>/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 --experimental-skills --debug

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

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

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

git add .qwen/skills/
git commit -m "Add team Skill for PDF processing"
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 "Remove unused Skill"

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

Сосредоточьтесь на конкретных навыках

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

• Узконаправленный: “заполнение PDF-форм”, “анализ Excel”, “сообщения коммитов Git”
• Слишком общий: “обработка документов” (разделите на более мелкие навыки)

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

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

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

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

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