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

Навыки агента (Agent Skills)

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

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

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

Что такое навыки агента (Agent Skills)?

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

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

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

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

/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: Краткое описание того, что делает этот навык и когда его использовать
priority: 10
---
 
# Имя вашего навыка
 
## Инструкции
Предоставьте четкие пошаговые инструкции для Qwen Code.
 
## Примеры
Покажите конкретные примеры использования этого навыка.

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

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

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

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

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

Опционально: привязка навыка к путям файлов (paths:)

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

---
name: tsx-helper
description: Помощник для React TSX компонентов
paths:
  - 'src/**/*.tsx'
  - 'packages/*/src/**/*.tsx'
---

Примечания:

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

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

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

---
name: model-only-helper
description: Помощник, который модель может вызывать, когда это уместно
user-invocable: false
---

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

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

---
name: manual-helper
description: Помощник, который вы вызываете вручную
disable-model-invocation: true
---

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

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

Создайте дополнительные файлы рядом с 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
```

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

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

  • Личные навыки: ~/.qwen/skills/
  • Навыки проекта: .qwen/skills/
  • Навыки расширений: навыки, предоставляемые установленными расширениями

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

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

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

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

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

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

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

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

/skills

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

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

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

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

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

Не могли бы вы помочь мне извлечь текст из этого 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 --debug

Обмен навыками с командой

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

  1. Добавьте навык в .qwen/skills/
  2. Зафиксируйте и отправьте изменения (commit & push)
  3. Коллеги получают изменения при pull
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 "Удалить неиспользуемый навык"

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

Держите навыки сфокусированными

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

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

Пишите четкие описания

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

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

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

  • Активируется ли навык, когда ожидается?
  • Понятны ли инструкции?
  • Нет ли недостающих примеров или крайних случаев?
Last updated on
Арена агентовБезголовый режим