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

Навыки Агента

Создавайте, управляйте и делитесь Навыками, чтобы расширить возможности 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

Поделиться Навыками с командой

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

  1. Добавьте Навык в .qwen/skills/
  2. Зафиксируйте и отправьте изменения
  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»
  • Слишком широко: «Обработка документов» (разбейте на более мелкие Навыки)

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

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

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

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

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