Skip to main content
Skills estendem o que Claude pode fazer. Crie um arquivo SKILL.md com instruções, e Claude o adiciona ao seu kit de ferramentas. Claude usa skills quando relevante, ou você pode invocar uma diretamente com /skill-name. Crie uma skill quando você fica colando as mesmas instruções, checklist ou procedimento de múltiplas etapas no chat, ou quando uma seção de CLAUDE.md cresceu e se tornou um procedimento em vez de um fato. Diferentemente do conteúdo de CLAUDE.md, o corpo de uma skill é carregado apenas quando é usado, então material de referência longo custa quase nada até que você precise dele.
Para comandos integrados como /help e /compact, e skills agrupadas como /debug e /code-review, consulte a referência de comandos.Comandos personalizados foram mesclados em skills. Um arquivo em .claude/commands/deploy.md e uma skill em .claude/skills/deploy/SKILL.md ambos criam /deploy e funcionam da mesma forma. Seus arquivos .claude/commands/ existentes continuam funcionando. Skills adicionam recursos opcionais: um diretório para arquivos de suporte, frontmatter para controlar se você ou Claude os invoca, e a capacidade de Claude carregá-los automaticamente quando relevante.
As skills do Claude Code seguem o padrão aberto Agent Skills, que funciona em múltiplas ferramentas de IA. Claude Code estende o padrão com recursos adicionais como controle de invocação, execução de subagent, e injeção de contexto dinâmico. Consulte Usando frontmatter de skill fora do Claude Code para saber quais campos de frontmatter fazem parte do padrão e quais são extensões do Claude Code.

Skills agrupadas

Claude Code inclui um conjunto de skills agrupadas, como /doctor, /code-review, /batch, /debug, /loop e /claude-api. Skills agrupadas são baseadas em prompt: elas fornecem ao Claude instruções detalhadas e permitem que ele orquestre o trabalho usando suas ferramentas. A maioria dos comandos integrados executa lógica fixa diretamente. Você invoca uma skill agrupada da mesma forma que qualquer outra skill, digitando / seguido do nome da skill. Claude invoca algumas skills agrupadas automaticamente quando relevante; outras, incluindo /verify, são executadas apenas quando você as invoca, o que mantém você no controle de quando essas verificações de execução mais longa gastam tempo e tokens. A maioria das skills agrupadas está disponível em todas as sessões. Algumas dependem de um recurso específico: /workflow-authoring, por exemplo, está disponível apenas quando fluxos de trabalho dinâmicos estão habilitados. Para desativar skills agrupadas, use a configuração disableBundledSkills.
A verificação de configuração /doctor permanece digitável quando disableBundledSkills está ativado, no Claude Code v2.1.205 e posterior. Para ocultá-la, defina a variável de ambiente DISABLE_DOCTOR_COMMAND ou uma entrada skillOverrides de "doctor": "off". Antes da v2.1.205, /doctor era um comando integrado em vez de uma skill agrupada.
Skills agrupadas são listadas junto com comandos integrados na referência de comandos, marcadas como Skill na coluna Propósito.

Execute e verifique seu aplicativo

Três skills agrupadas trabalham juntas para iniciar seu aplicativo e confirmar alterações em relação ao aplicativo em execução em vez de apenas testes: /run e /verify funcionam sem configuração. Eles inferem o lançamento do tipo de seu projeto (CLI, servidor, TUI, orientado por navegador) e do que está em seu README, package.json ou Makefile. Essa inferência se torna pouco confiável para projetos que precisam de algo além de um lançamento padrão: um banco de dados, um arquivo env, uma sessão gráfica, uma compilação em várias etapas. /run-skill-generator registra a receita em vez disso. Ele coloca seu aplicativo em execução a partir de um ambiente limpo, captura o que funcionou (os comandos de instalação, as variáveis de ambiente, o script de lançamento) e o confirma como uma skill por projeto em .claude/skills/run-<name>/. Depois disso, /run, /verify e qualquer outro agente no repositório seguem a receita registrada em vez de redescobri-la. Execute /run-skill-generator uma vez por projeto e novamente se o processo de compilação ou lançamento mudar. /verify também pode registrar sua própria receita. Quando ele precisa compilar e conduzir seu aplicativo sem uma receita registrada, ele escreve o que funcionou em .claude/skills/verify/SKILL.md na raiz do repositório, ou no diretório de pacote tocado em um monorepo, para que execuções posteriores e outros agentes sigam as mesmas etapas. Na raiz do repositório, a skill registrada substitui o /verify agrupado. Isso requer Claude Code v2.1.200 ou posterior. Claude edita o arquivo registrado apenas quando direcionou uma execução incorretamente, como um comando que falhou ou uma etapa ausente, para que você possa confirmar o arquivo sem diffs por sessão. Antes da v2.1.205, a skill agrupada dizia ao Claude para incorporar qualquer coisa que uma execução aprendesse, o que causava conflitos de mesclagem frequentes.

Primeiros passos

Crie sua primeira skill

Este exemplo cria uma skill que resume as alterações não confirmadas em seu repositório git e sinaliza qualquer coisa arriscada. Ele puxa o diff ao vivo para o prompt antes de Claude lê-lo, para que a resposta seja fundamentada em sua árvore de trabalho real em vez do que Claude pode adivinhar a partir de arquivos abertos. Claude carrega a skill automaticamente quando você pergunta sobre suas alterações, ou você pode invocá-la diretamente com /summarize-changes.
1

Crie o diretório da skill

Crie um diretório para a skill em sua pasta de skills pessoais. Skills pessoais estão disponíveis em todos os seus projetos.
2

Escreva SKILL.md

Toda skill precisa de um arquivo SKILL.md com duas partes: frontmatter YAML entre marcadores --- que diz a Claude quando usar a skill, e conteúdo markdown com as instruções que Claude segue quando a skill é executada. O nome do diretório, ou o frontmatter name quando você define um, se torna o comando que você digita, e a description ajuda Claude a decidir quando carregar a skill automaticamente.Salve isto em ~/.claude/skills/summarize-changes/SKILL.md:
A linha !`git diff HEAD` usa injeção de contexto dinâmico: Claude Code executa o comando e substitui a linha por sua saída antes de Claude ver o conteúdo da skill, para que as instruções cheguem com o diff atual já embutido.
3

Teste a skill

Abra um projeto git, faça uma pequena edição em qualquer arquivo e inicie Claude Code executando claude. Você pode testar a skill de duas maneiras.Deixe Claude invocá-la automaticamente perguntando algo que corresponda à descrição:
Ou invoque-a diretamente com o nome da skill:
De qualquer forma, Claude deve responder com um breve resumo de sua edição e uma lista de riscos.

Escolha onde as skills são carregadas

Onde você salva uma skill decide quais sessões a carregam. Salve-a no seu diretório inicial para obtê-la em todos os projetos, confirme-a em um repositório para compartilhá-la com todos que trabalham lá, ou distribua-a através de um plugin ou configurações gerenciadas para alcançar toda uma equipe. As pastas de skill também seguem estas regras:
  • Pastas com symlink: uma entrada <skill-name> no local enterprise, personal ou project pode ser um symlink para um diretório em outro lugar no disco. Claude Code lê SKILL.md do alvo e carrega a skill uma vez mesmo que vários locais apontem para o mesmo alvo. Skills de plugin lidam com symlinks de forma diferente.
  • Nome reservado synced: não nomeie uma pasta de skill como synced, em qualquer capitalização. Claude Code usa ~/.claude/skills/synced/ para skills baixadas do claude.ai e pula uma skill que você cria com esse nome nos locais enterprise, personal e project.
  • Nome reservado anthropic-skills: fora de um plugin, uma pasta de skill ou arquivo de comando cujo nome é anthropic-skills ou começa com anthropic-skills: não carrega. Veja Nomes reservados para skills sincronizadas.
  • Arquivos de comando: um arquivo Markdown em .claude/commands/ é o formato mais antigo e ainda funciona. Ele suporta o mesmo frontmatter exceto name e paths. Para encontrar o nome que você digita para invocá-lo, veja Como uma skill obtém seu nome de comando. Prefira uma skill para novo trabalho, já que skills também suportam arquivos de suporte.
  • Pasta de skill como um plugin: adicione um .claude-plugin/plugin.json a uma pasta de skill e ela carrega como um plugin nomeado <name>@skills-dir, para que possa agrupar agents, hooks e servidores MCP. Em um .claude/skills/ de projeto, isso requer aceitar primeiro o diálogo de confiança do workspace.

Carregue skills em monorepos e subdiretórios

Claude Code carrega skills de projeto de .claude/skills/ no diretório onde você o inicia e em todos os diretórios pai até a raiz do repositório, então iniciar em packages/frontend/ ainda pega skills definidas na raiz. Quando você move a sessão com /cd na v2.1.246 ou posterior, Claude Code adiciona as skills de projeto do novo diretório. Em uma sessão executada em um git worktree vinculado, Claude Code pesquisa diretórios pai apenas até a raiz do worktree. Na Claude Code v2.1.277 ou posterior, quando o checkout do worktree não tem um diretório .claude/skills em sua raiz, Claude Code carrega as skills de projeto do checkout principal. Veja O que worktrees compartilham com o checkout principal. Skills em um diretório .claude/skills/ abaixo de onde você iniciou não carregam na inicialização. Elas carregam na primeira vez que Claude lê ou edita um arquivo naquele subdiretório e permanecem disponíveis pelo resto da sessão. Até então, elas não aparecem no menu / e você não pode invocá-las por nome. Para carregá-las mais cedo, execute /add-dir com o caminho do subdiretório, o que requer Claude Code v2.1.257 ou posterior. Quando o nome do diretório de uma skill aninhada corresponde ao nome de outra skill, ambas permanecem disponíveis. Com uma skill deploy na raiz do repositório e outra em apps/web/.claude/skills/:
  • /deploy executa a skill raiz. Claude Code também lista as variantes qualificadas por diretório para Claude, com uma instrução para invocar aquela cujo diretório contém os arquivos em que está trabalhando, para que a skill aninhada ainda se aplique ao trabalho em apps/web/.
  • /apps/web:deploy executa a skill aninhada por conta própria. Sua descrição nomeia o diretório ao qual se aplica.

Carregue skills de um diretório fora do projeto

Quando você adiciona um diretório com --add-dir ou /add-dir, Claude Code carrega as skills no .claude/skills/ daquele diretório, junto com seu .claude/commands/ e .claude/agents/. Diretórios que o Agent SDK adiciona através de additionalDirectories em TypeScript ou add_dirs em Python carregam da mesma forma, porque o SDK os passa como --add-dir. A configuração permissions.additionalDirectories em settings.json concede apenas acesso a arquivos e não carrega nenhum destes. Claude Code observa .claude/skills/ em um diretório que você passa com --add-dir na inicialização, como Edite uma skill durante uma sessão descreve. Ele não observa o .claude/commands/ ou .claude/agents/ do diretório adicionado, então reinicie a sessão após alterar um arquivo lá. Esses carregamentos dependem da fonte de configuração project, que está ativada por padrão. Uma política strictPluginOnlyCustomization, modo bare e --safe-mode cada uma as restringe ainda mais, como essas páginas descrevem. Veja Diretórios adicionais concedem acesso a arquivos, não configuração para a tabela completa do que um diretório adicionado carrega, incluindo CLAUDE.md e configurações de plugin.

Resolva skills que compartilham um nome

Quando duas skills compartilham um nome de diretório ou arquivo, de onde cada uma veio decide qual /name executa. Para um nome definido pelo campo frontmatter name, veja Como uma skill obtém seu nome de comando. A tabela cobre os locais enterprise, personal, project, nested, plugin e claude.ai, skills agrupadas e arquivos de comando:

Use skills em sessões Cowork e cloud

Sessões Cowork e sessões cloud, incluindo rotinas, não leem ~/.claude/skills/ em sua máquina. Tanto sessões Cowork interativas quanto agendadas carregam as skills habilitadas para sua conta claude.ai, sincronizadas no início da sessão; gerencie-as em Customize na barra lateral do aplicativo Desktop ou nas configurações de skills em claude.ai. Sessões cloud carregam adicionalmente skills de projeto confirmadas no .claude/skills/ do repositório clonado. Se uma skill existe apenas em ~/.claude/skills/ em sua máquina, Claude Code relata que a skill não foi encontrada quando uma rotina a invoca, porque cada execução de rotina começa como uma sessão cloud nova. Para disponibilizar uma skill pessoal nessas sessões:
  • Para sessões Cowork e cloud, habilite a skill para sua conta claude.ai.
  • Para sessões cloud, você pode em vez disso confirmar a skill no .claude/skills/ do repositório. Plugins declarados no .claude/settings.json do repositório e plugins habilitados apenas em suas configurações de usuário não carregam em sessões cloud.
Tarefas agendadas do Desktop executam localmente em sua máquina, então elas carregam ~/.claude/skills/.

Skills sincronizadas do claude.ai

Esta seção se aplica a você se usar sessões Cowork ou cloud, ou se conectar a Claude Code em seu terminal com uma conta claude.ai. Nessas sessões, Claude Code carrega as skills habilitadas para sua conta claude.ai, sem nenhuma configuração de sua parte, como Onde as skills sincronizadas carregam descreve. Essas skills incluem as que você cria ou ativa em suas configurações claude.ai, skills que sua organização fornece lá, e skills integradas da Anthropic como pdf e xlsx. Claude Code baixa uma skill sincronizada de sua conta em vez de ler um arquivo que você escreveu na máquina onde a sessão executa, então aplica regras a skills sincronizadas que não se aplicam às skills que você armazena nos locais de skills.

Onde as skills sincronizadas carregam

Em uma sessão Cowork ou cloud, Claude Code carrega as skills habilitadas para sua conta claude.ai, e Skills em sessões Cowork e cloud diz como escolher quais skills essas sessões obtêm. Em seu terminal, Claude Code sincroniza essas skills em sessões onde você se conecta com sua conta claude.ai. Quando a sessão inicia, Claude Code baixa as skills de sua conta em ~/.claude/skills/synced/ em segundo plano, então verifica claude.ai para mudanças a cada 10 minutos enquanto a sessão executa. Quando uma verificação encontra que uma skill foi adicionada, editada ou desativada em claude.ai, Claude Code a adiciona, atualiza ou remove na sessão em execução sem uma reinicialização. A sincronização em sessões de terminal requer Claude Code v2.1.273 ou posterior. A sincronização nunca atrasa a inicialização, porque Claude aguarda o download de uma skill apenas quando a invoca. Uma execução não interativa curta pode portanto terminar antes que uma skill recém-adicionada seja baixada, caso em que uma sessão posterior a baixa. Para fazer uma execução não interativa baixar suas skills e aguardar a lista antes de responder ao prompt, defina CLAUDE_CODE_SYNC_SKILLS como 1. Claude Code sincroniza apenas em uma sessão que se conecta com sua conta claude.ai e busca sinalizadores de recurso da Anthropic. Ele não sincroniza nessas sessões:
  • Uma sessão que não usa um sign-in armazenado por /login, como uma que autentica com uma chave de API, ou uma onde ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_OAUTH_TOKEN ou um script apiKeyHelper fornece a credencial
  • Uma sessão que não busca sinalizadores de recurso, como uma em Amazon Bedrock ou uma onde você define CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC
  • Uma sessão em modo bare ou uma que você inicia com --safe-mode
  • Uma sessão onde as configurações gerenciadas de sua organização bloqueiam skills para fontes de plugin, ou uma que você inicia com uma lista --setting-sources que deixa de fora user
Se você se conectar com /login durante uma sessão, reinicie Claude Code para começar a sincronizar. Skills que uma sessão anterior sincronizou permanecem no disco. Claude Code as carrega em sessões posteriores conectadas à mesma conta, mesmo quando não consegue alcançar claude.ai. Claude Code baixa skills sincronizadas e nunca as envia. Se você ou Claude editar um arquivo em ~/.claude/skills/synced/, a alteração não é salva em sua conta claude.ai, e uma sincronização posterior pode sobrescrevê-la ou removê-la. Para alterar uma skill sincronizada, atualize-a em claude.ai; a próxima sincronização baixa a nova versão. Para ver quais skills sincronizaram, execute /skills. O menu as lista em claude.ai sync. Algumas skills da Anthropic, como pdf e xlsx, sempre sincronizam. Para o resto, ative ou desative uma skill em suas configurações de skills em claude.ai para alterar se ela sincroniza. Para parar de sincronizar em uma máquina, defina syncClaudeAiSkills como false em suas configurações de usuário. Claude Code para de baixar, e na próxima vez que inicia, move as skills que já sincronizou para ~/.claude/skills/.trash/ e não as carrega mais. Sua organização pode desativar a sincronização para todos desativando Skills em claude.ai. Para parar de sincronizar deixando Skills ativado, pode definir a mesma chave em configurações gerenciadas. Se sua organização desativar Skills em claude.ai, Claude Code remove as skills baixadas e elas param de carregar. As skills removidas se movem para ~/.claude/skills/.trash/, onde você pode recuperar os arquivos até que a varredura de retenção os delete. Uma vez que sua organização ativa Skills novamente, Claude Code baixa as skills que você habilitou na próxima sincronização.

Quando um nome de skill sincronizada corresponde a outro comando

Você pode invocar uma skill sincronizada por seu nome curto, /<name>, ou por seu nome completo, /anthropic-skills:<name>. Quando outro comando usa o nome curto, /<name> executa o outro comando, e a skill sincronizada executa apenas como /anthropic-skills:<name>. Com uma skill local deploy e uma sincronizada deploy, /deploy executa a skill local e /anthropic-skills:deploy executa a sincronizada. Antes da v2.1.269, uma skill sincronizada tinha apenas seu nome curto. No menu /, /skills e /context, uma skill sincronizada aparece sob seu nome curto, ou sob seu nome completo enquanto outro comando usa o nome curto. Execute /skills em sua sessão. Uma nota sob a lista explica cada skill sincronizada que perdeu seu nome curto. Se um de seus skills pessoais ou arquivos de comando em ~/.claude/ usar o nome, a nota também diz o que renomear ou deletar para liberá-lo. Da v2.1.269 até v2.1.280, essas listas mostravam cada skill sincronizada sob seu nome completo, e /skills não tinha tal nota; ambas mudaram na v2.1.281. O comando que usa o nome curto pode ser qualquer um destes:
  • Um comando integrado ou uma skill agrupada, incluindo uma que não está disponível em sua sessão, por exemplo após você desativar skills agrupadas
  • Uma skill em qualquer nível local ou um arquivo em .claude/commands/
  • Uma skill de plugin
  • Um prompt MCP
Claude Code rotula skills sincronizadas para que você possa dizer de onde vieram. O menu /skills e /context agrupam skills sincronizadas em claude.ai sync, e o menu de comando / as marca como vindo de claude.ai. Quando compara nomes, Claude Code ignora maiúsculas, espaçamento e caracteres invisíveis, e trata formas de compatibilidade como letras de largura completa e variantes de travessão como seus equivalentes simples. Por exemplo, uma skill sincronizada nomeada Commit e uma skill local nomeada commit contam como o mesmo nome, então /commit continua executando sua skill local. Um nome que difere apenas por uma letra semelhante de outro alfabeto conta como um nome diferente, e o rótulo claude.ai sync é como você diferencia os dois. Essas verificações e rótulos requerem Claude Code v2.1.228 ou posterior.

Nomes reservados para skills sincronizadas

Claude Code reserva o nome anthropic-skills, e cada nome dentro daquele namespace como anthropic-skills:pdf, para skills sincronizadas do claude.ai, então o nome completo de uma skill sincronizada nunca executa nada mais. O nome é reservado em cada sessão, independentemente de você se conectar ou não com uma conta claude.ai.
  • Uma pasta de skill, um frontmatter name, um arquivo ou subpasta em .claude/commands/, ou um fluxo de trabalho salvo: ele não carrega. Um aviso de inicialização nomeia o primeiro item a renomear ou editar.
  • Um plugin nomeado anthropic-skills: ele carrega. Quando uma de suas skills e uma skill sincronizada são ambas nomeadas <name>, /anthropic-skills:<name> executa a skill sincronizada.
  • Um servidor MCP nomeado anthropic-skills: ele se conecta e suas ferramentas funcionam, mas seus prompts não aparecem como comandos. Renomeie o servidor em sua configuração MCP para listá-los.

Como Claude Code lida com o frontmatter de uma skill sincronizada

Claude Code aplica duas regras ao frontmatter de uma skill sincronizada:
  • Claude Code honra o frontmatter em cada tipo de sessão, então uma concessão allowed-tools passa pelo fluxo de permissão normal.
  • Claude Code sanitiza o texto de exibição que a skill fornece, como sua descrição. Remove caracteres de controle, e em texto que alcança Claude, como a descrição, também escapa colchetes angulares para que o texto não possa imitar a formatação interna de Claude Code. Esta sanitização requer Claude Code v2.1.228 ou posterior.

Como Claude Code lida com o corpo de uma skill sincronizada

O que Claude Code faz com o corpo de uma skill sincronizada depende de onde a sessão executa:
  • Em uma sessão cloud, o corpo mantém o comportamento que uma skill local tem, porque a sessão executa em um contêiner isolado.
  • Em uma sessão Cowork em seu desktop, o corpo mantém o comportamento que uma skill local tem, exceto que Claude Code substitui cada linha de comando ! pelo placeholder disableSkillShellExecution, como faz para cada skill que você fornece lá.
  • Em qualquer outra sessão em sua máquina, Claude Code não executa comandos !, não anexa os arquivos que referências @ nomeiam da forma que faz para uma skill local, e não substitui os placeholders ${CLAUDE_PROJECT_DIR} e ${CLAUDE_SESSION_ID}, então as referências @ e ambos os placeholders alcançam Claude como texto literal. Uma linha de comando ! alcança Claude como texto literal também, ou como aquele placeholder quando disableSkillShellExecution está ativado. Este tratamento requer Claude Code v2.1.228 ou posterior.

Edite uma skill durante uma sessão

Claude Code observa diretórios de skill para mudanças de arquivo, exceto em modo bare. Quando você adiciona, edita ou remove uma skill em ~/.claude/skills/, o .claude/skills/ do projeto, ou um .claude/skills/ dentro de um diretório --add-dir, Claude Code pega a mudança dentro da sessão atual, sem uma reinicialização. Se você criar um diretório de skills de nível superior que não existia quando a sessão iniciou, execute /reload-skills para pegar as skills que você colocou lá. Claude Code não está observando aquele diretório ainda, então execute /reload-skills novamente após cada mudança posterior lá. A detecção de mudança ao vivo cobre apenas texto SKILL.md. Para uma pasta de skill que também é um plugin, mudanças em hooks/, .mcp.json, agents/ e output-styles/ precisam de /reload-plugins para entrar em vigor.

Remova uma skill

Como você remove uma skill depende de onde ela veio:
  • Skill pessoal ou de projeto: delete o diretório da skill, ~/.claude/skills/<skill-name>/ ou .claude/skills/<skill-name>/. Claude Code a remove de /skills na sessão atual; o conteúdo que Claude Code já carregou dela segue o ciclo de vida do conteúdo da skill.
  • Skill enterprise: um administrador deleta o diretório da skill de .claude/skills/ dentro do diretório de configurações gerenciadas, por exemplo /etc/claude-code/.claude/skills/<skill-name>/ em Linux.
  • Skill de plugin: desabilite ou desinstale o plugin que a fornece, do menu /plugin ou com /plugin uninstall <plugin-name>@<marketplace-name>. Claude Code descarrega as skills do plugin quando a mudança se aplica ou quando você reinicia.
  • Skill sincronizada do claude.ai: desative a skill para sua conta claude.ai, no mesmo lugar onde você a habilitou. Claude Code a remove de ~/.claude/skills/synced/ na próxima vez que sincroniza suas skills. Se você deletar o diretório manualmente, a próxima sincronização o baixa novamente enquanto a skill permanece habilitada em claude.ai.
  • Skill agrupada: defina disableBundledSkills como true para desativar skills agrupadas, ou defina uma skill como "off" em skillOverrides para ocultá-la.
Para manter uma skill pessoal ou de projeto mas parar Claude de invocá-la por conta própria, defina disable-model-invocation: true em seu frontmatter, ou "user-invocable-only" em skillOverrides quando você não quer editar o arquivo.

Configurar skills

Skills são configuradas através de frontmatter YAML no topo de SKILL.md e no conteúdo markdown que segue.

Tipos de conteúdo de skill

Arquivos de skill podem conter qualquer instrução, mas pensar em como você quer invocá-los ajuda a guiar o que incluir: Conteúdo de referência adiciona conhecimento que Claude aplica ao seu trabalho atual. Convenções, padrões, guias de estilo, conhecimento de domínio. Este conteúdo é executado inline para que Claude possa usá-lo junto com seu contexto de conversa.
Conteúdo de tarefa fornece a Claude instruções passo a passo para uma ação específica, como deployments, commits ou geração de código. Estas são frequentemente ações que você quer invocar diretamente com /skill-name em vez de deixar Claude decidir quando executá-las. Adicione disable-model-invocation: true para evitar que Claude a dispare automaticamente. O exemplo abaixo adiciona context: fork, que executa a skill em seu próprio contexto de subagent; veja Executar skills em um subagent.
Mantenha o corpo em si conciso. Uma vez que uma skill é carregada, seu conteúdo permanece em contexto entre turnos, então cada linha é um custo de token recorrente. Declare o que fazer em vez de narrar como ou por que, e aplique o mesmo teste de concisão que você faria para conteúdo CLAUDE.md.

Referência de frontmatter

Configure uma skill com YAML frontmatter entre marcadores --- no topo de SKILL.md, e escreva as instruções da skill como Markdown após o --- de fechamento. Os nomes de campo usam palavras minúsculas separadas por hífens, exceto when_to_use. Um arquivo de comando em .claude/commands/ aceita os mesmos campos exceto name e paths. Este exemplo define quatro campos:
Todos os campos são opcionais. Apenas description é recomendado para que Claude saiba quando usar a skill. Um nome de campo deve corresponder exatamente à tabela, hífens inclusos: Claude Code ignora um campo que não reconhece sem relatar um erro. Claude Code lê o frontmatter apenas quando a abertura --- é a primeira linha do arquivo. Caso contrário, trata o arquivo inteiro, incluindo marcadores ---, como conteúdo de skill. Se o YAML entre os marcadores não for analisado, a skill ainda carrega sem campos definidos; veja Skill não disparando para encontrar e corrigir o erro. Campos booleanos aceitam yes, no, on, off, 1 e 0 em qualquer caso de letra, além de true e false. Antes da v2.1.218, Claude Code reconhecia apenas true e false.

Usando frontmatter de skill fora do Claude Code

Claude Code aceita todos os campos na tabela acima. Fora do Claude Code, você pode usar apenas os campos na especificação Agent Skills: Quando você habilita uma skill pessoal para sua conta claude.ai, por exemplo para usá-la em sessões Cowork e cloud e rotinas, você a carrega no claude.ai, então as mesmas regras se aplicam. Se você incluir qualquer campo que a especificação não permite, o empacotamento ou upload falha com um erro difícil em vez de ignorar o campo:
Restringir o frontmatter aos seis campos da especificação evita o erro de chave inesperada acima. A especificação Agent Skills e os requisitos da Skills API definem tudo mais que esses caminhos validam. Recursos de corpo específicos do Claude Code, como injeção de contexto dinâmico, não funcionam no chat claude.ai ou através da API. Claude Code aceita todos os seis campos, então o frontmatter que segue a especificação carrega no Claude Code sem alterações.

Como uma skill obtém seu nome de comando

O comando que você digita para invocar uma skill vem de onde o arquivo de skill vive e, para diretórios de skill e skills de plugin, do campo frontmatter name. Em um diretório de skill pessoal ou de projeto, name define o comando que o menu / mostra e que você digita, a menos que outro comando já use esse nome. O nome do diretório também invoca a skill. Em uma skill de plugin, name define o último segmento do comando e o prefixo do plugin permanece no lugar. A tabela abaixo mostra de onde o nome do comando vem para cada layout: Em uma skill de plugin, o frontmatter name substitui o nome do diretório no último segmento do comando, então my-plugin/skills/review/SKILL.md com name: fancy se torna /my-plugin:fancy. O comando /fancy simples também invoca a skill a menos que outro comando já use esse nome. Se o name que você escreve já começa com o próprio prefixo do plugin, Claude Code não adiciona o prefixo novamente na v2.1.246 ou posterior. Por exemplo, name: my-plugin:fancy ainda se torna /my-plugin:fancy. Da v2.1.216 até v2.1.245, Claude Code duplicava o prefixo quando o name já o carregava. Em sessões não-interativas, os nomes help e feedback não são reservados para seus comandos built-in apenas de terminal, então uma skill de plugin com um desses nomes mantém seu comando simples lá. Todos os outros built-ins apenas de terminal, como /login, permanecem reservados mesmo que o comando não possa ser executado nessas sessões. Para um SKILL.md raiz de plugin, não há diretório de skill para obter o nome, então name fornece o segmento final inteiro. Sem um campo name, Claude Code volta para o nome do diretório do plugin.

Substituições de string disponíveis

Skills suportam substituição de string para valores dinâmicos no conteúdo da skill: Claude Code substitui ${CLAUDE_SKILL_DIR} e ${CLAUDE_PROJECT_DIR} em dois lugares: o conteúdo markdown da skill e regras Bash no frontmatter allowed-tools. Em uma skill de plugin, Claude Code substitui ${CLAUDE_PLUGIN_ROOT} e ${CLAUDE_PLUGIN_DATA} nos mesmos dois lugares. Usar a mesma variável em ambos os lugares permite que uma skill execute um script agrupado sem um prompt de permissão. A skill a seguir mostra o padrão:
Se esta skill está instalada em ~/.claude/skills/render-chart/, ambas as ocorrências de ${CLAUDE_SKILL_DIR} se expandem para esse diretório. A regra allowed-tools então corresponde ao comando exato que o corpo da skill diz a Claude para executar, então o script é executado sem avisar. A substituição ${CLAUDE_PROJECT_DIR} requer Claude Code v2.1.196 ou posterior. Argumentos indexados usam quoting estilo shell, então envolva valores com múltiplas palavras em aspas para passá-los como um único argumento. Por exemplo, /my-skill "hello world" second faz $0 se expandir para hello world e $1 para second. O placeholder $ARGUMENTS sempre se expande para a string de argumento completa conforme digitada. Um placeholder indexado sem argumento correspondente, como $2 quando apenas um argumento foi passado, permanece no conteúdo inalterado. Um placeholder nomeado do frontmatter arguments sem argumento correspondente se expande para uma string vazia. Se você passar um valor de argumento que em si contém texto como $1 ou $ARGUMENTS, Claude Code o insere como texto literal e não o expande. Por exemplo, se o corpo de uma skill contém Summarize $0 e você executa /summarize "$ARGUMENTS from yesterday", Claude recebe Summarize $ARGUMENTS from yesterday. Claude Code ainda substitui variáveis ${CLAUDE_*} como ${CLAUDE_SKILL_DIR} depois de inserir os argumentos. Para incluir um $ literal antes de um dígito, ARGUMENTS ou um nome de argumento declarado, como $1.00 em prosa, escape-o com uma barra invertida: \$1.00. Uma barra invertida antes de qualquer outro $ é deixada inalterada. Apenas uma única barra invertida diretamente antes do token a escapa. Uma barra invertida duplicada como \\$1 deixa ambas as barras invertidas no lugar, e $1 ainda se expande para o valor do argumento. O escape de barra invertida cobre apenas esses placeholders de argumento. Uma barra invertida não evita a substituição de uma variável ${CLAUDE_*} onde a variável se aplica. Exemplo usando substituições:

Adicionar arquivos de suporte

Skills podem incluir múltiplos arquivos em seu diretório. Isso mantém SKILL.md focado no essencial enquanto permite que Claude acesse material de referência detalhado apenas quando necessário. Documentos de referência grandes, especificações de API ou coleções de exemplos não precisam carregar em contexto toda vez que a skill é executada.
Referencie arquivos de suporte de SKILL.md para que Claude saiba o que cada arquivo contém e quando carregá-lo:
Mantenha SKILL.md sob 500 linhas. Mova material de referência detalhado para arquivos separados.

Controlar quem invoca uma skill

Por padrão, você e Claude podem invocar qualquer skill. Você pode digitar /skill-name para invocá-la diretamente, e Claude pode carregá-la automaticamente quando relevante para sua conversa. Dois campos de frontmatter permitem que você restrinja isso:
  • disable-model-invocation: true: Apenas você pode invocar a skill. Use isso para workflows com efeitos colaterais ou que você quer controlar o timing, como /commit, /deploy ou /send-slack-message. Você não quer que Claude decida fazer deploy porque seu código parece pronto.
  • user-invocable: false: Apenas Claude pode invocar a skill. Use isso para conhecimento de fundo que não é acionável como um comando. Uma skill legacy-system-context explica como um sistema antigo funciona. Claude deve saber disso quando relevante, mas /legacy-system-context não é uma ação significativa para os usuários tomarem.
Este exemplo cria uma skill de deploy que apenas você pode disparar. Se você definir disable-model-invocation: true, Claude não pode executar a skill automaticamente:
Se Claude tentar mesmo assim, Claude Code bloqueia a chamada e o instrui a não reproduzir os passos de deploy de outra forma, então espere que Claude sugira executar /deploy você mesmo. Aqui está como os dois campos afetam invocação e carregamento de contexto:
Em uma sessão regular, descrições de skills são carregadas em contexto para que Claude saiba o que está disponível, mas conteúdo de skill completo apenas carrega quando invocado. Subagents com skills pré-carregadas funcionam diferentemente: o conteúdo de skill completo é injetado na inicialização.

Ciclo de vida do conteúdo de skill

Quando você ou Claude invocam uma skill, o conteúdo SKILL.md renderizado entra na conversa como uma única mensagem e permanece lá entre turnos posteriores. Esta persistência se aplica às instruções da skill, não suas permissões: uma concessão allowed-tools é limpa quando você envia sua próxima mensagem. Claude Code não relê o arquivo de skill em turnos posteriores, então escreva orientação que deve se aplicar ao longo de uma tarefa como instruções permanentes em vez de passos únicos. Quando Claude reinvoca uma skill cujo conteúdo renderizado é idêntico à cópia já em contexto, Claude Code adiciona uma nota curta que a skill já está carregada em vez de uma segunda cópia do conteúdo. Quando o conteúdo renderizado difere, porque os argumentos mudaram ou um comando contexto dinâmico produziu nova saída, Claude Code anexa o conteúdo completo novamente. Auto-compactação leva skills invocadas adiante dentro de um orçamento de token. Quando a conversa é resumida para liberar contexto, Claude Code reanexa a invocação mais recente de cada skill após o resumo, mantendo os primeiros 5.000 tokens de cada. Skills reanexa compartilham um orçamento combinado de 25.000 tokens. Claude Code preenche este orçamento começando pela skill invocada mais recentemente, então skills mais antigas podem ser descartadas inteiramente após compactação se você invocou muitas em uma sessão. Se uma skill parece parar de influenciar o comportamento após a primeira resposta, o conteúdo geralmente ainda está presente e o modelo está escolhendo outras ferramentas ou abordagens. Fortaleça a description da skill e as instruções para que o modelo continue preferindo-a, ou use hooks para impor comportamento deterministicamente. Se a skill é grande ou você invocou várias outras depois dela, reinvoque-a após compactação para restaurar o conteúdo completo.

Pré-aprovar ferramentas para uma skill

O campo allowed-tools concede permissão para as ferramentas listadas durante o turno que invoca a skill, para que Claude possa usá-las sem avisar você para aprovação. A concessão é limpa quando você envia sua próxima mensagem, mesmo que o conteúdo da skill permaneça em contexto; invocar a skill novamente reaplica-a para esse turno. Não restringe quais ferramentas estão disponíveis: toda ferramenta permanece chamável, e suas configurações de permissão ainda governam ferramentas que não estão listadas. Para pré-aprovar ferramentas para a sessão inteira em vez de um único turno, adicione regras de permissão a essas configurações de permissão em vez disso. Confiança de workspace não bloqueia este campo. Claude Code aplica allowed-tools de uma skill de projeto sempre que você ou Claude invocam a skill, incluindo em uma execução -p em uma pasta que você nunca confiou. Uma skill pode conceder a si mesma acesso amplo a ferramentas, então revise allowed-tools de skills verificadas em um repositório antes de executar Claude Code lá. Esta skill permite que Claude execute comandos git sem aprovação por uso sempre que você invoca:
Para remover ferramentas do pool disponível de Claude enquanto uma skill está ativa, liste-as em disallowed-tools no frontmatter da skill. A restrição é limpa quando você envia sua próxima mensagem. Como regras de negação, o campo não pode remover EndConversation enquanto qualquer outra ferramenta permanecer. Para bloquear ferramentas em todas as skills e prompts, adicione regras de negação em suas configurações de permissão.

Passar argumentos para skills

Você e Claude podem passar argumentos ao invocar uma skill. Argumentos estão disponíveis via placeholder $ARGUMENTS. Esta skill corrige um problema do GitHub por número. O placeholder $ARGUMENTS é substituído por qualquer coisa que siga o nome da skill:
Quando você executa /fix-issue 123, Claude recebe “Fix GitHub issue 123 following our coding standards…” Se você invocar uma skill com argumentos mas nenhum placeholder no conteúdo da skill recebe um, Claude Code anexa ARGUMENTS: <your input> ao final do conteúdo da skill para que Claude ainda veja o que você digitou. Um placeholder é $ARGUMENTS, uma forma indexada como $1 ou um argumento nomeado. Um placeholder indexado sem argumento em sua posição permanece como texto literal e não conta como recebendo um. Um placeholder nomeado conta mesmo quando sua posição não tem argumento, porque se expande para uma string vazia. Você também pode empilhar várias skills no início de uma mensagem. Digitar /write-tests /fix-issue 123 carrega ambas as skills e passa o texto final 123 como $ARGUMENTS para cada uma delas. Antes da v2.1.199, apenas a primeira skill carregava e recebia /fix-issue 123 como texto de argumento literal. Claude Code expande a primeira skill mais até cinco mais empilhadas depois dela. A expansão para no primeiro token que não é uma skill invocável pelo usuário inline, então uma skill que é executada como um subagent bifurcado, como /code-review, ou uma cujos argumentos podem em si começar com um comando slash, como /loop, também termina a execução lá. Esse token e tudo depois dele se tornam o texto de argumento para cada skill expandida. /code-review é executado como um subagent bifurcado a partir da v2.1.218; em versões anteriores era executado inline e empilhado. Para acessar argumentos individuais por posição, use $ARGUMENTS[N] ou o mais curto $N:
Executar /migrate-component SearchBar JavaScript TypeScript substitui $ARGUMENTS[0] com SearchBar, $ARGUMENTS[1] com JavaScript e $ARGUMENTS[2] com TypeScript. A mesma skill usando a abreviação $N:

Padrões avançados

Injetar contexto dinâmico

A sintaxe !`<command>` executa comandos shell antes do conteúdo da skill ser enviado para Claude. A saída do comando substitui o espaço reservado, então Claude recebe dados reais, não o comando em si. Claude Code não executa esses comandos em sua máquina quando a skill é sincronizada de sua conta claude.ai. Esta restrição requer Claude Code v2.1.228 ou posterior. Esta skill resume um pull request buscando dados de PR ao vivo com a CLI do GitHub. Os comandos !`gh pr diff` e outros são executados primeiro, e sua saída é inserida no prompt:
A substituição é executada uma vez sobre o arquivo original. A saída do comando é inserida como texto simples e não é verificada novamente para espaços reservados !`<command>` adicionais, então um comando não pode emitir um espaço reservado para uma passagem posterior expandir. O formulário inline é reconhecido apenas quando ! aparece no início de uma linha ou imediatamente após espaço em branco. Se ! segue outro caractere, como em KEY=!`cmd`, o espaço reservado é deixado como texto literal e o comando não é executado. Para comandos de múltiplas linhas, use um bloco de código cercado aberto com ```! em vez do formulário inline:
Para desabilitar esse comportamento para skills e comandos personalizados de fontes de usuário, projeto, plugin ou additional-directory, defina "disableSkillShellExecution": true em settings. Cada comando é substituído por [shell command execution disabled by policy] em vez de ser executado. Skills agrupadas e gerenciadas não são afetadas. Esta configuração é mais útil em managed settings, onde os usuários não podem substituí-la. Claude Code nunca executa esses comandos em sua máquina quando aparecem em skills sincronizadas de sua conta claude.ai, independentemente desta configuração. Esta restrição requer Claude Code v2.1.228 ou posterior. How Claude Code handles the body of a synced skill diz o que Claude recebe no lugar do comando em cada tipo de sessão.
Para solicitar raciocínio mais profundo quando uma skill é executada, inclua ultrathink em qualquer lugar no conteúdo da skill. Veja Use ultrathink for one-off deep reasoning.

Como comandos injetados são executados

Claude Code escolhe a ferramenta que executa os comandos injetados de uma skill a partir da chave shell no frontmatter da skill e seu ambiente. Cada combinação executa os comandos através da ferramenta Bash ou da ferramenta PowerShell, exceto uma que falha na invocação completamente:
  • shell: powershell, com a ferramenta PowerShell habilitada: os comandos são executados através da ferramenta PowerShell.
  • shell: bash quando bash não está disponível: a invocação falha antes de qualquer comando ser executado. Isso acontece no Windows sem Git Bash. Claude Code mostra Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found.
  • Qualquer outra combinação: os comandos são executados através da ferramenta Bash quando bash está disponível. Quando não está, eles são executados através da ferramenta PowerShell.
Qualquer ferramenta executa os comandos da mesma forma que executa os próprios comandos shell de Claude. Eles compartilham o diretório de trabalho, timeout e tratamento de saída:
  • Diretório de trabalho: Claude Code executa cada comando no diretório de trabalho atual do shell da sessão. Esse diretório se move quando Claude executa cd. Use ${CLAUDE_SKILL_DIR} ou ${CLAUDE_PROJECT_DIR} em caminhos que devem ser resolvidos da mesma forma sempre.
  • stderr: com o shell bash padrão, Claude Code mescla stderr em stdout. Qualquer coisa que o comando escreva em stderr aparece no texto injetado.
  • Timeout: cada comando é executado sob o timeout padrão de 2 minutos da ferramenta Bash. Quando a ferramenta Bash move um comando com timeout para o background, a skill ainda é renderizada. O texto injetado relata a mudança e nomeia a tarefa em background e o arquivo coletando a saída do comando. Quando o comando é um que a ferramenta Bash nunca coloca automaticamente em background, Claude Code o mata no timeout. Essa falha aborta a invocação.
  • Tamanho da saída: saída além do limite inline da ferramenta Bash chega como um caminho de arquivo mais uma visualização curta, não texto truncado. Output limits cobre o limite e como ajustar cada limite.
A ferramenta PowerShell aplica o mesmo comportamento de timeout, backgrounding e output-ceiling aos comandos que executa. Veja a seção ferramenta PowerShell para seus detalhes.

Quando um comando injetado falha

Um comando que falha aborta toda a invocação da skill, não apenas seu próprio espaço reservado. Claude nunca vê o conteúdo da skill para essa invocação. O aborto mostra Shell command failed for pattern "...". A mensagem de erro inclui a saída do comando sob [stderr]. Com o shell bash padrão, qualquer código de saída diferente de zero conta como uma falha. Uma exceção se aplica: Claude Code trata o código de saída 1 de search and comparison commands como um resultado normal e injeta sua saída. Códigos de saída de 2 ou superior falham mesmo para esses comandos. Quais comandos recebem a exceção depende do shell:
  • Shell bash padrão: os comandos listados em Output limits
  • shell: powershell, quando a ferramenta PowerShell está habilitada: um conjunto diferente que inclui grep e git diff mas não find ou diff
Com o shell bash padrão, acrescente || true a qualquer outro comando que você espera sair com código diferente de zero. Um script de verificação que sai com 1 quando encontra problemas é um exemplo.

Verificações de permissão em comandos injetados

Comandos injetados nunca solicitam permissão enquanto a skill é renderizada. Claude Code verifica cada um contra suas regras de permissão primeiro. Um comando que uma regra de negação corresponde aborta a invocação com Shell command permission check failed for pattern "...". Fora do modo automático, quando a verificação de permissão de um comando retorna qualquer coisa diferente de permitir, Claude Code aborta a invocação com o mesmo erro. Isso inclui uma regra que normalmente perguntaria. Para evitar que um comando não correspondido aborte aqui, pré-aprove-o com allowed-tools. Regras de negação e pergunta ainda substituem allowed-tools. Veja Manage permissions. No modo automático, um comando que de outra forma precisaria de sua aprovação não aborta a invocação. A skill carrega com uma instrução dizendo a Claude para executar o comando primeiro, e a própria chamada de Claude passa pelas verificações usuais do modo automático. A invocação ainda aborta em uma skill bifurcada que define agent, e em uma sessão onde Claude não tem a ferramenta shell que executa comandos injetados.

Executar skills em um subagente

Adicione context: fork ao seu frontmatter quando você quiser que uma skill seja executada em isolamento. Claude Code inicia um novo subagente do tipo definido no campo agent e lhe fornece o conteúdo da skill como seu prompt. O subagente não vê seu histórico de conversa, então as instruções da skill têm que se sustentar por si mesmas.
Apesar do nome, uma skill com context: fork não é executada em um fork da conversa atual, que entregaria ao subagente tudo o que você discutiu até agora. Quando a tarefa depende desse histórico, bifurque a conversa em vez de usar context: fork.
O subagente bifurcado é executado em background: você continua trabalhando enquanto ele é executado, e seu resultado chega em sua conversa quando é concluído. Defina background: false no frontmatter para esperar o resultado na volta que invocou a skill. Antes da v2.1.218, skills bifurcadas sempre bloqueavam a volta até serem concluídas. Claude Code também espera pelo resultado, mesmo quando a skill não define background: false, em casos como estes:
  • Em modo não-interativo, com a flag -p ou o Agent SDK
  • Quando você define CLAUDE_CODE_DISABLE_BACKGROUND_TASKS para 1, o que também desativa todos os outros recursos de tarefa em background
  • Quando você invoca uma skill bifurcada enquanto uma invocação anterior da mesma skill ainda está em execução
  • Quando uma scheduled task dispara com a skill como seu prompt
Um fork em background também é executado com o conjunto de ferramentas mais estreito que se aplica a subagentes em background: o subagente da skill é um tipo de agente regular, então a isenção para subagentes que bifurcam a conversa não o cobre. Se as etapas de sua skill dependem de uma ferramenta fora desse conjunto, defina background: false para manter o conjunto completo de ferramentas. Uma skill bifurcada que é executada em background aplica suas edições fora dos checkpoints de sua sessão, então /rewind não as desfaz; use git para revertê-las.
context: fork só faz sentido para skills com instruções explícitas. Se sua skill contém diretrizes como “use essas convenções de API” sem uma tarefa, o subagente recebe as diretrizes mas nenhum prompt acionável, e retorna sem saída significativa.
Skills e subagentes trabalham juntos em duas direções: Com context: fork, você escreve a tarefa em sua skill e escolhe um tipo de agente para executá-la. Os agentes Explore e Plan integrados pulam CLAUDE.md e git status para manter seu contexto pequeno, então uma skill bifurcada usando agent: Explore vê apenas o conteúdo SKILL.md e o prompt do sistema do agente. Para o inverso, onde você define um subagente personalizado que usa skills como material de referência, veja Subagentes.

Exemplo: Skill de pesquisa usando agente Explore

Esta skill executa pesquisa em um agente Explore bifurcado. O conteúdo da skill se torna a tarefa, e o agente fornece ferramentas somente leitura otimizadas para exploração de codebase:
Quando esta skill é executada:
  1. Um novo contexto isolado é criado
  2. O subagente recebe o conteúdo da skill como seu prompt (as instruções “Research $ARGUMENTS thoroughly”)
  3. O campo agent determina o ambiente de execução (modelo, ferramentas e permissões)
  4. O subagente resume seus resultados e os retorna para sua conversa principal quando termina
O campo agent especifica qual configuração de subagente usar. As opções incluem agentes integrados (Explore, Plan, general-purpose) ou qualquer subagente personalizado de .claude/agents/. Se omitido, usa general-purpose.

Restringir acesso de Claude às skills

Por padrão, Claude pode invocar qualquer skill que não tenha disable-model-invocation: true definido. Skills que definem allowed-tools concedem a Claude acesso a essas ferramentas sem aprovação por uso durante a volta que invoca a skill; a concessão é limpa quando você envia sua próxima mensagem. Suas configurações de permissão ainda governam o comportamento de aprovação de linha de base para todas as outras ferramentas. Alguns comandos integrados também estão disponíveis através da ferramenta Skill, incluindo /init e /security-review. Outros comandos integrados como /compact não estão. Três maneiras de controlar quais skills Claude pode invocar: Desabilitar todas as skills negando a ferramenta Skill em /permissions:
Permitir ou negar skills específicas usando regras de permissão:
Sintaxe de permissão: Skill(name) para correspondência exata, Skill(name *) para correspondência de prefixo com quaisquer argumentos. Em uma regra allow, um prefixo fora do namespace reservado para skills sincronizadas não corresponde aos nomes dentro dele: Skill(anthropic *) não cobre anthropic-skills:pdf. Se sua regra deny nomeia um alias ou um nome não qualificado em vez do nome da própria skill, Claude Code ainda bloqueia a skill: com Skill(review) bloqueia o /code-review agrupado através de seu alias /review, e com Skill(deploy) bloqueia uma skill aninhada listada como apps/web:deploy através de seu nome não qualificado. Antes da v2.1.260, Claude Code não bloqueava uma skill aninhada listada sob seu nome qualificado quando a regra deny nomeava apenas o nome não qualificado. Claude Code corresponde uma regra allow apenas contra o nome da própria skill e o nome na invocação de Claude. Para aprovar uma skill sincronizada sem um prompt, nomeie-a dentro de seu namespace reservado: Skill(anthropic-skills:pdf) aprova a skill sincronizada pdf, e Skill(anthropic-skills *) aprova cada skill sincronizada. Ocultar skills individuais adicionando disable-model-invocation: true ao seu frontmatter. Isso remove a skill do contexto de Claude completamente.
Com user-invocable: false, você não pode invocar a skill, mas Claude ainda pode. Para evitar que Claude a invoque através da ferramenta Skill, defina disable-model-invocation: true.

Substituir visibilidade de skill a partir de configurações

A configuração skillOverrides controla a visibilidade de skill a partir de suas configurações em vez do frontmatter da própria skill. Use-a para skills cujo SKILL.md você não quer editar, como aquelas verificadas em um repositório de projeto compartilhado. O menu /skills escreve para você: destaque uma skill e pressione Space para alternar estados, depois Esc para salvar em .claude/settings.local.json. Cada chave é um nome de skill e cada valor é um de quatro estados: O menu /skills rotula o estado "user-invocable-only" como user-only. A partir da v2.1.199, "off" também oculta a skill das listas de comandos anunciadas para clientes Remote Control e para chamadores Agent SDK, além do menu / do terminal. Invocar uma skill oculta pelo seu nome completo ainda retorna o erro skillOverrides em vez de executá-la. Uma skill ausente de skillOverrides é tratada como "on". O exemplo abaixo colapsa uma skill para seu nome e desativa outra completamente:
Algumas skills agrupadas têm aliases, como checkup para /doctor. Se você definir uma entrada skillOverrides sob um alias em managed settings ou em um arquivo que você passa com a flag --settings, Claude Code a aplica à skill atrás do alias. Você só pode restringir uma skill ainda mais através de um alias, nunca torná-la mais visível, e se você também definir uma entrada sob o nome da própria skill em managed settings, essa entrada tem precedência. Antes da v2.1.260, Claude Code não aplicava uma entrada sob um alias à skill em nenhuma fonte de configurações. Em configurações de usuário, projeto e local, Claude Code corresponde entradas apenas contra nomes de skills. Se você definir uma entrada para review lá, ela se aplica a uma skill nomeada review, não ao /code-review agrupado através de seu alias /review. Skills de plugin não são afetadas por skillOverrides. Gerencie-as através de /plugin em vez disso.

Encontrar skills não utilizadas

Cada skill na listagem de skills adiciona ao seu contexto em cada volta, independentemente de Claude nunca usá-la. Execute /skill-doctor para ver o que cada uma de suas skills custa e com que frequência é usada, para que você possa decidir quais desativar. Em uma sessão interativa, o relatório abre na aba Stats do gerenciador /plugin. Em modo não-interativo com -p, Claude Code o imprime como texto. O relatório cobre as skills em sua sessão além de skills agrupadas e skills empresariais. Ele sinaliza skills na listagem que nunca foram invocadas e diz onde desativá-las. Das skills que ele diz onde desativar, comece com as que têm o maior custo de contexto. O relatório também lista plugins que você não usou recentemente. /skill-doctor requer Claude Code v2.1.252 ou posterior e não está disponível em sessões que pulam feature-flag fetching. Se você executar /skill-doctor sobre Remote Control de seu telefone ou navegador, Claude Code responde Skill usage reports are not available on this connection. em vez disso. Execute /skill-doctor no terminal na máquina onde a sessão está em execução.

Avaliar e iterar em uma skill

Ver uma skill ser acionada informa que Claude a encontrou, não que ela fez o que você pretendia. Para saber que uma skill está funcionando, meça separadamente se Claude a invoca nos prompts que deveria, e se a saída corresponde ao que você espera quando o faz. A verificação de ambas é uma comparação de linha de base. Colete alguns prompts realistas, execute cada um em uma sessão nova com a skill disponível e novamente com ela desabilitada, e compare os resultados. Uma sessão nova é importante porque o contexto restante da autoria da skill mascarará lacunas nas instruções escritas. Duas ferramentas automatizam essa comparação. Para uma skill que é entregue em um plugin, claude plugin eval executa cada prompt em uma sessão isolada com e sem o plugin, a classifica com avaliadores que você define ou que ela escreve para você, e sai com código não-zero abaixo de um limite para que você possa bloquear CI nela. Para iterar em uma única skill dentro de uma conversa Claude Code, o plugin skill-creator abaixo executa um loop similar com seu próprio formato evals/evals.json. Os dois formatos não são intercambiáveis.

Executar evals com skill-creator

O plugin skill-creator automatiza o loop de comparação dentro do Claude Code. Instale-o do marketplace oficial:
Se a instalação falhar, corresponda à mensagem que Claude Code relata:
  • Marketplace "claude-plugins-official" not found: adicione o marketplace com /plugin marketplace add anthropics/claude-plugins-official, depois tente novamente a instalação.
  • O plugin não foi encontrado no marketplace: verifique o nome do plugin.
Se o resumo da instalação relatar Run /reload-plugins to activate., Claude Code então executa esse reload para você. Se o reload avisar que sua próxima mensagem releria a conversa, execute /reload-plugins --force para disponibilizar as skills do plugin na sessão atual. Depois peça ao Claude para avaliar uma skill existente, por exemplo evaluate my summarize-changes skill with skill-creator. O plugin o orienta através da escrita de casos de teste e executa o loop:
  • Casos de teste: armazena prompts, arquivos de entrada e comportamento esperado em evals/evals.json dentro do diretório da skill
  • Execuções isoladas: gera um subagent por caso de teste para que cada execução comece com um contexto limpo, e registra contagem de tokens e duração
  • Classificação: verifica cada asserção contra a saída e escreve aprovado ou reprovado com evidência em grading.json
  • Benchmark: agrega taxa de aprovação, tempo e tokens para com-skill versus sem-skill em benchmark.json para que você possa comparar a melhoria da taxa de aprovação contra a sobrecarga de token e tempo
  • Comparação de versão: executa um A/B cego entre duas versões da skill para que você possa confirmar que uma edição é uma melhoria antes de confirmá-la
  • Ajuste de descrição: gera prompts de deve-acionar e não-deve-acionar, mede a taxa de acerto e propõe edições de descrição quando a skill é acionada em solicitações erradas
  • Visualizador de revisão: abre um relatório HTML onde você inspeciona cada saída e registra feedback qualitativo que a próxima iteração lê
Para o formato do arquivo eval e o fluxo de trabalho de iteração completo, consulte Evaluating skill output quality em agentskills.io. Para informações sobre o benchmark e modos de comparação, consulte o skill-creator announcement.

Compartilhar skills

Skills podem ser distribuídas em diferentes escopos dependendo do seu público:
  • Project skills: Faça commit de .claude/skills/ para controle de versão
  • Plugins: Crie um diretório skills/ em seu plugin
  • Managed: Implante em toda a organização através de managed settings

Gerar saída visual

Skills podem agrupar e executar scripts em qualquer linguagem, dando ao Claude capacidades além do que é possível em um único prompt. Um padrão é gerar saída visual: arquivos HTML interativos que abrem em seu navegador para explorar dados, depurar ou criar relatórios. Este exemplo cria um explorador de codebase: uma visualização de árvore interativa onde você pode expandir e recolher diretórios, ver tamanhos de arquivo em um relance e identificar tipos de arquivo por cor. Crie o diretório Skill:
Salve isto em ~/.claude/skills/codebase-visualizer/SKILL.md. A descrição diz ao Claude quando ativar este Skill, e as instruções dizem ao Claude para executar o script agrupado. O caminho do script usa ${CLAUDE_SKILL_DIR} para que seja resolvido corretamente se a skill estiver instalada no nível pessoal, de projeto ou de plugin:
Salve isto em ~/.claude/skills/codebase-visualizer/scripts/visualize.py. Este script varre uma árvore de diretórios e gera um arquivo HTML independente com:
  • Uma barra lateral de resumo mostrando contagem de arquivos, contagem de diretórios, tamanho total e número de tipos de arquivo
  • Um gráfico de barras dividindo o codebase por tipo de arquivo (top 8 por tamanho)
  • Uma árvore recolhível onde você pode expandir e recolher diretórios, com indicadores de tipo de arquivo codificados por cor
O script requer Python 3 mas usa apenas bibliotecas integradas, então não há pacotes para instalar:
Para testar, abra Claude Code em qualquer projeto e peça “Visualize this codebase.” Claude executa o script, que imprime o caminho do arquivo gerado, como Generated /path/to/codebase-map.html, e o abre em seu navegador. Se você trabalha em um ambiente sem interface gráfica onde nenhum navegador abre, o caminho impresso confirma que o script foi bem-sucedido. Este padrão funciona para qualquer saída visual: gráficos de dependência, relatórios de cobertura de testes, documentação de API ou visualizações de esquema de banco de dados. O script agrupado faz o trabalho enquanto Claude lida com a orquestração.

Troubleshooting

Skill não é acionada

Se Claude não usar sua skill quando esperado:
  1. Verifique se a descrição inclui palavras-chave que os usuários naturalmente diriam
  2. Verifique se a skill aparece em What skills are available?
  3. Tente reformular sua solicitação para corresponder mais closely à descrição
  4. Invoque-a diretamente com /skill-name se a skill for invocável pelo usuário
Se o YAML do frontmatter estiver malformado, Claude Code carrega o corpo da skill com metadados vazios, então /skill-name ainda funciona, mas Claude não pode corresponder contra sua description. Execute com --debug para ver o erro de análise. Se a skill é fornecida em um plugin, você pode medir com que frequência ela é acionada em prompts realistas em vez de verificar uma de cada vez: escreva um caso de eval com um tool_used: Skill grader e execute-o com claude plugin eval após cada mudança de descrição. Para encontrar arquivos SKILL.md cujo frontmatter não é analisado, execute claude plugin validate no diretório de skills, por exemplo claude plugin validate .claude/skills para skills de projeto ou claude plugin validate ~/.claude/skills para skills pessoais. Requer Claude Code v2.1.233 ou posterior.

Skill é acionada com muita frequência

Se Claude usar sua skill quando você não quer:
  1. Torne a descrição mais específica
  2. Adicione disable-model-invocation: true se você quiser apenas invocação manual

Descrições de skill são cortadas

Claude Code carrega uma listagem de nomes e descrições de skills no contexto para que Claude saiba o que está disponível. A listagem sempre contém todos os nomes de skills, mas se você tiver muitas skills, Claude Code encurta as descrições para se ajustar ao orçamento de caracteres da listagem, o que pode remover as palavras-chave que Claude precisa para corresponder sua solicitação. O orçamento é dimensionado em 1% da janela de contexto do modelo. Quando a listagem excede o limite, Claude Code remove descrições começando com as skills que você invoca menos, então as skills que você usa mais mantêm seu texto completo. Execute /doctor para uma estimativa do custo de contexto da listagem e seus maiores contribuidores. Para encontrar skills que valem a pena desativar, execute /skill-doctor. Quando a listagem excede seu orçamento, Claude Code também escreve um aviso no log de depuração, visível com --debug. A linha Skills em /context relata o tamanho da listagem após o orçamento ser aplicado, então corresponde ao que o modelo recebe. Antes da v2.1.196, a linha contava o texto completo de cada descrição e poderia mostrar um valor várias vezes maior que o orçamento configurado. Para aumentar o orçamento, defina a configuração skillListingBudgetFraction (por exemplo, 0.02 = 2%) ou a variável de ambiente SLASH_COMMAND_TOOL_CHAR_BUDGET para uma contagem de caracteres fixa. Para liberar orçamento para outras skills, defina entradas de baixa prioridade como "name-only" em skillOverrides para que elas apareçam na listagem sem uma descrição. Você também pode aparar o texto description e when_to_use na fonte: coloque o caso de uso principal primeiro, já que o texto combinado de cada entrada é limitado a 1.536 caracteres independentemente do orçamento. O limite é configurável com skillListingMaxDescChars.

Personal skills desapareceram

Se as pastas de skills que você criou em ~/.claude/skills/ desapareceram, procure em ~/.claude/skills/.trash/. Quando Claude Code sincroniza skills do claude.ai, ele as baixa na subpasta separada synced e não move ou deleta as pastas que você cria. Antes da v2.1.280, um arquivo chamado manifest.json em ~/.claude/skills/ fazia com que Claude Code movesse as pastas de skills que esse arquivo listava para uma pasta com timestamp em ~/.claude/skills/.trash/, e essas skills paravam de carregar. Para restaurar uma skill, mova sua pasta da pasta com timestamp de volta para ~/.claude/skills/. Faça isso antes da limpeza de retenção deletar entradas de lixo, por padrão 30 dias após serem movidas para a lixeira.
  • Depure sua configuração: diagnostique por que uma skill não está aparecendo ou sendo acionada
  • Avaliando a qualidade de saída de skill: o formato do arquivo eval e fluxo de trabalho de iteração em agentskills.io
  • Melhores práticas de autoria de skill: orientação de escrita que se aplica em produtos Claude
  • Subagents: delegue tarefas para agents especializados
  • Plugins: empacote e distribua skills com outras extensões
  • Hooks: automatize fluxos de trabalho em torno de eventos de ferramentas
  • Memory: gerencie arquivos CLAUDE.md para contexto persistente
  • Comandos: referência para comandos integrados e skills agrupadas
  • Permissões: controle acesso a ferramentas e skills
  • Claude Tag skills: skills de projeto confirmadas em um repositório também são carregadas quando esse repositório é usado em um canal Claude Tag