Навыки Агента
Создавайте, управляйте и делитесь Навыками, чтобы расширить возможности Qwen Code.
Это руководство показывает, как создавать, использовать и управлять Навыками Агента в Qwen Code. Навыки — это модульные возможности, которые повышают эффективность модели с помощью организованных папок, содержащих инструкции (и, опционально, скрипты/ресурсы).
Предварительные требования
- Qwen Code (актуальная версия)
- Базовое знакомство с Qwen Code (Быстрый старт)
Что такое Навыки Агента?
Навыки Агента упаковывают экспертизу в обнаруживаемые возможности. Каждый Навык состоит из файла SKILL.md с инструкциями, которые модель может загрузить, когда это уместно, а также дополнительных файлов, таких как скрипты и шаблоны.
Как вызываются Навыки
Навыки вызываются моделью — модель автономно решает, когда их использовать, на основе вашего запроса и описания Навыка. Это отличается от слэш-команд, которые вызываются пользователем (вы явно вводите /команда).
Если вы хотите вызвать Навык явно, используйте слэш-команду /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:)
Для Навыков, которые актуальны только для определённых частей кодовой базы, добавьте список шаблонов glob в paths:. Навык не будет отображаться в списке доступных Навыков для модели до тех пор, пока вызов инструмента не коснётся соответствующего файла:
---
name: tsx-helper
description: Помощник для React TSX компонентов
paths:
- 'src/**/*.tsx'
- 'packages/*/src/**/*.tsx'
---Примечания:
- Glob-шаблоны сопоставляются относительно корня проекта с помощью picomatch ; файлы за пределами корня проекта никогда не вызывают активацию.
- Навык, ограниченный путём, остаётся активированным на всю остальную сессию, как только будет затронут соответствующий файл. Новая сессия или
refreshCache, вызванный редактированием любого файла Навыка, сбрасывает активации. paths:ограничивает только обнаружение моделью, и только на уровне перечня SkillTool. Если не установленоuser-invocable: false, вы всегда можете вызвать ограниченный путём Навык самостоятельно через/<название-навыка>или через выбор/skills— этот пользовательский путь запускает тело Навыка независимо от состояния активации. Однако сторона модели остаётся ограниченной до тех пор, пока не будет затронут соответствующий файл: слэш-инвокация не разблокирует активацию со стороны модели, поэтому если вы хотите, чтобы модель продолжила цепочку на основе вашего вызова (сама вызвалаSkill { skill: ... }), также сначала откройте файл, соответствующийpaths:этого Навыка.- Комбинация
paths:сdisable-model-invocation: trueразрешена, но шлюз не имеет эффекта — Навык в любом случае скрыт от модели, поэтому активация по пути никогда не объявит его.
Опционально: управление вызовом пользователем и моделью
Навыки по умолчанию доступны для вызова пользователем. Чтобы скрыть Навык из прямого вызова через слеш-команду, но оставить доступным для вызова моделью, установите user-invocable: false:
---
name: model-only-helper
description: Helper the model can call when appropriate
user-invocable: false
---Это удаляет Навык из вызова /<skill-name> и из результатов выбора /skills. Это не скрывает Навык от модели.
Чтобы скрыть Навык от вызова моделью, оставив прямой вызов пользователем, установите disable-model-invocation: true:
---
name: manual-helper
description: Helper you invoke manually
disable-model-invocation: true
---Можно комбинировать оба поля, но тогда Навык становится недоступным ни через обычный вызов пользователем, ни через вызов моделью.
Добавление вспомогательных файлов
Создайте дополнительные файлы рядом с SKILL.md:
my-skill/
├── SKILL.md (обязательно)
├── reference.md (опциональная документация)
├── examples.md (опциональные примеры)
├── scripts/
│ └── helper.py (опциональная утилита)
└── templates/
└── template.txt (опциональный шаблон)Ссылайтесь на эти файлы из SKILL.md:
For advanced usage, see [reference.md](reference.md).
Run the helper script:
```bash
python scripts/helper.py input.txt
```Просмотр доступных Навыков
Qwen Code обнаруживает Навыки из:
- Личные Навыки:
~/.qwen/skills/ - Проектные Навыки:
.qwen/skills/ - Навыки расширений: Навыки, предоставляемые установленными расширениями
Навыки расширений
Расширения могут предоставлять пользовательские навыки, которые становятся доступными при включении расширения. Эти навыки хранятся в каталоге skills/ расширения и соответствуют тому же формату, что и личные и проектные навыки.
Навыки расширений автоматически обнаруживаются и загружаются, когда расширение установлено и включено.
Чтобы узнать, какие расширения предоставляют навыки, проверьте поле skills в файле qwen-extension.json расширения.
Чтобы просмотреть доступные Навыки, спросите напрямую у Qwen Code:
Какие Навыки доступны?Внимание — представление модели и пользователя. Запрос к модели показывает только те Навыки, которые модель может видеть в данный момент. Если у Навыка указаны
paths:(см. «Опционально: доступ к Навыку по путям файлов» выше), он не отображается в этом списке, пока не будет затронут соответствующий файл. Слеш-команда/skillsпоказывает Навыки, которые вы можете вызвать напрямую; Навыки сuser-invocable: falseостаются видимыми на диске и могут по-прежнему быть видны модели.
Или просмотрите список вызываемых пользователем команд через слеш-команду (включая Навыки, ограниченные по путям, которые ещё не активированы):
/skillsИли проверьте файловую систему:
# Список личных Навыков
ls ~/.qwen/skills/
# Список проектных Навыков (если находитесь в каталоге проекта)
ls .qwen/skills/
# Просмотр содержимого конкретного Навыка
cat ~/.qwen/skills/my-skill/SKILL.mdТестирование Навыка
После создания Навыка протестируйте его, задавая вопросы, соответствующие вашему описанию.
Пример: если в вашем описании упоминаются «PDF-файлы»:
Можете помочь извлечь текст из этого PDF?Модель автономно решает использовать ваш Навык, если он соответствует запросу — вам не нужно вызывать его явно.
Отладка Навыка
Если Qwen Code не использует ваш Навык, проверьте следующие типичные проблемы:
Сделайте описание конкретным
Слишком размыто:
description: Helps with documentsКонкретно:
description: Извлекать текст и таблицы из PDF-файлов, заполнять формы, объединять документы. Использовать при работе с PDF, формами или извлечением документов.Проверьте путь к файлу
- Личные Навыки:
~/.qwen/skills/<skill-name>/SKILL.md - Проектные Навыки:
.qwen/skills/<skill-name>/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/ - Зафиксируйте и отправьте изменения
- Участники команды получают изменения при 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»
- Слишком широко: «Обработка документов» (разбейте на более мелкие Навыки)
Пишите четкие описания
Помогите модели понять, когда использовать навыки, добавляя конкретные триггеры:
description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or .xlsx data.Тестируйте с командой
- Активируется ли навык, когда ожидается?
- Понятны ли инструкции?
- Нет ли недостающих примеров или граничных случаев?