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

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

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

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

• Qwen Code (новая версия)

Как включить

С помощью флага CLI

qwen --experimental-skills

С помощью settings.json

Добавьте в ваш ~/.qwen/settings.json или в файл проекта .qwen/settings.json:

{
  "tools": {
    "experimental": {
      "skills": true
    }
  }
}

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

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

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

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

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

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

/skills <имя-навыка>

Команда /skills доступна только при запуске с флагом --experimental-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.md`:
 
```text
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/
• Навыки расширений: навыки, предоставляемые установленными расширениями

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

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

Навыки расширений автоматически обнаруживаются и загружаются, когда:

• Расширение установлено и включено
• Включён флаг --experimental-skills

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

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

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

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

 
# Список персональных навыков
ls ~/.qwen/skills/
 
# Список навыков проекта (если вы находитесь в каталоге проекта)
ls .qwen/skills/

Просмотр содержимого конкретного навыка

cat ~/.qwen/skills/my-skill/SKILL.md

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

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

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

```text
Можете ли вы помочь мне извлечь текст из этого 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 --experimental-skills --debug

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

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

1. Добавьте навык в .qwen/skills/
2. Зафиксируйте и отправьте изменения
3. Коллеги получают изменения и запускают их с помощью --experimental-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 "Remove unused Skill"

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

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

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

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

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

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

description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or .xlsx data.

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

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