Estender Claude com skills

Crie, gerencie e compartilhe skills para estender as capacidades do Claude no Claude Code. Inclui comandos personalizados e skills agrupadas.

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.

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.

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.

Execute suas verificações antes de cada commit

Quando uma sessão começa com uma skill chamada verify ou simplify disponível, as instruções de commit do Claude Code dizem ao Claude para executá-la logo antes de cada commit, exceto para alterações em documentação ou testes. Isso requer Claude Code v2.1.286 ou posterior. Claude recebe essa instrução quando estas condições são atendidas no início da sessão:

• Local: a skill é carregada a partir do local corporativo, pessoal, de projeto ou de diretório adicional, ou de um arquivo .claude/commands/ com esse nome. A receita que /verify registra na raiz do seu repositório é uma skill de projeto, então ela conta. O /verify e o /simplify incluídos, skills de plugins e skills da sua conta claude.ai não contam.
• Invocação: Claude pode invocar a skill. Se você impediu o Claude de invocá-la, por exemplo com disable-model-invocation: true, Claude não recebe a instrução.
• Instruções do Git: você não desativou includeGitInstructions. Desativá-la remove essa instrução junto com o restante das instruções integradas de commit e PR.

Trabalhe em projetos da Claude API

A skill agrupada /claude-api carrega material de referência da Claude API e Managed Agents para a linguagem do seu projeto. Claude também a ativa automaticamente quando seu código importa anthropic ou @anthropic-ai/sdk.

Para iniciar um dos fluxos de trabalho da skill, digite um subcomando após o nome da skill no prompt do Claude Code, por exemplo /claude-api migrate. A tabela lista o que cada subcomando faz e a versão mais antiga do Claude Code que o inclui. migrate e managed-agents-onboard antecedem v2.1.221, a versão mais antiga que a tabela rastreia.

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.

mkdir -p ~/.claude/skills/summarize-changes

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

What did I change?

/summarize-changes

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 incluídas, comandos integrados 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:

• O frontmatter se aplica em cada tipo de sessão, então uma concessão allowed-tools passa pelo fluxo de permissão normal. Se sua organização definir allowManagedPermissionRulesOnly, a concessão não se aplica.
• 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

As skills são configuradas por meio do frontmatter YAML no topo do SKILL.md e do conteúdo markdown que vem em seguida.

Tipos de conteúdo de skill

Os arquivos de skill podem conter quaisquer instruções, mas pensar em como você deseja invocá-las ajuda a orientar o que incluir:

Conteúdo de referência adiciona conhecimento que o Claude aplica ao seu trabalho atual. Convenções, padrões, guias de estilo, conhecimento de domínio. Esse conteúdo é executado inline para que o Claude possa usá-lo junto com o contexto da sua conversa.

---
name: api-conventions
description: API design patterns for this codebase
---

When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation

Conteúdo de tarefa fornece ao Claude instruções passo a passo para uma ação específica, como deploys, commits ou geração de código. Geralmente são ações que você deseja invocar diretamente com /skill-name em vez de deixar o Claude decidir quando executá-las. Adicione disable-model-invocation: true para impedir que o Claude a acione automaticamente. O exemplo abaixo adiciona context: fork, que executa a skill em seu próprio contexto de subagente; consulte Executar skills em um subagente.

---
name: deploy
description: Deploy the application to production
context: fork
disable-model-invocation: true
---

Deploy the application:
1. Run the test suite
2. Build the application
3. Push to the deployment target

Mantenha o corpo em si conciso. Depois que uma skill é carregada, seu conteúdo permanece no contexto ao longo dos turnos, então cada linha é um custo recorrente de tokens. Declare o que fazer em vez de narrar como ou por quê, e aplique o mesmo teste de concisão que você aplicaria ao conteúdo do CLAUDE.md.

Referência do frontmatter

Configure uma skill com frontmatter YAML entre marcadores --- no topo do SKILL.md e escreva as instruções da skill em Markdown após o --- de fechamento. Os nomes dos campos usam palavras em minúsculas separadas por hifens, exceto when_to_use. Um arquivo de comando em .claude/commands/ aceita os mesmos campos, exceto name e paths. Este exemplo define quatro campos:

---
name: my-skill
description: What this skill does
disable-model-invocation: true
allowed-tools: Read Grep
---

Your skill instructions here...

Todos os campos são opcionais. Apenas description é recomendado para que o Claude saiba quando usar a skill. O nome de um campo deve corresponder exatamente à tabela, incluindo hifens: o Claude Code ignora um campo que não reconhece sem relatar um erro.

O Claude Code lê o frontmatter somente quando o --- de abertura é a primeira linha do arquivo. Caso contrário, ele trata o arquivo inteiro, incluindo os marcadores ---, como conteúdo da skill. Se o YAML entre os marcadores não puder ser analisado, a skill ainda é carregada sem nenhum campo definido; consulte Skill não é acionada para encontrar e corrigir o erro.

Campos booleanos aceitam yes, no, on, off, 1 e 0 com qualquer combinação de maiúsculas e minúsculas, além de true e false. Antes da v2.1.218, o Claude Code reconhecia apenas true e false.

Usar o frontmatter de skills fora do Claude Code

O Claude Code aceita todos os campos da tabela acima. Fora do Claude Code, você pode usar apenas os campos da especificação Agent Skills:

Quando você habilita uma skill pessoal para sua conta do claude.ai, por exemplo para usá-la em sessões do Cowork e na nuvem e em rotinas, você a envia para o claude.ai, então as mesmas regras se aplicam.

Se você incluir qualquer campo que a especificação não permite, o empacotamento ou o upload falha com um erro grave em vez de ignorar o campo:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

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 API de Skills definem todo o resto que esses caminhos validam. Recursos de corpo exclusivos do Claude Code, como a injeção de contexto dinâmico, não funcionam no chat do claude.ai nem pela API. O Claude Code aceita todos os seis campos, então um frontmatter que segue a especificação é carregado 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 do local onde o arquivo da skill está e, para diretórios de skills e skills de plugins, do campo name do frontmatter. Em um diretório de skills pessoal ou de projeto, name define o comando que o menu / exibe 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.

A tabela abaixo mostra de onde vem o nome do comando para cada estrutura:

Em uma skill de plugin, o name do frontmatter 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 /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, o 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é a v2.1.245, o Claude Code duplicava o prefixo quando o name já o continha.

Em sessões não interativas, os nomes help e feedback não são reservados para seus comandos integrados exclusivos do terminal, então uma skill de plugin com um desses nomes mantém seu comando simples nessas sessões. O nome de todos os outros comandos integrados exclusivos do terminal, como /login, permanece reservado, mesmo que o comando não possa ser executado nessas sessões.

Para um SKILL.md na raiz do plugin, não há diretório de skill de onde obter o nome, então name fornece todo o segmento final. Sem um campo name, o Claude Code usa o nome do diretório do plugin como fallback.

Substituições de string disponíveis

As skills suportam substituição de strings para valores dinâmicos no conteúdo da skill:

O Claude Code substitui ${CLAUDE_SKILL_DIR} e ${CLAUDE_PROJECT_DIR} em dois lugares: no conteúdo markdown da skill e nas regras de Bash no frontmatter allowed-tools. Em uma skill de plugin, o Claude Code substitui ${CLAUDE_PLUGIN_ROOT} e ${CLAUDE_PLUGIN_DATA} nesses mesmos dois lugares. Usar a mesma variável em ambos os lugares permite que uma skill execute um script incluído sem um prompt de permissão. A skill a seguir mostra o padrão:

---
name: render-chart
description: Render a chart from a CSV file
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *)
---

Run `${CLAUDE_SKILL_DIR}/scripts/render.sh <csv-file>` to render the chart.

Se esta skill estiver instalada em ~/.claude/skills/render-chart/, ambas as ocorrências de ${CLAUDE_SKILL_DIR} se expandem para esse diretório. A regra de allowed-tools então corresponde exatamente ao comando que o corpo da skill instrui o Claude a executar, então o script é executado sem solicitar confirmação.

A substituição de ${CLAUDE_PROJECT_DIR} requer Claude Code v2.1.196 ou posterior.

Os argumentos indexados usam aspas no estilo shell, então coloque valores com várias palavras entre 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 completa de argumentos conforme digitada.

Um placeholder indexado sem argumento correspondente, como $2 quando apenas um argumento foi passado, permanece inalterado no conteúdo. Um placeholder nomeado do frontmatter arguments sem argumento correspondente se expande para uma string vazia.

Se você passar um valor de argumento que contém texto como $1 ou $ARGUMENTS, o 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", o Claude recebe Summarize $ARGUMENTS from yesterday. O 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, de ARGUMENTS ou de um nome de argumento declarado, como $1.00 em texto corrido, escape-o com uma barra invertida: \$1.00. Uma barra invertida antes de qualquer outro $ permanece inalterada. Apenas uma única barra invertida diretamente antes do token o escapa. Uma barra invertida dupla, como \\$1, mantém ambas as barras invertidas, e $1 ainda se expande para o valor do argumento. O escape com barra invertida cobre apenas esses placeholders de argumentos. Uma barra invertida não impede a substituição de uma variável ${CLAUDE_*} onde a variável se aplica.

Exemplo usando substituições:

---
name: session-logger
description: Log activity for this session
---

Log the following to logs/${CLAUDE_SESSION_ID}.log:

$ARGUMENTS

Adicionar arquivos de apoio

As skills podem incluir vários arquivos em seu diretório. Isso mantém o SKILL.md focado no essencial, enquanto permite que o Claude acesse material de referência detalhado somente quando necessário. Documentos de referência grandes, especificações de API ou coleções de exemplos não precisam ser carregados no contexto toda vez que a skill é executada.

my-skill/
├── SKILL.md (required - overview and navigation)
├── reference.md (detailed API docs - loaded when needed)
├── examples.md (usage examples - loaded when needed)
└── scripts/
    └── helper.py (utility script - executed, not loaded)

Referencie os arquivos de apoio a partir do SKILL.md para que o Claude saiba o que cada arquivo contém e quando carregá-lo:

## Additional resources

- For complete API details, see [reference.md](/anthropic/claude-code/history/docs/pt/2026-10-02-2259..2026-10-03-1200/reference/)
- For usage examples, see [examples.md](/anthropic/claude-code/history/docs/pt/2026-10-02-2259..2026-10-03-1200/examples/)

Controlar quem invoca uma skill

Por padrão, tanto você quanto o Claude podem invocar qualquer skill. Você pode digitar /skill-name para invocá-la diretamente, e o Claude pode carregá-la automaticamente quando for relevante para sua conversa. Dois campos do frontmatter permitem restringir isso:

• disable-model-invocation: true: Somente você pode invocar a skill. Use para fluxos de trabalho com efeitos colaterais ou cujo momento você deseja controlar, como /commit, /deploy ou /send-slack-message. Você não quer que o Claude decida fazer deploy só porque seu código parece pronto.

• user-invocable: false: Somente o Claude pode invocar a skill. Use para conhecimento de fundo que não é acionável como comando. Uma skill legacy-system-context explica como um sistema antigo funciona. O Claude deve saber disso quando for relevante, mas /legacy-system-context não é uma ação significativa para os usuários executarem.

Este exemplo cria uma skill de deploy que somente você pode acionar. Se você definir disable-model-invocation: true, o Claude não poderá executar a skill automaticamente:

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

Deploy $ARGUMENTS to production:

1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

Se o Claude tentar mesmo assim, o Claude Code bloqueia a chamada e o instrui a não reproduzir as etapas de deploy de outra forma, então espere que o Claude sugira que você mesmo execute /deploy.

Veja como os dois campos afetam a invocação e o carregamento de contexto:

Ciclo de vida do conteúdo da skill

Quando você ou o Claude invocam uma skill, o conteúdo renderizado do SKILL.md entra na conversa como uma única mensagem e permanece lá nos turnos seguintes. Essa persistência se aplica às instruções da skill, não às suas permissões: uma concessão de allowed-tools é removida quando você envia sua próxima mensagem. O Claude Code não relê o arquivo da skill em turnos posteriores, então escreva as orientações que devem se aplicar ao longo de uma tarefa como instruções permanentes, e não como etapas únicas.

Quando o Claude invoca novamente uma skill cujo conteúdo renderizado é idêntico à cópia já presente no contexto, o Claude Code adiciona uma breve nota de 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 de contexto dinâmico produziu uma nova saída, o Claude Code anexa o conteúdo completo novamente.

A compactação automática mantém as skills invocadas dentro de um orçamento de tokens. Quando a conversa é resumida para liberar contexto, o Claude Code reanexa a invocação mais recente de cada skill após o resumo, mantendo os primeiros 5.000 tokens de cada uma. As skills reanexadas compartilham um orçamento combinado de 25.000 tokens. O Claude Code preenche esse orçamento começando pela skill invocada mais recentemente, então skills mais antigas podem ser descartadas inteiramente após a compactação se você tiver invocado muitas em uma sessão.

Se o Claude parar de seguir uma skill no meio de uma sessão, consulte O Claude para de seguir uma skill.

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 o Claude possa usá-las sem solicitar sua aprovação. A concessão é removida quando você envia sua próxima mensagem, mesmo que o conteúdo da skill permaneça no contexto; invocar a skill novamente a reaplica para aquele turno. Ele não restringe quais ferramentas estão disponíveis: todas as ferramentas continuam podendo ser chamadas, e suas configurações de permissão ainda regem as ferramentas não listadas. Para pré-aprovar ferramentas para a sessão inteira em vez de um único turno, adicione regras allow a essas configurações de permissão.

A confiança no workspace não restringe esse campo. O Claude Code aplica o allowed-tools de uma skill de projeto mesmo em uma execução -p em uma pasta na qual você nunca confiou. Uma skill pode conceder a si mesma amplo acesso a ferramentas, então revise o allowed-tools das skills incluídas em um repositório antes de executar o Claude Code nele. Para ignorar o campo nas skills de repositórios em toda a sua organização, consulte Quando apenas regras de permissão gerenciadas se aplicam.

Esta skill permite que o Claude execute comandos git sem aprovação a cada uso sempre que você a invoca:

---
name: commit
description: Stage and commit the current changes
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

Para remover ferramentas do conjunto disponível do Claude enquanto uma skill está ativa, liste-as em disallowed-tools no frontmatter da skill. A restrição é removida quando você envia sua próxima mensagem. Assim como as regras deny, o campo não pode remover EndConversation enquanto qualquer outra ferramenta permanecer. Para bloquear ferramentas em todas as skills e prompts, adicione regras deny nas suas configurações de permissão.

Quando apenas regras de permissão gerenciadas se aplicam

Quando sua organização define allowManagedPermissionRulesOnly nas configurações gerenciadas, o Claude Code ignora allowed-tools em skills de projeto e pessoais e nas outras fontes listadas na entrada da configuração. Isso requer Claude Code v2.1.282 ou posterior.

As ferramentas que uma skill afetada lista passam, em vez disso, pelas regras gerenciadas da sua organização e pelo prompt de permissão normal. Execute /status para listar cada skill cujo allowed-tools o Claude Code ignorou até o momento na sessão. Um comando injetado na skill que nenhuma regra gerenciada permite segue Verificações de permissão em comandos injetados.

Passar argumentos para skills

Tanto você quanto o Claude podem passar argumentos ao invocar uma skill. Os argumentos ficam disponíveis por meio do placeholder $ARGUMENTS.

Esta skill corrige uma issue do GitHub pelo número. O placeholder $ARGUMENTS é substituído pelo que vier depois do nome da skill:

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit

Quando você executa /fix-issue 123, o 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 receber um, o Claude Code anexa ARGUMENTS: <your input> ao final do conteúdo da skill para que o 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 tendo recebido um. Um placeholder nomeado conta mesmo quando sua posição não tem argumento, porque ele 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.

O Claude Code expande a primeira skill mais até cinco outras empilhadas depois dela. A expansão para no primeiro token que não seja uma skill inline invocável pelo usuário, então uma skill que é executada como um subagente bifurcado, como /code-review, ou uma cujos argumentos podem começar com um comando de barra, como /loop, também encerra a sequência ali. Esse token e tudo o que vem depois dele se tornam o texto de argumentos para cada skill expandida. /code-review é executada como um subagente bifurcado a partir da v2.1.218; em versões anteriores, ela era executada inline e empilhada.

Para acessar argumentos individuais por posição, use $ARGUMENTS[N] ou a forma mais curta $N:

---
name: migrate-component
description: Migrate a component from one language to another
---

Migrate the $ARGUMENTS[0] component from $ARGUMENTS[1] to $ARGUMENTS[2].
Preserve all existing behavior and tests.

Executar /migrate-component SearchBar JavaScript TypeScript substitui $ARGUMENTS[0] por SearchBar, $ARGUMENTS[1] por JavaScript e $ARGUMENTS[2] por TypeScript. A mesma skill usando a forma abreviada $N:

---
name: migrate-component
description: Migrate a component from one language to another
---

Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.

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:

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request...

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:

## Environment
```!
node --version
git status --short
```

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.

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 auto, quando a verificação de permissão de um comando retorna qualquer coisa diferente de allow, Claude Code aborta a invocação com o mesmo erro. Isso inclui uma regra que normalmente perguntaria a você. Para evitar que um comando não correspondido aborte aqui, pré-aprove-o com allowed-tools. Se sua organização restringe as regras de permissão às configurações gerenciadas, veja Quando apenas regras de permissão gerenciadas se aplicam. Regras deny e ask ainda sobrescrevem 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.

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.

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:

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:

1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

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 o turno 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:

# Add to deny rules:
Skill

Permitir ou negar skills específicas usando regras de permissão:

# Allow only specific skills
Skill(commit)
Skill(review-pr *)

# Deny specific skills
Skill(deploy *)

Sintaxe de permissão: Skill(name) para correspondência exata, Skill(name *) para correspondência de prefixo com quaisquer argumentos.

A tabela mostra o que uma regra deny bloqueia além do nome que você escreve, pelo tipo de nome na regra.

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
• Skill(anthropic-skills *) aprova cada skill sincronizada
• Skill(anthropic *) não cobre anthropic-skills:pdf, porque um prefixo fora do namespace não corresponde aos nomes dentro dele

Ocultar skills individuais adicionando disable-model-invocation: true ao seu frontmatter. Isso remove a skill do contexto de Claude completamente.

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.

"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 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:

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

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.

Como você desabilita a skill para a segunda execução depende de onde ela vem:

• Skill pessoal ou de projeto: defina-a como "off" em skillOverrides.
• Skill que um plugin fornece: skillOverrides não se aplica a skills de plugin. Use claude plugin eval em vez disso, que repete cada execução sem nenhum plugin carregado.

Duas ferramentas automatizam a comparação de linha de base. 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. Na extensão do VS Code ou no aplicativo desktop, instale-o do marketplace oficial seguindo Instalar um plugin. Em um terminal, inicie o Claude Code executando claude e, em seguida, digite isto no prompt dele:

/plugin install skill-creator@claude-plugins-official

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:

mkdir -p ~/.claude/skills/codebase-visualizer/scripts

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:

---
name: codebase-visualizer
description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.
allowed-tools: Bash(python3 *)
---

# Codebase Visualizer

Generate an interactive HTML tree view that shows your project's file structure with collapsible directories.

## Usage

Run the visualization script from your project root:

```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py .
```

This creates `codebase-map.html` in the current directory and opens it in your default browser.

## What the visualization shows

- **Collapsible directories**: Click folders to expand/collapse
- **File sizes**: Displayed next to each file
- **Colors**: Different colors for different file types
- **Directory totals**: Shows aggregate size of each folder

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:

#!/usr/bin/env python3
"""Generate an interactive collapsible tree visualization of a codebase."""

import json
import sys
import webbrowser
from html import escape
from pathlib import Path
from collections import Counter

IGNORE = {'.git', 'node_modules', '__pycache__', '.venv', 'venv', 'dist', 'build'}

def scan(path: Path, stats: dict) -> dict:
    result = {"name": path.name, "children": [], "size": 0}
    try:
        for item in sorted(path.iterdir()):
            if item.name in IGNORE or item.name.startswith('.'):
                continue
            if item.is_file():
                size = item.stat().st_size
                ext = item.suffix.lower() or '(no ext)'
                result["children"].append({"name": item.name, "size": size, "ext": ext})
                result["size"] += size
                stats["files"] += 1
                stats["extensions"][ext] += 1
                stats["ext_sizes"][ext] += size
            elif item.is_dir():
                stats["dirs"] += 1
                child = scan(item, stats)
                if child["children"]:
                    result["children"].append(child)
                    result["size"] += child["size"]
    except PermissionError:
        pass
    return result

def generate_html(data: dict, stats: dict, output: Path) -> None:
    ext_sizes = stats["ext_sizes"]
    total_size = sum(ext_sizes.values()) or 1
    sorted_exts = sorted(ext_sizes.items(), key=lambda x: -x[1])[:8]
    colors = {
        '.js': '#f7df1e', '.ts': '#3178c6', '.py': '#3776ab', '.go': '#00add8',
        '.rs': '#dea584', '.rb': '#cc342d', '.css': '#264de4', '.html': '#e34c26',
        '.json': '#6b7280', '.md': '#083fa1', '.yaml': '#cb171e', '.yml': '#cb171e',
        '.mdx': '#083fa1', '.tsx': '#3178c6', '.jsx': '#61dafb', '.sh': '#4eaa25',
    }
    lang_bars = "".join(
        f'<div class="bar-row"><span class="bar-label">{ext}</span>'
        f'<div class="bar" style="width:{(size/total_size)*100}%;background:{colors.get(ext,"#6b7280")}"></div>'
        f'<span class="bar-pct">{(size/total_size)*100:.1f}%</span></div>'
        for ext, size in sorted_exts
    )
    def fmt(b):
        if b < 1024: return f"{b} B"
        if b < 1048576: return f"{b/1024:.1f} KB"
        return f"{b/1048576:.1f} MB"

    html = f'''<!DOCTYPE html>
<html><head>
  <meta charset="utf-8"><title>Codebase Explorer</title>
  <style>
    body {{ font: 14px/1.5 system-ui, sans-serif; margin: 0; background: #1a1a2e; color: #eee; }}
    .container {{ display: flex; height: 100vh; }}
    .sidebar {{ width: 280px; background: #252542; padding: 20px; border-right: 1px solid #3d3d5c; overflow-y: auto; flex-shrink: 0; }}
    .main {{ flex: 1; padding: 20px; overflow-y: auto; }}
    h1 {{ margin: 0 0 10px 0; font-size: 18px; }}
    h2 {{ margin: 20px 0 10px 0; font-size: 14px; color: #888; text-transform: uppercase; }}
    .stat {{ display: flex; justify-content: space-between; padding: 8px 0; border-bottom: 1px solid #3d3d5c; }}
    .stat-value {{ font-weight: bold; }}
    .bar-row {{ display: flex; align-items: center; margin: 6px 0; }}
    .bar-label {{ width: 55px; font-size: 12px; color: #aaa; }}
    .bar {{ height: 18px; border-radius: 3px; }}
    .bar-pct {{ margin-left: 8px; font-size: 12px; color: #666; }}
    .tree {{ list-style: none; padding-left: 20px; }}
    details {{ cursor: pointer; }}
    summary {{ padding: 4px 8px; border-radius: 4px; }}
    summary:hover {{ background: #2d2d44; }}
    .folder {{ color: #ffd700; }}
    .file {{ display: flex; align-items: center; padding: 4px 8px; border-radius: 4px; }}
    .file:hover {{ background: #2d2d44; }}
    .size {{ color: #888; margin-left: auto; font-size: 12px; }}
    .dot {{ width: 8px; height: 8px; border-radius: 50%; margin-right: 8px; }}
  </style>
</head><body>
  <div class="container">
    <div class="sidebar">
      <h1>📊 Summary</h1>
      <div class="stat"><span>Files</span><span class="stat-value">{stats["files"]:,}</span></div>
      <div class="stat"><span>Directories</span><span class="stat-value">{stats["dirs"]:,}</span></div>
      <div class="stat"><span>Total size</span><span class="stat-value">{fmt(data["size"])}</span></div>
      <div class="stat"><span>File types</span><span class="stat-value">{len(stats["extensions"])}</span></div>
      <h2>By file type</h2>
      {lang_bars}
    </div>
    <div class="main">
      <h1>📁 {escape(data["name"])}</h1>
      <ul class="tree" id="root"></ul>
    </div>
  </div>
</body></html>'''
    output.write_text(html)

if __name__ == '__main__':
    target = Path(sys.argv[1] if len(sys.argv) > 1 else '.').resolve()
    stats = {"files": 0, "dirs": 0, "extensions": Counter(), "ext_sizes": Counter()}
    data = scan(target, stats)
    out = Path('codebase-map.html')
    generate_html(data, stats, out)
    print(f'Generated {out.absolute()}')
    webbrowser.open(f'file://{out.absolute()}')

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

Claude para de seguir uma skill

Se Claude segue uma skill em sua primeira resposta e para de segui-la depois, comece com qualquer um desses casos que corresponda:

• Claude pulou uma regra que deve ser mantida o tempo todo: mova a regra para um hook. Claude Code executa um hook toda vez que seu evento ocorre, como antes de cada edição de arquivo, independentemente de Claude estar seguindo a skill ou não. Para manter a regra com a skill, defina o hook no frontmatter hooks da skill. Esse hook se aplica desde o momento em que a skill é invocada até o final da sessão.
• Claude pulou orientação que deveria aplicar com julgamento: reformule a orientação para que se aplique à tarefa inteira, por exemplo "Execute os testes após cada edição" em vez de "Execute os testes". Claude Code adiciona o conteúdo da skill à conversa quando a skill é invocada e não relê o arquivo em turnos posteriores.
• A conversa foi compactada: invoque a skill novamente para restaurar seu conteúdo completo. Após compactação, Claude Code pode manter apenas o início de uma skill invocada, então coloque as instruções mais importantes perto do topo de SKILL.md.

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.

Recursos relacionados

• 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