Agent Skills

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

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

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

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

Что такое Agent Skills?

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

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

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

Если вы хотите явно вызвать Skill, введите его как slash-команду, используя имя Skill:

/<skill-name>

Начните вводить /, чтобы использовать автодополнение и просматривать доступные Skills вместе с их описаниями. Команда /skills открывает панель Skills, где можно интерактивно просматривать, искать, включать и запускать Skills.

Примечание: Если ранее вы запускали Skill с помощью /skills <skill-name>, теперь этот синтаксис просто открывает панель Skills и игнорирует конечный аргумент. Используйте /<skill-name> для прямого запуска Skill.

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

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

---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
priority: 10
---
 
# 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 — непустая строка
• priority — необязательное поле. Если указано, это должно быть конечное число. Более высокие значения сортируются раньше только в списке /skills — автодополнение slash-команд (ввод /) и просмотр пользовательских команд через /help остаются в алфавитном порядке, поэтому Skill с высоким приоритетом никогда не меняет порядок встроенных команд. Пропущенные или недействительные значения считаются незаданными, что эквивалентно 0.

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

• Предпочитайте нижний регистр ASCII с дефисами для имен, которыми можно делиться (например, tsx-helper)
• Делайте description конкретным: укажите как что делает Skill, так и когда его использовать (ключевые слова, которые пользователи будут естественно упоминать)
• Используйте priority экономно для Skills, которые должны надежно появляться перед стандартным алфавитным порядком в /skills. Отрицательные приоритеты разрешены и сортируются ниже незаданных Skills.

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

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

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

Примечания:

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

Опционально: управление вызовом пользователем и моделью

По умолчанию Skills доступны для вызова пользователем. Чтобы скрыть Skill от прямого использования через slash-команды, но оставить его доступным для вызова моделью, установите user-invocable: false:

---
name: model-only-helper
description: Helper the model can call when appropriate
user-invocable: false
---

Это удаляет Skill из вызова через /<skill-name> и результатов селектора /skills. Это не скрывает Skill от модели.

Чтобы скрыть Skill от вызова моделью, но оставить доступным для прямого вызова пользователем, установите disable-model-invocation: true:

---
name: manual-helper
description: Helper you invoke manually
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/
• Расширений Skills: Skills, предоставляемые установленными расширениями

Skills расширений

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

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

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

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

What Skills are available?

Внимание — представление модели и пользователя. Запрос к модели показывает только те Skills, которые модель может видеть в данный момент. Если Skill использует paths: (см. «Опционально: ограничение Skill путями к файлам» выше), он не будет в этом списке, пока не будет затронут соответствующий файл. Slash-команда /skills показывает Skills, которые вы можете вызвать напрямую; Skills с user-invocable: false остаются видимыми на диске и могут быть по-прежнему видимы для модели.

Или просмотрите список, доступный для вызова пользователем, с помощью slash-команды (включая 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 в режиме отладки, чтобы увидеть ошибки загрузки Skills:

qwen --debug

Поделиться Skills с командой

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

1. Добавьте Skill в .qwen/skills/
2. Закоммитьте и запушьте
3. Участники команды пуллят изменения

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 commit-сообщения»
• Слишком широкие: «Обработка документов» (разбейте на более мелкие Skills)

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

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

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

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

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