Навыки агента (Agent Skills)
Создавайте, управляйте навыками и делитесь ими, чтобы расширить возможности Qwen Code.
Это руководство покажет вам, как создавать, использовать и управлять навыками агента (Agent Skills) в Qwen Code. Навыки — это модульные возможности, расширяющие эффективность модели с помощью организованных папок, содержащих инструкции (и, опционально, скрипты/ресурсы).
Предварительные требования
- Qwen Code (последняя версия)
- Базовое знакомство с 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Обмен навыками с командой
Вы можете делиться навыками через репозитории проектов:
- Добавьте навык в
.qwen/skills/ - Зафиксируйте и отправьте изменения (commit & push)
- Коллеги получают изменения при 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.Тестируйте с командой
- Активируется ли навык, когда ожидается?
- Понятны ли инструкции?
- Нет ли недостающих примеров или крайних случаев?