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

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.

Создание проектного Skill с помощью /learn

Используйте /learn, чтобы извлечь существующий источник знаний в переиспользуемый проектный Skill:

/learn https://docs.example.com/api
/learn ~/projects/acme-sdk
/learn Our deploy process: run migrate, deploy the service, then check health

Команда выполняется как обычный ход агента и создаёт результат в .qwen/skills/learned-skill-<name>/SKILL.md с source: learned в фронтматере. Проверьте сгенерированные инструкции перед использованием или публикацией.

/learn также принимает локальные или прямые ссылки на видео .mp4, .webm, .mov и .m4v. Добавьте текст после пути или URL, чтобы сфокусировать сгенерированный Skill на одной части туториала:

/learn ./tutorial.mp4 focus on the deployment workflow

Для обучения по видео требуется модель с поддержкой видео у OpenAI-совместимого провайдера. URL-адреса страниц YouTube не являются прямым видео-вводом; скачайте видео в рабочее пространство и передайте его локальный путь вместо этого.

Личные 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, и они автоматически станут доступны участникам команды.

Поддержка автогенерированных проектных Skills

Qwen Code отслеживает успешное использование сгенерированных проектных Skills локально, в том числе когда генерация новых Auto Skill отключена, чтобы при повторном включении обслуживания недавно использованный skill не был ошибочно принят за неактивный. Когда Auto Skill включён, он периодически перемещает неактивные сгенерированные Skills из активной библиотеки. Управляются только директории с именем .qwen/skills/auto-skill-*, чей фронтматер SKILL.md содержит source: auto-skill; личные, расширения, bundled и написанные вручную Skills никогда не выбираются.

  • Через 30 дней без успешного использования или редактирования SKILL.md auto-skill помечается как устаревший.
  • Через 90 дней его полная директория перемещается в .qwen/archived-skills/. Ничего не удаляется безвозвратно.
  • Автоматическое обслуживание запускается не чаще одного раза в 7 дней в доверенных рабочих пространствах. Каждый вновь обнаруженный auto-skill получает полный льготный период до начала обслуживания.
  • Закреплённый auto-skill исключается из автоматических переходов в устаревшее состояние и архивирование до тех пор, пока не будет откреплён.
  • Имена архивных директорий остаются зарезервированными, и существующий адресат архива пропускает только это совпадение, а не останавливает обслуживание для других skills.

Используйте /curator, чтобы увидеть активные, устаревшие, архивные и закреплённые auto-skills. Выполните /curator run --dry-run для предварительного просмотра обслуживания, /curator run для его немедленного применения, /curator pin <directory> или /curator unpin <directory> для управления обслуживанием каждого skill, или /curator restore <directory> для перемещения архивного auto-skill обратно в активную библиотеку.

Статус и предварительный просмотр dry-run доступны в safe mode и недоверенных рабочих пространствах. Применение обслуживания, изменение закрепления и восстановление архивных auto-skills требуют доверенного рабочего пространства вне safe mode.

Написание 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, предоставляемые установленными расширениями
  • Bundled Skills: Skills, поставляемые вместе с Qwen Code

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 отслеживает директории личных и проектных Skills. Добавление, редактирование или удаление Skill автоматически обновляет список Skills и состояние вызова через короткую задержку. Bare mode не запускает эти наблюдатели, поэтому перезапустите Qwen Code, чтобы загрузить изменения Skills в этом режиме.

Удаление 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, когда ожидается?
  • Понятны ли инструкции?
  • Не хватает ли примеров или граничных случаев?
Last updated on
Арена агентовБезголовый режим