Agent Skills

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

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

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

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

Что такое Agent Skills?

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

Как вызываются Skills

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

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


/skills <skill-name>

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

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

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

Создание Skill

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

Персональные Skills

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


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

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

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

Проектные Skills

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


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

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

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

Проектные Skills можно закоммитить в git, и они автоматически станут доступны коллегам по команде.

Написание `SKILL.md`

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


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

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

В настоящее время Qwen Code проверяет, что:

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

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

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

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

Создайте дополнительные файлы рядом с SKILL.md:


my-skill/
├── SKILL.md (required)
├── reference.md (optional documentation)
├── examples.md (optional examples)
├── scripts/
│   └── helper.py (optional utility)
└── templates/
    └── template.txt (optional template)

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


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

Просмотр доступных Skills

Qwen Code обнаруживает Skills из:

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

Skills расширений

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

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

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

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


What Skills are available?

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


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

Тестирование Skill

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

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


Can you help me extract text from this PDF?

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

Отладка Skill

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

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

Слишком размыто:


description: Helps with documents

Конкретно:


description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDFs, forms, or document extraction.

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

Персональные Skills: ~/.qwen/skills/<skill-name>/SKILL.md
Проектные Skills: .qwen/skills/<skill-name>/SKILL.md


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

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

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


cat SKILL.md | head -n 15

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

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

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

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


qwen --debug

Обмен Skills с командой

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

Добавьте Skill в .qwen/skills/
Закоммитьте и отправьте изменения (push)
Коллеги по команде забирают изменения (pull)


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

Обновление Skill

Отредактируйте SKILL.md напрямую:


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

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

Удаление Skill

Удалите директорию Skill:


# Персональный
rm -rf ~/.qwen/skills/my-skill
 
# Проектный
rm -rf .qwen/skills/my-skill
git commit -m "Удален неиспользуемый Skill"

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

Сохраняйте фокус Skills

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

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

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

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


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

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

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