Agent Skills

Crie, gerencie e compartilhe Skills para estender as capacidades do Qwen Code.

Este guia mostra como criar, usar e gerenciar Agent Skills no Qwen Code. Skills são capacidades modulares que estendem a eficácia do modelo por meio de pastas organizadas contendo instruções (e, opcionalmente, scripts/recursos).

Pré-requisitos

Qwen Code (versão recente)
Familiaridade básica com o Qwen Code (Quickstart)

O que são Agent Skills?

Agent Skills empacotam conhecimento em capacidades descobríveis. Cada Skill consiste em um arquivo SKILL.md com instruções que o modelo pode carregar quando relevante, além de arquivos de suporte opcionais, como scripts e templates.

Como as Skills são invocadas

As Skills são invocadas pelo modelo — o modelo decide autonomamente quando usá-las com base na sua solicitação e na descrição da Skill. Isso é diferente dos slash commands, que são invocados pelo usuário (você digita explicitamente /command).

Se você quiser invocar uma Skill explicitamente, digite-a como um slash command usando o nome da Skill:


/<skill-name>

<skill-name> é sempre o nome registrado da Skill. Para uma Skill de uma extensão instalada, esse nome carrega seu owner — rust:pdf, não pdf — então você digita /rust:pdf. Consulte Como as Skills de extensão são nomeadas.

Comece a digitar / para autocompletar e navegar pelas Skills disponíveis junto com suas descrições. O comando /skills abre o painel de Skills, onde você pode navegar, pesquisar, alternar e executar Skills de forma interativa.

Nota: Se você executou anteriormente uma Skill com /skills <skill-name>, essa sintaxe agora apenas abre o painel de Skills e ignora o argumento final. Use /<skill-name> para executar uma Skill diretamente.

Benefícios

Estenda o Qwen Code para seus fluxos de trabalho
Compartilhe conhecimento com sua equipe via git
Reduza prompts repetitivos
Componha múltiplas Skills para tarefas complexas

Criar uma Skill

As Skills são armazenadas como diretórios contendo um arquivo SKILL.md.

Gerar uma Skill de projeto com `/learn`

Use /learn para destilar uma fonte de conhecimento existente em uma Skill reutilizável de projeto:


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

O comando é executado como um turno normal do agente e cria o resultado em .qwen/skills/learned-skill-<name>/SKILL.md com source: learned no seu frontmatter. Revise as instruções geradas antes de usá-las ou compartilhá-las.

O /learn também aceita vídeos .mp4, .webm, .mov e .m4v locais ou de link direto. Adicione texto após o caminho ou URL para focar a Skill gerada em uma parte do tutorial:


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

O aprendizado de vídeo requer um modelo compatível com vídeo em um provedor compatível com OpenAI. URLs de página do YouTube não são entrada de vídeo direta; baixe o vídeo para o workspace e passe seu caminho local.

Skills Pessoais

As Skills pessoais estão disponíveis em todos os seus projetos. Armazene-as em ~/.qwen/skills/:


mkdir -p ~/.qwen/skills/my-skill-name

Use Skills pessoais para:

Seus fluxos de trabalho e preferências individuais
Skills que você está desenvolvendo
Ajudantes de produtividade pessoal

Skills de Projeto

As Skills de projeto são compartilhadas com sua equipe. Armazene-as em .qwen/skills/ dentro do seu projeto:


mkdir -p .qwen/skills/my-skill-name

Use Skills de projeto para:

Fluxos de trabalho e convenções da equipe
Conhecimento específico do projeto
Utilitários e scripts compartilhados

As Skills de projeto podem ser adicionadas ao git e ficam automaticamente disponíveis para os colegas de equipe.

Manter Skills de projeto geradas automaticamente

O Qwen Code rastreia localmente o uso bem-sucedido de Skills de projeto geradas, inclusive enquanto a geração de Auto Skill está desabilitada, para que a reativação da manutenção não confunda uma skill usada recentemente com uma inativa. Quando o Auto Skill está habilitado, ele move periodicamente Skills geradas inativas para fora da biblioteca ativa. Apenas diretórios chamados .qwen/skills/auto-skill-* cujo frontmatter do SKILL.md contém source: auto-skill são gerenciados; Skills pessoais, de extensão, integradas e escritas manualmente nunca são selecionadas.

Após 30 dias sem uso bem-sucedido ou edição do SKILL.md, uma auto-skill é marcada como obsoleta.
Após 90 dias, seu diretório completo é movido para .qwen/archived-skills/. Nada é excluído permanentemente.
A manutenção automática é executada no máximo uma vez a cada 7 dias em workspaces confiáveis. Cada auto-skill recém-observada recebe um período de carência completo antes da manutenção começar.
Uma auto-skill fixada é excluída das transições automáticas de obsolescência e arquivamento até ser desafixada.
Nomes de diretório arquivados permanecem reservados, e um destino de arquivo existente ignora apenas essa colisão em vez de parar a manutenção para outras skills.

Use /curator para ver auto-skills ativas, obsoletas, arquivadas e fixadas. Execute /curator run --dry-run para visualizar uma passagem de manutenção, /curator run para aplicá-la imediatamente, /curator pin <directory> ou /curator unpin <directory> para controlar a manutenção por skill, ou /curator restore <directory> para mover uma auto-skill arquivada de volta à biblioteca ativa.

O status e as pré-visualizações dry-run estão disponíveis em modo seguro e workspaces não confiáveis. Aplicar manutenção, alterar fixações e restaurar auto-skills arquivadas requerem um workspace confiável fora do modo seguro.

Escrever o SKILL.md

Crie um arquivo SKILL.md com frontmatter YAML e conteúdo 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.

Requisitos dos campos

O Qwen Code atualmente valida que:

name é uma string não vazia que corresponde a /^[\p{L}\p{N}_:.-]+$/u — letras e dígitos Unicode (CJK / cirílico / latim acentuado, tudo OK), além de _, :, ., -. Espaços em branco, barras, colchetes e outros caracteres estruturalmente inseguros são rejeitados no momento do parse. O : admitido é o que permite que uma Skill registrada por uma extensão (rust:pdf) e um autor que escolha um colon por conta própria (rust:chat, escrito dentro da extensão rust) compartilhem um padrão, então um colon em um nome registrado não é prova de um owner — consulte Como as Skills de extensão são nomeadas.
description é uma string não vazia
priority é opcional. Quando presente, deve ser um número finito. Valores mais altos são ordenados primeiro apenas na listagem de /skills — o autocompletar de slash commands (digitar /) e a visualização de comandos personalizados /help permanecem em ordem alfabética, então uma Skill de alta prioridade nunca reordena comandos integrados. Valores omitidos ou inválidos são tratados como não definidos, o que se comporta como 0.

Convenções recomendadas:

Prefira ASCII minúsculo com hífens para nomes compartilháveis (por exemplo, tsx-helper)
Torne a description específica: inclua tanto o que a Skill faz quanto quando usá-la (palavras-chave que os usuários mencionarão naturalmente)
Use priority com moderação para Skills que devem aparecer de forma confiável antes da ordem alfabética padrão em /skills. Prioridades negativas são permitidas e são ordenadas abaixo de Skills não definidas.

Opcional: restringir uma Skill a caminhos de arquivo (`paths:`)

Para Skills que são relevantes apenas para partes específicas de uma base de código, adicione uma lista paths: de padrões glob. A Skill permanece fora da listagem de Skills disponíveis do modelo até que uma chamada de ferramenta acesse um arquivo correspondente:


---
name: tsx-helper
description: React TSX component helper
paths:
  - 'src/**/*.tsx'
  - 'packages/*/src/**/*.tsx'
---

Observações:

Os globs são correspondidos em relação à raiz do projeto com picomatch ; arquivos fora da raiz do projeto nunca acionam a ativação.
Uma Skill restrita por caminho permanece ativada pelo resto da sessão assim que um arquivo correspondente é acessado. Uma nova sessão ou um refreshCache acionado pela edição de qualquer arquivo de Skill redefine as ativações.
paths: restringe apenas a descoberta pelo modelo, e apenas no nível de listagem do SkillTool. A menos que user-invocable: false esteja definido, você sempre pode invocar uma Skill restrita por caminho por conta própria via /<skill-name> ou o seletor /skills — esse caminho do usuário executa o corpo da Skill independentemente do estado de ativação. O lado do modelo, no entanto, permanece restrito até que um arquivo correspondente seja acessado: uma invocação por slash não desbloqueia a ativação do lado do modelo, então se você quiser que o modelo encadeie a partir da sua invocação (chamar Skill { skill: ... } por conta própria), acesse também um arquivo que corresponda ao paths: da Skill primeiro.
Combinar paths: com disable-model-invocation: true é permitido, mas a restrição não tem efeito — a Skill fica oculta do modelo de qualquer forma, então a ativação por caminho nunca a divulga.

Opcional: controlar a invocação pelo usuário e pelo modelo

As Skills são invocáveis pelo usuário por padrão. Para ocultar uma Skill do uso direto por slash command, mantendo-a disponível para invocação pelo modelo, defina user-invocable: false:


---
name: model-only-helper
description: Helper the model can call when appropriate
user-invocable: false
---

Isso remove a Skill da invocação /<skill-name> e dos resultados do seletor /skills. Não oculta a Skill do modelo.

Para ocultar uma Skill da invocação pelo modelo, mantendo a invocação direta pelo usuário disponível, defina disable-model-invocation: true:


---
name: manual-helper
description: Helper you invoke manually
disable-model-invocation: true
---

Você pode combinar ambos os campos, mas então a Skill não será acessível através dos caminhos normais de invocação pelo usuário ou pelo modelo.

Opcional: impor uma regra deterministicamente (`hooks:`)

Tudo no corpo de um SKILL.md é uma instrução para o modelo: é texto de prompt, então segui-lo depende do modelo. Quando uma regra deve ser respeitada independentemente do que o modelo decida — recusar executar a menos que um valor obrigatório tenha sido injetado, nunca alterar um caminho protegido — declare um hook no frontmatter. Hooks são executados como código, portanto não dependem da cooperação do modelo:


---
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 é definido como o diretório da própria Skill, então os comandos do hook podem referenciar arquivos enviados junto com o SKILL.md. A string do comando é passada para um shell, então mantenha as aspas internas: sem aspas, um caminho de projeto contendo um espaço se divide em duas palavras e o gate nunca é executado. Torne o script executável (chmod +x) também. Ambos os erros resultam em fail-open da mesma forma: a chamada de ferramenta prossegue, e nada aparece na transcrição ou no log indicando que o gate não foi executado. Um hook PreToolUse bloqueia a chamada de ferramenta quando sai com código 2 (stderr é devolvido ao modelo como motivo), ou quando imprime 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

Observações:

Os hooks são registrados quando a Skill é invocada e duram pelo resto da sessão. Isso é verdade em ambos os caminhos de invocação — tanto quando o modelo chama a Skill quanto quando você digita /<skill-name>.
Os hooks de sessão existem apenas na memória, então retomar uma sessão com --continue / --resume não os restaura, em nenhum caminho de invocação. As instruções da Skill podem voltar com a conversa reexecutada, enquanto os hooks que deveriam aplicá-las se foram — reexecute a Skill após retomar para rearmar seu gate.
O registro é idempotente: reinvocar uma Skill não acumula hooks duplicados.
Sempre defina um matcher: explícito para um evento de ferramenta. Um matcher omitido é armazenado como padrão vazio, que é compilado para ^$ e não corresponde a nenhum nome de ferramenta — o hook é registrado mas nunca é disparado, sem nada para indicar isso. Use * se quiser todas as ferramentas.
O command: é executado pelo shell da plataforma: bash no macOS e Linux, e no Windows o Git Bash quando detectado (MSYSTEM/TERM), caso contrário cmd.exe ou PowerShell. O exemplo acima é shell POSIX — sob cmd.exe, $QWEN_SKILL_ROOT não é expandido e um script .sh não é executável, então o gate falha abertamente ali. Um hook pode definir shell: bash para forçar o bash, mas isso resolve para qualquer bash no PATH, então no Windows fora do Git Bash escreva o gate para o shell que você realmente tem.
Sessões que desabilitam hooks não registram nenhum — disableAllHooks, modo seguro e o skipHooks de um cliente ACP. O corpo da Skill e seus allowedTools ainda se aplicam nessas sessões, mas seu gate não, então uma regra que depende de um hook para ser aplicada não será aplicada ali. O modo bare vai além: nenhuma Skill é descoberta, então não há corpo nem allowedTools.
Os hooks de uma Skill de projeto executam comandos fornecidos pelo repositório, então são registrados apenas em uma pasta confiável, e a confiança é relida toda vez que um hook é disparado e toda vez que uma permissão é decidida. Com um companion de IDE conectado, esse valor é dinâmico: revogar a confiança silencia um gate já registrado — e suspende os allowedTools da Skill — na próxima chamada de ferramenta, sem reiniciar. Sem conexão de IDE, o valor é fixado quando a CLI inicia, então uma alteração feita pelo próprio diálogo de confiança da CLI entra em vigor na reinicialização. Conceder confiança nunca registra retroativamente: invoque a Skill novamente.
hooks: é lido para Skills de projeto, de usuário e integradas. Skills fornecidas por extensões não o suportam; use os hooks de nível de manifesto da própria extensão.
Consulte Hooks para a lista completa de eventos, sintaxe de matcher e formato de saída.

Adicionar arquivos de suporte

Crie arquivos adicionais junto com o 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)

Referencie esses arquivos a partir do SKILL.md:


For advanced usage, see [reference.md](reference.md).
 
Run the helper script:
 
```bash
python scripts/helper.py input.txt
```

Visualizar Skills disponíveis

O Qwen Code descobre Skills a partir de:

Skills pessoais: ~/.qwen/skills/
Skills de projeto: .qwen/skills/
Skills de extensão: Skills fornecidas por extensões instaladas
Skills integradas: Skills distribuídas com o Qwen Code

Skills de Extensão

As extensões podem fornecer Skills personalizadas que ficam disponíveis quando a extensão é habilitada. Essas Skills são armazenadas no diretório skills/ da extensão e seguem o mesmo formato das Skills pessoais e de projeto.

As Skills de extensão são descobertas e carregadas automaticamente quando a extensão é instalada e habilitada.

Para ver quais extensões fornecem Skills, verifique o arquivo qwen-extension.json da extensão para um campo skills.

Como as Skills de extensão são nomeadas

O Qwen Code registra uma Skill de uma extensão instalada como <extensionName>:<name>, onde <extensionName> é o campo name do qwen-extension.json dessa extensão e <name> é o name do frontmatter da própria Skill. Uma Skill chamada pdf na extensão rust é registrada como rust:pdf.

O prefixo é adicionado enquanto a Skill é carregada, não escrito no arquivo: seu SKILL.md mantém o nome que você criou, e o Qwen Code nunca recupera o nome criado dividindo o nome registrado (um autor pode legitimamente escrever rust:chat dentro de rust). Apenas Skills de extensão recebem prefixo — Skills pessoais, de projeto e integradas mantêm a única grafia que você criou.

Use o nome registrado em todos os lugares onde você se refere à Skill:

Invoque-a como /rust:pdf. O /pdf puro não é um alias — a Skill da extensão é acessível apenas sob seu nome registrado.
O modelo a chama como Skill { skill: "rust:pdf" }, o mesmo nome que lê em <available_skills>.
Duas extensões que cada uma tem uma Skill chamada pdf resultam em duas Skills (rust:pdf e docs-suite:pdf) em vez de uma vencer e a outra desaparecer.

As superfícies onde você lê e escolhe Skills também nomeiam o owner: o painel de Skills (incluindo as linhas que uma configuração travou), a listagem somente leitura que um /skills puro imprime fora da UI interativa (ACP e outros modos não interativos — interativamente o comando abre o painel), e o badge na paleta de comandos /, que lê [Extension: Rust] em vez de um [Extension] puro. Esses labels preferem o displayName da extensão e usam seu name como fallback quando ela não declara nenhum.

Skills de extensão e as configurações `skills.*`

skills.disabled, skills.defaultDisabled e slashCommands.disabled correspondem a uma Skill de extensão sob qualquer grafia, então um skills.disabled: ["pdf"] que você escreveu antes do prefixo existir ainda oculta rust:pdf. Uma restrição só pode remover capability, então renomear uma Skill não pode remover uma restrição.

skills.enabled é a exceção, e a única mudança visível para um arquivo de configurações existente: ele concede capability, então corresponde apenas ao nome registrado. skills.enabled: ["pdf"] não inclui mais o pdf de uma extensão por conta própria — escreva skills.enabled: ["rust:pdf"]. O único par puro que continua funcionando é um opt-in pré-prefixo em skills.defaultDisabled com a mesma grafia: a cancelamento compara as próprias entradas, então defaultDisabled: ["pdf"] + enabled: ["pdf"] cancela a entrada — a skill então termina habilitada conforme a enablement armazenada para este workspace, senão o padrão da própria extensão; para uma skill default-off, escreva rust:pdf em skills.enabled.

Alternar uma Skill no painel de Skills escreve o nome registrado e remove apenas essa entrada, então habilitar rust:pdf deixa um disabled: ["pdf"] legado intacto. Quando essa entrada legada está em um escopo superior — padrões do sistema, usuário ou configurações do sistema — o painel diz isso e trava a linha, nomeando o escopo a editar em vez de oferecer um toggle que não pode movê-la. Uma entrada legada nas próprias configurações deste workspace trava a linha da mesma forma, nomeando a entrada e seu escopo (skills.disabled 'pdf' (Workspace) ou skills.defaultDisabled 'pdf' (Workspace)) para que você saiba qual lista em qual arquivo editar.

Dois limites que vale conhecer:

A precedência entre níveis não mudou e ainda compara nomes registrados exatamente (project > user > extension > bundled), então uma Skill pessoal ou de projeto que você criar como rust:pdf supera o pdf da extensão. Colisões de nome puro entre uma Skill pessoal ou de projeto e uma Skill integrada ainda são resolvidas por essa precedência, não pelo prefixo. Uma Skill que colide com um comando personalizado não é — na superfície slash o último loader vence, e comandos personalizados carregam depois das Skills, então /pdf executa o comando personalizado enquanto a Skill permanece disponível para o modelo.
Nomes de Skills também são usados como nomes de arquivo: o arquivo do qual uma Skill lê seus argumentos de invocação substitui cada caractere fora de [A-Za-z0-9._-] por _, então uma Skill de extensão registrada como rust:pdf e uma Skill pessoal ou de projeto criada como rust_pdf ambas resolvem para qwen-skill-args-rust_pdf.txt e compartilham um arquivo de argumentos. (O prefixo raramente colide consigo mesmo — rust:rust_pdf se torna rust_rust_pdf — mas nomes de extensão podem conter _, então rust_pdf:x e rust:pdf_x convergem para o mesmo nome de arquivo.) Letras não-ASCII convergem da mesma forma, então um café criado e um caf_ criado terminam em caf_ também — uma limitação que precede o prefixo, que apenas torna mais fácil de atingir. Evite um nome de Skill que seja outro nome com : transformado em _.

Para visualizar as Skills disponíveis, pergunte diretamente ao Qwen Code:


What Skills are available?

Atenção — visualização do modelo vs. usuário. Perguntar ao modelo exibe apenas as Skills que o modelo pode ver atualmente. Se uma Skill usar paths: (consulte “Opcional: restringir uma Skill a caminhos de arquivo” acima), ela permanece fora dessa listagem até que um arquivo correspondente seja acessado. O slash command /skills mostra as Skills que você pode invocar diretamente; Skills com user-invocable: false permanecem visíveis no disco e ainda podem estar visíveis para o modelo.

Ou navegue pela lista invocável pelo usuário com o slash command (incluindo Skills restritas por caminho que ainda não foram ativadas):


/skills

Ou inspecione o sistema de arquivos:


# Listar Skills pessoais
ls ~/.qwen/skills/
 
# Listar Skills de projeto (se estiver em um diretório de projeto)
ls .qwen/skills/
 
# Visualizar o conteúdo de uma Skill específica
cat ~/.qwen/skills/my-skill/SKILL.md

Testar uma Skill

Após criar uma Skill, teste-a fazendo perguntas que correspondam à sua descrição.

Exemplo: se a sua descrição mencionar “arquivos PDF”:


Can you help me extract text from this PDF?

O modelo decide autonomamente usar a sua Skill se ela corresponder à solicitação — você não precisa invocá-la explicitamente.

Depurar uma Skill

Se o Qwen Code não usar a sua Skill, verifique estes problemas comuns:

Torne a descrição específica

Muito vaga:


description: Helps with documents

Específica:


description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDFs, forms, or document extraction.

Verificar o caminho do arquivo

Skills pessoais: ~/.qwen/skills/<skill-name>/SKILL.md
Skills de projeto: .qwen/skills/<skill-name>/SKILL.md


# Pessoal
ls ~/.qwen/skills/my-skill/SKILL.md
 
# Projeto
ls .qwen/skills/my-skill/SKILL.md

Verificar a sintaxe YAML

Um YAML inválido impede que os metadados da Skill sejam carregados corretamente.


cat SKILL.md | head -n 15

Certifique-se de que:

O --- de abertura esteja na linha 1
O --- de fechamento esteja antes do conteúdo Markdown
A sintaxe YAML seja válida (sem tabs, indentação correta)

Visualizar erros

Execute o Qwen Code com o modo de depuração para ver erros de carregamento de Skills:


qwen --debug

Compartilhar Skills com sua equipe

Você pode compartilhar Skills por meio de repositórios de projeto:

Adicione a Skill em .qwen/skills/
Faça commit e push
Os colegas de equipe fazem pull das alterações


git add .qwen/skills/
git commit -m "Add team Skill for PDF processing"
git push

Atualizar uma Skill

Edite o SKILL.md diretamente:


# Skill pessoal
code ~/.qwen/skills/my-skill/SKILL.md
 
# Skill de projeto
code .qwen/skills/my-skill/SKILL.md

Durante uma sessão normal, o Qwen Code monitora os diretórios de Skills pessoais e de projeto. Adicionar, editar ou remover uma Skill atualiza a lista de Skills e o estado de invocação automaticamente após um curto atraso. O modo bare não inicia esses watchers, então reinicie o Qwen Code para carregar alterações de Skills nesse modo.

Remover uma Skill

Exclua o diretório da Skill:


# Pessoal
rm -rf ~/.qwen/skills/my-skill
 
# Projeto
rm -rf .qwen/skills/my-skill
git commit -m "Remove unused Skill"

Boas práticas

Mantenha as Skills focadas

Uma Skill deve abordar uma capacidade:

Focado: “preenchimento de formulários PDF”, “análise de Excel”, “mensagens de commit do Git”
Amplo demais: “processamento de documentos” (divida em Skills menores)

Escreva descrições claras

Ajude o modelo a descobrir quando usar as Skills incluindo gatilhos específicos:


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

Teste com sua equipe

A Skill é ativada quando esperado?
As instruções estão claras?
Faltam exemplos ou casos limite?