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.

<skill-name> — это всегда зарегистрированное имя Skill. Для Skill из установленного расширения это имя включает владельца — rust:pdf, а не pdf, — поэтому вы вводите /rust:pdf. См. Как именуются Skills расширений.

Преимущества

  • Расширяйте возможности 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 / кириллица / латиница с диакритикой — все подходит), а также _, :, ., -. Пробелы, слеши, скобки и другие структурно небезопасные символы отклоняются на этапе парсинга. Допускаемый : позволяет Skill, зарегистрированному расширением (rust:pdf), и автору, который сам выбирает двоеточие (rust:chat, написанный внутри расширения rust), использовать один шаблон, поэтому двоеточие в зарегистрированном имени не является доказательством владельца — см. Как именуются Skills расширений.
  • 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 будет недоступен через обычные пути вызова пользователем или моделью.

Опционально: детерминированное применение правила (hooks:)

Всё в теле SKILL.md — это инструкция для модели: это текст промпта, поэтому его выполнение зависит от модели. Когда правило должно выполняться независимо от решений модели — отказываться от запуска, если не было внедрено требуемое значение, никогда не касаться защищённого пути — объявите хук во фронтматере вместо этого. Хуки выполняются как код, поэтому они не зависят от сотрудничества модели:

---
name: gated-skill
description: Calls the downstream CLI using a runtime-injected session ID
hooks:
  PreToolUse:
    - matcher: run_shell_command
      hooks:
        - type: command
          command: '"$QWEN_SKILL_ROOT/scripts/gate-session-id.sh"'
---

$QWEN_SKILL_ROOT устанавливается в собственную директорию Skill, поэтому команды хука могут ссылаться на файлы, поставляемые вместе с SKILL.md. Строка команды передаётся оболочке, поэтому сохраняйте внутренние кавычки: без кавычек путь проекта, содержащий пробел, разделится на два слова, и гейт никогда не запустится. Сделайте скрипт исполняемым (chmod +x) тоже. Обе ошибки приводят к fail open одинаковым образом: вызов инструмента продолжается, и ничего не появляется в транскрипте или логе, чтобы сообщить, что гейт не запустился. Хук PreToolUse блокирует вызов инструмента, когда он завершается с кодом 2 (stderr возвращается модели как причина), или когда он выводит hookSpecificOutput.permissionDecision: "deny":

#!/usr/bin/env bash
if [ -z "${DOWNSTREAM_SESSION_ID:-}" ]; then
  echo "Required input DOWNSTREAM_SESSION_ID is not available. Cannot proceed." >&2
  exit 2
fi
exit 0

Примечания:

  • Хуки регистрируются при вызове Skill и действуют до конца сессии. Это верно для обоих путей вызова — вызывает ли модель Skill или вы вводите /<skill-name>.
  • Хуки сессии живут только в памяти, поэтому восстановление сессии с помощью --continue / --resume не восстанавливает их ни на одном пути вызова. Инструкции Skill могут вернуться с воспроизведённым разговором, в то время как хуки, предназначенные для их обеспечения, исчезнут — повторно запустите Skill после восстановления, чтобы снова активировать его гейт.
  • Регистрация идемпотентна: повторный вызов Skill не накапливает дублирующиеся хуки.
  • Всегда указывайте явный matcher: для события инструмента. Пропущенный matcher сохраняется как пустой паттерн, который компилируется в ^$ и не соответствует ни одному имени инструмента — хук регистрируется, но никогда не срабатывает, и ничего не сообщает об этом. Используйте *, если имеете в виду каждый инструмент.
  • command: выполняется через платформенную оболочку: bash на macOS и Linux, а на Windows — Git Bash, если он обнаружен (MSYSTEM/TERM), иначе cmd.exe или PowerShell. Пример выше — это POSIX-оболочка — в cmd.exe $QWEN_SKILL_ROOT не раскрывается, и скрипт .sh не является исполняемым, поэтому гейт открывается там. Хук может установить shell: bash, чтобы принудительно использовать bash, но это разрешается в тот bash, который находится в PATH, поэтому на Windows вне Git Bash напишите гейт для оболочки, которая у вас есть.
  • Сессии, отключающие хуки, не регистрируют ни одного из них — disableAllHooks, безопасный режим и skipHooks ACP-клиента. Тело Skill и его allowedTools по-прежнему применяются в этих сессиях, но его гейт — нет, поэтому правило, для обеспечения которого вы полагаетесь на хук, не обеспечивается там. Bare mode идёт дальше: Skills вообще не обнаруживаются, поэтому нет ни тела, ни allowedTools.
  • Хуки проектного Skill выполняют команды из репозитория, поэтому они регистрируются только в доверенной папке, и доверие перечитывается каждый раз, когда срабатывает хук и каждый раз, когда принимается решение о разрешении. С подключённым IDE-компаньоном это значение живое: отзыв доверия отключает уже зарегистрированный гейт — и приостанавливает allowedTools Skill — при следующем вызове инструмента, без перезапуска. Без подключения к IDE значение фиксируется при запуске CLI, поэтому изменение, сделанное через собственный диалог доверия CLI, вступает в силу при перезапуске. Предоставление доверия никогда не регистрирует задним числом: вызовите Skill снова.
  • hooks: читается для проектных, пользовательских и bundled Skills. Skills, предоставляемые расширениями, не поддерживают это; вместо этого используйте собственные хуки уровня манифеста расширения.
  • См. Hooks для полного списка событий, синтаксиса matcher и формата вывода.

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

Создайте дополнительные файлы вместе с 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 регистрирует Skill из установленного расширения как <extensionName>:<name>, где <extensionName> — это поле name в qwen-extension.json этого расширения, а <name> — собственное поле name во фронтматере Skill. Skill с именем pdf в расширении rust регистрируется как rust:pdf.

Префикс добавляется при загрузке Skill, а не записывается в файл: ваш SKILL.md сохраняет авторское имя, и Qwen Code никогда не восстанавливает авторское имя, разделяя зарегистрированное (автор может законно написать rust:chat внутри rust). Только Skills расширений получают префикс — личные, проектные и bundled Skills сохраняют единое написанное вами имя.

Используйте зарегистрированное имя везде, где вы обращаетесь к Skill:

  • Вызывайте его как /rust:pdf. Простой /pdf — это не алиас — Skill расширения доступен только под своим зарегистрированным именем.
  • Модель вызывает его как Skill { skill: "rust:pdf" }, то же имя, которое она читает в <available_skills>.
  • Два расширения, каждое из которых поставляется со Skill с именем pdf, дают вам два Skills (rust:pdf и docs-suite:pdf), а не один выигрывает и другой исчезает.

Поверхности, где вы читаете и выбираете Skills, также называют владельца: панель Skills (включая строки, заблокированные настройкой), список только для чтения, который печатает простой /skills вне интерактивного UI (ACP и другие неинтерактивные режимы — в интерактивном режиме команда открывает панель), и значок в палитре команд /, который читается как [Extension: Rust], а не просто [Extension]. Эти метки предпочитают displayName расширения и используют name, если displayName не задан.

Extension Skills и настройки skills.*

skills.disabled, skills.defaultDisabled и slashCommands.disabled сопоставляют Skill расширения по обоим написаниям, поэтому skills.disabled: ["pdf"], который вы написали до появления префикса, всё равно скрывает rust:pdf. Ограничение может только удалить возможность (capability), поэтому переименование Skill не может снять ограничение.

skills.enabled — это исключение и единственное видимое изменение для существующего файла настроек: он предоставляет возможность (capability), поэтому сопоставляется только с зарегистрированным именем. skills.enabled: ["pdf"] больше не включает pdf расширения самостоятельно — напишите skills.enabled: ["rust:pdf"]. Единственная пара без префикса, которая продолжает работать, — это включение до префикса в skills.defaultDisabled с тем же написанием: отмена сравнивает сами записи, поэтому defaultDisabled: ["pdf"] + enabled: ["pdf"] отменяет запись — skill затем оказывается включённым согласно хранению enablement для этого рабочего пространства, иначе стандартному значению расширения; для skill, отключённого по умолчанию, напишите rust:pdf в skills.enabled.

Переключение Skill на панели Skills записывает зарегистрированное имя и удаляет только эту запись, поэтому включение rust:pdf оставляет устаревший disabled: ["pdf"] нетронутым. Когда устаревшая запись находится в области более высокого уровня — системные настройки по умолчанию, пользовательские или системные настройки — панель сообщает об этом и блокирует строку, называя область для редактирования, а не предлагая переключатель, который не может её изменить. Устаревшая запись в собственных настройках этого рабочего пространства блокирует строку аналогичным образом, называя запись и её область (skills.disabled 'pdf' (Workspace) или skills.defaultDisabled 'pdf' (Workspace)), чтобы вы знали, какой список в каком файле редактировать.

Два ограничения, о которых стоит знать:

  • Приоритет между уровнями не изменился и по-прежнему сравнивает зарегистрированные имена точно (project > user > extension > bundled), поэтому личный или проектный Skill, который вы назовёте rust:pdf, имеет приоритет над pdf расширения. Коллизии имён без префикса между личным или проектным Skill и bundled Skill по-прежнему разрешаются этим приоритетом, а не префиксом. Skill, который коллидирует с пользовательской командой, — нет: на поверхности слеш-команд последний загрузчик побеждает, а пользовательские команды загружаются после Skills, поэтому /pdf запускает пользовательскую команду, в то время как Skill остаётся доступным для модели.
  • Имена Skills также используются как имена файлов: файл, из которого Skill читает аргументы вызова, заменяет каждый символ вне [A-Za-z0-9._-] на _, поэтому Skill расширения, зарегистрированный как rust:pdf, и личный или проектный Skill с именем rust_pdf оба разрешаются в qwen-skill-args-rust_pdf.txt и используют один файл аргументов. (Префикс редко коллидирует сам с собой — rust:rust_pdf становится rust_rust_pdf — но имена расширений могут содержать _, поэтому rust_pdf:x и rust:pdf_x сворачиваются в одно имя файла.) Не-ASCII буквы сворачиваются так же, поэтому авторское café и авторское caf_ оба становятся caf_ — ограничение, которое предшествует префиксу, который лишь облегчает попадание в него. Избегайте имён Skills, которые являются другим именем с :, заменённым на _.

Чтобы просмотреть доступные 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
Арена агентовПамять