Skip to Content
Руководство для пользователейВозможностиНавыки

Agent Skills

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

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

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

Что такое 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: Brief description of what this Skill does and when to use it
---
 
# Your Skill Name
 
## Instructions
Provide clear, step-by-step guidance for Qwen Code.
 
## Examples
Show concrete examples of using this Skill.

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

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

  • name — непустая строка, соответствующая регулярному выражению /^[\p{L}\p{N}_:.-]+$/u — буквы и цифры Unicode (CJK / кириллица / латиница с диакритикой допустимы), а также _, :, ., -. Пробелы, слеши, скобки и другие структурно небезопасные символы отклоняются на этапе парсинга.
  • description — непустая строка

Рекомендуемые соглашения:

  • Для имен, предназначенных для общего доступа, предпочтительны строчные символы ASCII с дефисами (например, tsx-helper)
  • Делайте description конкретным: указывайте, что делает Skill и когда его использовать (ключевые слова, которые пользователи будут естественно упоминать)

Опционально: ограничение Skill по путям к файлам (paths:)

Для Skills, которые актуальны только для определенных частей кодовой базы, добавьте список glob-паттернов в paths:. Skill не будет отображаться в списке доступных навыков модели, пока вызов инструмента не затронет соответствующий файл:

---
name: tsx-helper
description: React TSX component helper
paths:
  - 'src/**/*.tsx'
  - 'packages/*/src/**/*.tsx'
---

Примечания:

  • Glob-паттерны сопоставляются относительно корня проекта с помощью picomatch ; файлы за пределами корня проекта никогда не активируют Skill.
  • Ограниченный по пути Skill остается активным до конца сессии после обращения к соответствующему файлу. Новая сессия или refreshCache, вызванный редактированием любого файла Skill, сбрасывает активации.
  • paths: ограничивает обнаружение только моделью и только на уровне списка SkillTool. Вы всегда можете самостоятельно вызвать ограниченный по пути Skill через /<skill-name> или меню /skills — этот пользовательский путь запускает тело Skill независимо от состояния активации. Однако со стороны модели ограничение сохраняется до обращения к соответствующему файлу: вызов через слэш не разблокирует активацию на стороне модели, поэтому если вы хотите, чтобы модель продолжила цепочку после вашего вызова (сама вызвала Skill { skill: ... }), сначала откройте файл, соответствующий paths: этого Skill.
  • Комбинирование paths: с disable-model-invocation: true допустимо, но ограничение не имеет эффекта — 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:

For advanced usage, see [reference.md](reference.md).
 
Run the helper script:
 
```bash
python scripts/helper.py input.txt
```

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

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

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

Extension Skills

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

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

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

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

What Skills are available?

Обратите внимание — вид модели vs. вид пользователя. Запрос к модели показывает только те Skills, которые модель может видеть в данный момент. Если Skill использует paths: (см. “Опционально: ограничение Skill по путям к файлам” выше), он не появится в этом списке, пока не будет открыт соответствующий файл. Полный набор всегда доступен вам через слэш-команду /skills и в файловой системе.

Или просмотрите полный список с помощью слэш-команды (всегда показывает все Skills, включая ограниченные по пути, которые еще не активированы):

/skills

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

# List personal Skills
ls ~/.qwen/skills/
 
# List project Skills (if in a project directory)
ls .qwen/skills/
 
# View a specific Skill's content
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
# Personal
ls ~/.qwen/skills/my-skill/SKILL.md
 
# Project
ls .qwen/skills/my-skill/SKILL.md

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

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

cat SKILL.md | head -n 15

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

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

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

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

qwen --debug

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

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

  1. Добавьте Skill в .qwen/skills/
  2. Закоммитьте и отправьте изменения (push)
  3. Коллеги забирают изменения (pull)
git add .qwen/skills/
git commit -m "Add team Skill for PDF processing"
git push

Обновление Skill

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

# Personal Skill
code ~/.qwen/skills/my-skill/SKILL.md
 
# Project Skill
code .qwen/skills/my-skill/SKILL.md

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

Удаление Skill

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

# Personal
rm -rf ~/.qwen/skills/my-skill
 
# Project
rm -rf .qwen/skills/my-skill
git commit -m "Remove unused 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 в ожидаемых ситуациях?
  • Понятны ли инструкции?
  • Не упущены ли примеры или граничные случаи?
Last updated on
Арена агентовБезголовый режим