Skills dos Agentes (Agent Skills): Equipando o Claude com Habilidades Especializadas

📚 Navegação da Série: O artigo anterior 25 Sistema de Memória abordou a "retenção passiva de fatos"—como salvar preferências e convenções do projeto no CLAUDE.md para evitar perguntas redundantes. Este artigo explora a "capacitação funcional ativa": como empacotar rotinas operacionais completas como Agent Skills, permitindo que o Claude chame a habilidade correta no momento certo.

“Será que uma Skill é apenas um comando slash com outro nome? Se eu digitar /deploy ele roda o deploy, qual a diferença em relação ao antigo .claude/commands/deploy.md?”

“A diferença é enorme. Um comando slash é executado apenas quando você o chama de forma explícita; uma Skill, por outro lado, pode ser ativada silenciosamente pelo Claude se a tarefa atual for compatível com a sua descrição. Além disso, ela ocupa apenas o espaço de uma linha no seu contexto inicial, expandindo-se apenas sob demanda.”

“...Ativada dinamicamente? Mas isso não geraria bagunça? Como vou saber quando ela será acionada?”

Esse é um mal-entendido comum que eu mesmo tive no início—coloquei um comando commit.md existente dentro de .claude/skills/ e, como a execução parecia idêntica à anterior, pensei: "isso é só uma mudança de diretório". Com o tempo percebi que o erro estava em tratar as Skills apenas como atalhos para comandos slash. Na verdade, os comandos personalizados foram consolidados no ecossistema de Skills—seus arquivos em .claude/commands/ continuam funcionais, mas o formato de Skill adiciona três vantagens: suporte a arquivos auxiliares, acionamento automático pelo Claude sob demanda e consumo quase nulo de tokens na janela de contexto.

Nota Oficial: "Comandos personalizados foram mesclados às skills. O arquivo em .claude/commands/deploy.md e a skill em .claude/skills/deploy/SKILL.md criarão o comando /deploy e funcionarão da mesma maneira."

Neste artigo, explicaremos detalhadamente o que são as Skills, como elas são acionadas sob demanda sem congestionar a janela de contexto, suas fontes de carregamento e como ativá-las.

Ao terminar este artigo, você obterá:

• O conceito real de uma Skill—um arquivo SKILL.md com recursos complementares que estende as capacidades do Claude
• Como funciona o carregamento sob demanda (revelação progressiva): o segredo para economizar tokens mantendo instruções compactas até o acionamento
• O comparativo de finalidades entre Skills, comandos slash e Subagents em uma tabela prática (as chaves de escolha serão detalhadas no Artigo 30)
• As origens das Skills (nativas, integradas em plugins ou customizadas por você) e como o diretório escolhido define o escopo de uso
• Métodos de acionamento (delegação automática por description sem necessidade de memorizar comandos) e como listar as habilidades ativas

---

01 Primeiro entenda: O que realmente é uma Skill

Conclusão direta: Uma Skill é composta estruturalmente por um manifesto SKILL.md acompanhado de arquivos complementares opcionais, empacotados como uma habilidade especializada entregue ao Claude.

Analogia: Atalhos de automação no smartphone. Ao configurar uma automação "Modo Chegar em Casa" no celular—que acende luzes, ajusta o ar-condicionado e toca música—você não executa cada etapa individualmente; basta um comando de voz para rodar a sequência. As Skills operam sob essa mesma premissa: você consolida uma rotina de execução (como "listar modificações locais pendentes e inspecionar riscos de segurança") no arquivo SKILL.md, transformando-a em uma rotina que o Claude executa autonomamente, sem a necessidade de você detalhar as instruções em cada conversa.

Qual a estrutura de um SKILL.md? Ele divide-se em duas seções principais, como demonstrado no exemplo oficial a seguir (salvo no caminho ~/.claude/skills/summarize-changes/SKILL.md, onde o nome da pasta summarize-changes atua como o comando de ativação):

---
description: Resume modificações não commitadas e aponta riscos de segurança. Usado quando o usuário pergunta sobre alterações locais, solicita mensagens de commit ou pede revisão de diffs.
---

## Modificações Atuais

!`git diff HEAD`

## Instruções

Resuma as modificações em dois ou três pontos principais e liste eventuais riscos identificados, como tratamento de erros ausente, chaves fixadas no código ou necessidade de atualização de testes. Se o diff estiver vazio, informe que não há alterações pendentes.

O bloco superior delimitado por --- é o YAML frontmatter (metadados de cabeçalho), que indica ao Claude a finalidade da Skill e quando utilizá-la; o texto em Markdown abaixo representa as instruções de execução a serem seguidas no acionamento.

Observe o trecho !`git diff HEAD`—este é um mecanismo de injeção dinâmica de contexto: o Claude Code executa o comando local do terminal primeiro, substituindo o resultado diretamente no arquivo antes de enviá-lo ao modelo. Assim, o Claude recebe os dados prontos das modificações locais reais daquele instante, reduzindo etapas de processamento.

Uma Skill pode conter múltiplos arquivos estruturados em um diretório. O modelo padrão recomendado na documentação segue esta árvore:

my-skill/
├── SKILL.md           # Instruções principais (Obrigatório)
├── template.md        # Modelos de saída opcionais
├── examples/
│   └── sample.md      # Exemplos de saídas esperadas de referência
└── scripts/
    └── validate.sh    # Scripts de execução auxiliares

Apenas o SKILL.md é obrigatório; o restante é opcional. Essa é a grande vantagem estrutural em relação aos comandos slash clássicos: suporte a modelos, exemplos e scripts executáveis em qualquer linguagem—deixando a execução complexa para os scripts e o gerenciamento lógico para o Claude.

Três cenários práticos onde as Skills se mostram úteis:

• Padronização de rotinas: se a cada commit você digita instruções repetitivas ("execute testes, elabore a mensagem e use o prefixo feat")—empacote isso na Skill commit e acione com um comando simples.
• Convenções de estilo: para manter a padronização de APIs na equipe (regras RESTful, estrutura de respostas de erro e validações)—escreva a Skill api-conventions para guiar a codificação automaticamente.
• Relatórios visuais: para gerar gráficos estruturais do repositório—a Skill oficial codebase-visualizer empacota um script Python que, ao ser concluído, abre uma árvore estrutural interativa no seu navegador.

💡 Resumo em uma frase: Uma Skill reúne o manifesto SKILL.md (regras de uso e instruções) e arquivos complementares de suporte—permitindo execuções automatizadas consistentes com suporte a templates e scripts.

---

02 O segredo: Revelação progressiva (Progressive Disclosure) para economia de contexto

Este é o conceito estrutural mais relevante do artigo. Como o Claude gerencia dezenas de Skills instaladas sem esgotar a janela de contexto? A resposta reside na revelação progressiva (progressive disclosure—carregamento sob demanda que oculta o texto completo de rotinas inativas).

A janela de contexto do Claude é limitada (Artigo 19). Cada caractere processado consome tokens e reduz a precisão lógica do modelo. Se o texto completo de todas as Skills ativas fosse injetado no boot de toda conversa, a memória útil seria congestionada rapidamente.

Analogia: O cardápio do restaurante. Ao sentar-se à mesa, você recebe o menu—contendo apenas nomes de pratos e resumos de preços. Se você decidir pedir o "Filé com Fritas", o cozinheiro buscará a receita detalhada de preparo na cozinha. As receitas dos outros pratos não solicitados permanecem guardadas, sem ocupar espaço físico na sua mesa. As Skills seguem essa mesma lógica:

• Em espera: o Claude lê apenas a linha de description de cada Skill disponível (o menu).
• Sob demanda: quando sua pergunta é compatível com uma descrição específica, as instruções completas daquela Skill são carregadas no chat (a receita).

A documentação oficial resume esse comportamento de forma clara:

Em uma conversa regular, as descrições das skills são carregadas no contexto para que o Claude saiba o que está disponível, mas o conteúdo completo da skill é carregado apenas no momento da chamada.

Portanto, você pode adicionar checklists detalhados e manuais extensos no escopo das suas Skills—elas não consumirão tokens até serem invocadas. Essa é a razão de a documentação sugerir modularizar regras operacionais em Skills em vez de concentrar tudo no CLAUDE.md (que é carregado de forma integral no boot).

A imagem ilustra os dois estágios da revelação progressiva: à esquerda, três Skills ativas ocupam apenas suas respectivas linhas de description no contexto; à direita, quando uma das descrições é acionada, as instruções completas desse item específico são carregadas, mantendo as demais minimizadas no console.

Contudo, há uma propriedade importante que você deve considerar: uma vez ativada, as instruções da Skill permanecem residentes na janela de contexto até o fim da conversa (o Claude não as limpa entre chamadas). Citação oficial:

Quando você ou o Claude invocam uma skill, o conteúdo apresentado do SKILL.md é inserido no chat como uma mensagem comum e permanece lá pelo restante da conversa.

Isso resulta em duas práticas sugeridas: primeiro, mantenha as instruções no SKILL.md objetivas para economizar tokens persistentes (recomenda-se manter o tamanho do arquivo abaixo de 500 linhas, movendo referências longas para subarquivos externos); segundo, estruture o conteúdo como "diretrizes contínuas de desenvolvimento" em vez de "passos temporários de execução única"—já que o texto permanecerá legível para o modelo nas rodadas seguintes.

Um erro clássico que costuma ocorrer: ao criar uma Skill longa, notar que o Claude deixa de seguir suas diretrizes após algumas rodadas de chat. A primeira reação costuma ser achar que houve erro de carregamento e reiniciar a sessão. Na verdade, as instruções continuam carregadas no contexto, mas o modelo desviou o foco para outras ferramentas. A solução é estruturar a descrição (description) de forma mais nítida e direcionada para manter a aderência lógica do modelo.

💡 Resumo em uma frase: A revelação progressiva mantém as Skills minimizadas em descrições breves no console até serem acionadas; uma vez ativadas, permanecem ativas na conversa, exigindo instruções limpas e focadas.

---

03 Skills, comandos slash e Subagents: Entendendo a diferença

Esta seção visa desfazer confusões comuns entre esses três recursos. Embora pareçam similares na execução, suas propostas operacionais são distintas. Detalharemos os critérios de escolha no Artigo 30, focando aqui em diferenciar seus escopos.

Alinhando os conceitos básicos:

• Comandos slash: rotinas executadas exclusivamente sob ação manual iniciada por você através da tecla /.
• Skills: blocos de funcionalidades que podem ser invocados manualmente ou delegados de forma autônoma pelo Claude.
• Subagents (Subagentes): assistentes isolados com janela de contexto independente, que processam tarefas em segundo plano e retornam apenas resumos de resultados (Artigo 23).

Para desfazer o mal-entendido inicial: comandos slash e Skills não são conflitantes—o comando é apenas uma interface de acionamento manual de uma Skill. O Claude Code mesclou os dois conceitos: criar uma Skill chamada commit disponibiliza nativamente o comando /commit. A diferença real reside no escopo de controle de acionamento e tokens:

Propriedade	Comandos slash clássicos (.claude/commands/)	Skills	Subagents
Iniciador	Apenas você (via console)	Você ou o Claude (delegação automática)	Assistente principal
Contexto	Sessão de chat activa	Sessão de chat ativa (padrão)	Janela isolada dedicada
Custo em espera	—	Apenas a linha de description	Inexistente (iniciado sob demanda)
Arquivos de suporte	Não	Sim (templates, scripts, exemplos)	Conforme definições internas
Caso de uso ideal	Controle estrito de execução de tarefas manuais	Automações integradas que o modelo aplica livremente	Tarefas isoladas complexas ou de alta poluição de logs

Esta tabela esclarece o dilema: um comando slash é simplesmente a invocação manual de uma Skill; a grande vantagem é que o Claude Code permite que o modelo decida quando acionar a Skill autonomamente baseando-se no contexto.

Esse acionamento autônomo pode ser restrito? Sim, você tem controle total sobre as chaves de invocação usando parâmetros no frontmatter do arquivo:

• disable-model-invocation: true: bloqueia o acionamento pelo Claude. Útil para ações com impactos externos ou que exijam validação humana estrita—como scripts de deploy, gravação de commits ou envio de alertas. Isso evita execuções autônomas indesejadas pelo modelo.
• user-invocable: false: bloqueia o acionamento manual. Recomendado para Skills informativas—como documentações de regras de legado legacy-system-context que servem de guias de raciocínio para o modelo, mas não possuem finalidade prática como comandos no terminal.

Portanto, o comportamento é totalmente customizável: use disable-model-invocation: true para prender a execução exclusivamente ao acionamento manual do usuário.

💡 Resumo em uma frase: Comandos slash e acionamentos automáticos são duas faces da mesma infraestrutura de Skills, enquanto Subagents isolam o processamento; defina disable-model-invocation: true para restringir execuções apenas ao console manual.

---

04 Origens de carregamento das Skills

De onde o Claude Code carrega as habilidades ativas? A infraestrutura mapeia três origens distintas:

1. Nativas (Bundled Skills): já integradas na instalação do Claude Code. Incluem utilitários de sistema como /code-review (revisão de arquivos), /debug (depuração automática), /batch (execução em lote), /loop (repetição de rotinas de testes) e /claude-api (documentação de endpoints). Além de utilitários como /run (validação de build), /verify (testes de inicialização) e /run-skill-generator (gerador de automação de testes). Elas ficam visíveis no menu flutuante do console.

Nota: as Skills nativas diferem de comandos internos básicos como /help ou /compact. Comandos internos executam trechos de rotinas estáticas locais; as Skills nativas funcionam alimentadas por instruções lógicas de contexto—guiando o modelo a orquestrar suas ferramentas nativas del console. A sintaxe de uso é a mesma para ambas.

2. Empacotadas em Plugins: trazidas a partir de instalações de terceiros (Artigo 24). Ao salvar a pasta skills/ no escopo de um plugin, suas instruções tornam-se ativas no repositório correspondente. Essas Skills usam namespaces estruturados no formato nome-do-plugin:nome-da-skill (como /my-plugin:review), evitando conflitos de nomenclatura com arquivos locais.

3. Customizadas por você (Custom Skills): a modalidade ideal para estender suas rotinas. Salve instruções repetitivas, guias de estilo ou procedimentos em um manifesto SKILL.md para transformá-los em habilidades permanentes. A documentação oficial sugere uma regra simples:

Crie uma skill quando notar que está colando repetidamente as mesmas instruções, checklists ou fluxos de execução no chat, ou quando partes do CLAUDE.md começarem a descrever fluxos procedimentais em vez de informações estáticas.

Isso define claramente a fronteira com o CLAUDE.md: o CLAUDE.md guarda "fatos estáticos" (arquitetura do projeto, pilhas de desenvolvimento), enquanto as Skills armazenam "procedimentos lógicos" (passo a passo de tarefas). Se notar que está redigindo listas de tarefas ou roteiros operacionais no CLAUDE.md, migre-os para uma Skill.

Mapeamento prático para tomada de decisão:

Contexto de trabalho	❌ Abordagem Ineficiente	✅ Solução com Skill
Passos repetitivos a cada commit do git	Redigitar a mesma instrução no terminal toda vez	Salvar uma Skill chamada commit para invocar com um comando
Padronização de estrutura de APIs da equipe	Acumular guias extensas no CLAUDE.md consumindo tokens permanentes	Criar uma Skill dedicada para carregamento exclusivo sob demanda
Geração periódica de relatórios complexos	Descrever os parâmetros e passos de geração a cada sprint	Empacotar scripts e referências de saída em uma Skill

💡 Resumo em uma frase: As Skills são divididas em nativas, importadas de plugins e customizadas locais; o gatilho para escrever uma nova Skill é a repetição manual de tarefas no chat.

---

05 Organização de arquivos, acionamento e diagnóstico

Esta seção trata das configurações de armazenamento no disco, das lógicas de comparação de descrições e de comandos de auditoria.

Escopos de diretórios no disco

A localização física do manifesto define quem pode acessá-lo. Siga esta tabela de referência:

Escopo	Localização	Usuários autorizados
User (Global)	~/.claude/skills/<nome-da-skill>/SKILL.md	Disponível para o seu usuário em qualquer projeto
Project (Local)	.claude/skills/<nome-da-skill>/SKILL.md	Ativo apenas no projeto atual (pode ser versionado no git)
Plugin	<plugin>/skills/<nome-da-skill>/SKILL.md	Escopo de uso do respectivo plugin (usa namespace)
Enterprise	Conforme diretrizes corporativas	Disponível para todos os membros da organização

A lógica de escopo é simples: rotinas gerais de uso individual (como padrões de commit do seu usuário) devem ser salvas no nível global ~/.claude/skills/; diretrizes e ferramentas da equipe para o repositório (como scripts de homologação) devem ser salvas no diretório local .claude/skills/ para versionamento com o time.

Precedência de colisão de nomes: Enterprise > Global (User) > Local (Project) (namespaces de plugins não colidem). Um aviso crítico de segurança: Skills locais obtidas de repositórios externos acionam o aviso de confiança do Workspace (Workspace Trust) no console de terceiros—já que os parâmetros em allowed-tools podem liberar privilégios. Revise os manifestos de Skills antes de conceder permissões a repositórios públicos.

Mecanismo de acionamento por descrições

Esta é a grande comodidade do sistema: não há necessidade de decorar comandos /nome-da-skill rígidos. O Claude avalia suas solicitações em linguagem natural com a description das Skills registradas e carrega as instruções corretas automaticamente.

Tomando a Skill summarize-changes (Seção 01) como referência—com descrição mapeando termos como "alterações locais"—ambas as entradas a seguir são válidas:

O que eu modifiquei localmente?

/summarize-changes

O primeiro caso representa a delegação automática (onde a intenção é capturada sem comandos diretos); o segundo representa a invocação manual. Priorize o acionamento por intenção no dia a dia. Isso realça a importância de redigir descrições claras (description): elas devem incluir palavras-chave que você usaria em uma conversa de chat padrão. Caso uma Skill falhe em ser ativada autonomamente, revise os termos da descrição.

Certifique-se de que a descrição contenha palavras-chave que os usuários usariam de forma natural.

Mapeamento de Skills ativas

Para auditar quais habilidades estão ativas no seu console, pergunte ao Claude no terminal:

Quais skills estão disponíveis no momento?

O console retornará a listagem completa de itens indexados. Essa auditoria é útil para validar se um novo manifesto Markdown foi registrado pelo sistema. Você também pode inspecionar os comandos via teclado digitando /, ou executar /doctor para verificar se descrições de Skills foram abreviadas para economizar contexto (se houver dezenas de Skills, as descrições podem ser reduzidas, enfraquecendo o acionamento por intenção).

💡 Resumo em uma frase: Use ~/.claude/skills/ para escopo global e .claude/skills/ para escopo local; a delegação é guiada por termos da description; use a pergunta Quais skills estão disponíveis? para auditar os registros.

---

06 Prática: Criando uma Skill simples e testando a delegação em 5 minutos

Nada melhor do que testar na prática. O roteiro a seguir demonstra o carregamento sob demanda e o acionamento por intenção natural no terminal do Claude Code, sem a necessidade de criar scripts executáveis.

Passo 1: Criar a pasta de Skills globais (Windows PowerShell)

New-Item -ItemType Directory -Path "$env:USERPROFILE\.claude\skills\explain-self" -Force

O comando acima cria a subpasta explain-self no diretório de dados global do usuário.

Passo 2: Escrever o manifesto SKILL.md

Com seu editor de código preferido, crie o arquivo no caminho correspondente (por exemplo, C:\Users\seu-usuario\.claude\skills\explain-self\SKILL.md) contendo:

---
description: Explica trechos de código ou mensagens de erro em linguagem simples de forma didática. Usar quando o usuário disser "o que este código faz", "qual o significado deste erro" ou "explique este trecho".
---

## Instruções

Explique o trecho de código ou log de erro fornecido pelo usuário de forma didática e acessível:
1. Descreva o objetivo geral do código em uma frase simples.
2. Explique a lógica linha a linha ou bloco a bloco.
3. Se for um log de erro, aponte a provável causa e como corrigi-la.

Evite termos técnicos excessivos e utilize analogias do cotidiano sempre que possível.

A descrição foi estruturada propositalmente com frases em linguagem natural—que servirão de gatilho para o modelo.

Passo 3: Inicializar o Claude Code e auditar o registro

claude

No console do Claude, digite:

Quais skills estão disponíveis no momento?

Saída esperada: A listagem de habilidades retornará o item explain-self com a respectiva descrição. A indexação confirma o carregamento correto. (Isso demonstra a revelação progressiva: até agora, apenas os metadados de descrição foram consumidos, economizando o contexto das instruções internas).

Passo 4: Chamar a habilidade por intenção natural

Envie uma instrução sem usar o comando com barra, combinando com a descrição da Skill:

O que este código faz: print(sum([1,2,3]) / len([1,2,3]))

Saída esperada: O Claude ativará autonomamente a Skill explain-self (indicado por uma mensagem no console) e formatará a resposta de acordo com os passos solicitados (resumo geral simplificado da média de três valores, divisão de etapas do cálculo e uso de analogias). O acionamento ocorreu de forma transparente baseando-se no contexto.

Passo 5: Testar a invocação manual

Agora teste o acionamento manual do comando:

/explain-self o que significa este erro: ZeroDivisionError: division by zero

Saída esperada: A Skill é acionada da mesma forma e a saída segue o padrão configurado—com a diferença de que a execução foi forçada pelo console manual. As duas vias de chamada funcionam sob o mesmo manifesto de instruções.

Essas etapas comprovam a conveniência dos conceitos de carregamento sob demanda e delegação automática de contexto.

💡 Resumo em uma frase: Crie o arquivo SKILL.md, verifique o registro com Quais skills estão disponíveis? e acione de forma automática e manual—testar esse fluxo demonstra a praticidade de estender as habilidades do seu assistente.

---

07 Resumo

Neste artigo, passamos pelas engrenagens de funcionamento de "Agent Skills"—entendendo como elas capacitam o Claude a portar ferramentas lógicas ativadas de forma modular.

Revisão dos pontos principais:

Dúvida comum	Resposta	Ponto-chave
O que é uma Skill	Manifesto SKILL.md e arquivos de suporte opcional	Cabeçalho YAML define regras de acionamento; Markdown define instruções
Por que economiza contexto	Revelação progressiva	Mantém a Skill em espera no boot e expande instruções apenas na chamada
Diferenças de formato	Propostas distintas	Comandos slash são manuais; Subagents isolam a janela de histórico
Origens de carga	Nativas, plugins de terceiros ou desenvolvidas por você	Automatize rotinas repetitivas que você cola no chat frequentemente
Organização e uso	Diretório físico determina o escopo	O Claude delega via descrição; audite os itens com o comando de listagem

Agora você deve ser capaz de: Descrever a estrutura de arquivos e metadados de uma Skill, compreender a economia de tokens via carregamento sob demanda, identificar a melhor escolha entre Skills e Subagents para automações e testar o registro e acionamento de novas diretrizes lógicas no console. Esse recurso transforma o Claude de um assistente genérico em um especialista alinhado aos padrões e rotinas do seu repositório.

---

No próximo artigo, 27 "Skills em Ação (Skills in Practice)"—com a teoria sedimentada, passaremos para a implementação real: construir uma Skill de produção funcional, acioná-la no terminal e inspecionar a execução de ponta a ponta. Avalie quais rotinas manuais você repete com frequência com o Claude e prepare-se para transformá-las em atalhos simplificados no próximo capítulo.

---

Leitura Recomendada

• Interagindo com navegadores de internet via Chrome
• Configuração de API: gerenciamento de tokens e assinaturas
• Guia de uso do CLAUDE.md: fixando regras persistentes de desenvolvimento