Skills em Ação: Instalando, Chamando e Vendo Funcionar na Prática

📚 Navegação da Série: O artigo anterior 26 O que é uma Skill detalhou a teoria—explicando a estrutura do SKILL.md e como a description define o acionamento pelo Claude. Este artigo parte direto para a prática: vamos listar as habilidades ativas, acionar uma Skill com uma frase simples e monitorar a conclusão da tarefa, transformando a teoria das Skills em prática.

Por exemplo, imagine que precise gerar um diagrama estrutural do repositório para uma apresentação. Normalmente, você teria que estruturar os nós na mente, escrever o código Mermaid, ajustar cores e exportar em PNG—um processo que consumiria facilmente metade do seu dia. Com o Claude Code, basta digitar "desenhe o diagrama de arquitetura deste projeto" e ele fará o trabalho sozinho.

Ele não pedirá parâmetros adicionais; carregará a Skill baoyu-diagram configurada localmente, estruturará o layout de acordo com o design system escuro especificado, gerará o SVG correspondente e o converterá em uma imagem PNG @2x—em menos de cinco minutos, a imagem estará salva no diretório docs/assets/.

Nesse instante, a utilidade real de uma Skill fica evidente: sua finalidade não é tornar o Claude mais inteligente, mas sim garantir que ele execute tarefas de forma padronizada, seguindo um fluxo consistente e confiável. A redução de meio dia de trabalho para os cinco minutos reside nessa rotina predefinida.

Vimos no artigo anterior o conceito básico das Skills. Hoje, vamos focar em uma única meta: colocar esse fluxo de aceleração de trabalho para rodar na prática.

Ao terminar este artigo, você obterá:

• Como listar as Skills indexadas na sessão ativa com uma única pergunta no console
• Uma análise de um manifesto SKILL.md real para entender a correlação entre a descrição e o acionamento
• O fluxo de acionamento por intenção natural e por comando manual / com saídas esperadas de confirmação
• Um roteiro de três etapas de depuração caso a Skill não seja acionada (solicitação vaga, inconsistência de descrição ou falta de indexação)
• Como integrar e versionar Skills locais no projeto para padronizar os fluxos de trabalho da equipe

---

01 Antes de começar: Listando as Skills indexadas no console

O passo inicial não é invocar a Skill, mas sim mapear quais opções estão indexadas no seu console.

Um erro comum é tentar acionar ferramentas por suposições—como solicitar "desenhe o diagrama X" assumindo que a Skill correspondente está ativa, e achar que o sistema falhou ao ver o Claude processar a tarefa de forma padrão. Auditar os registros disponíveis é o melhor primeiro passo.

Analogia: Inspecionar o catálogo antes de cozinhar. Você não tentará preparar um prato complexo sem antes abrir o livro de receitas para confirmar se possui a lista de ingredientes e o passo a passo mapeados. O ecossistema de Skills funciona de forma parecida: o arquivo SKILL.md é a receita estruturada—confirme o registro no catálogo antes de iniciar a execução.

A auditoria é direta; pergunte ao Claude no terminal em linguagem natural:

Quais skills estão disponíveis no momento?

Você pode usar a variação em inglês What skills are available? se preferir. Saída esperada: O Claude retornará a lista completa de Skills indexadas, exibindo o identificador e um resumo de finalidade para cada item. No repositório de testes, o utilitário de diagramas estará mapeado:

baoyu-diagram — Gera diagramas profissionais SVG em tema escuro (arquitetura, fluxogramas, sequência, mapas mentais...)

💡 Resumo em uma frase: Antes de solicitar tarefas especializadas, pergunte Quais skills estão disponíveis? no chat para certificar-se de que a automação desejada foi carregada no ambiente.

Dois utilitários complementares de verificação que vale a pena conhecer:

Menu /skills: digite /skills no terminal para exibir um painel interativo. Ele lista as Skills e permite gerenciar o status de ativação de cada uma (navegue pelos itens, use a tecla Space para alternar a ativação e Enter para salvar), sendo mais visual que a listagem em texto.

Comando /doctor: ferramenta de diagnóstico avançada. Se houver dezenas de Skills instaladas no ambiente, o Claude Code pode reduzir ou cortar descrições para poupar a janela de contexto de boot. O comando /doctor ajuda a auditar se há colisão de limites ou descrições incompletas. Se uma Skill ativa parar de responder à intenção natural, execute /doctor como primeiro teste.

---

02 Anatomia de uma Skill real: O arquivo SKILL.md

Mapear a indexação é importante, mas entender a arquitetura do arquivo ajuda a entender os critérios de comparação lógica usados no acionamento.

Utilizaremos o utilitário baoyu-diagram configurado no repositório local de testes para inspecionar essa estrutura na prática, em vez de recorrer a exemplos teóricos básicos.

Mapeamento dos arquivos no disco:

.claude/skills/baoyu-diagram/
├── SKILL.md              # Manifesto e instruções (Obrigatório)
├── references/           # Manuais detalhados de estilo por tipo de diagrama (Lidos sob demanda)
│   ├── architecture.md
│   ├── flowchart.md
│   └── sequence.md
└── scripts/
    └── main.ts           # Script de conversão de SVG para PNG (Executado no terminal, sem carregar tokens no chat)

A estrutura de diretórios expõe o padrão: a Skill reside em uma pasta modular onde o SKILL.md atua como cabeçalho de inicialização, suportando caminhos de documentação adicionais e scripts externos. O arquivo SKILL.md é mandatório; os subarquivos e subpastas mantêm o manifesto de instruções curto, delegando regras específicas para leitura sob demanda e execuções pesadas para scripts locais.

Ao inspecionar o SKILL.md, a seção inicial delimitada por --- representa os metadados do frontmatter:

---
name: baoyu-diagram
description: Create professional, dark-themed SVG diagrams of any type — architecture diagrams, flowcharts, sequence diagrams... Also trigger when the user says "画个图" "画一个架构图" "diagram" "flowchart"...
version: 1.117.3
---

O bloco Markdown situado abaixo do segundo delimitador --- reúne as diretrizes de desenvolvimento (regras do design system escuro, paleta de cores e comandos de geração de imagens).

Note a regra de acionamento vista no capítulo anterior: a propriedade description funciona como a chave de comparação lógica usada pelo Claude para mapear a intenção da chamada (o cabeçalho do frontmatter suporta o campo complementar when_to_use para cenários complexos; a soma de ambos é limitada a 1536 caracteres).

Observe que a descrição inclui termos associados à intenção de desenho como "desenhar", "diagrama", "fluxograma" e "arquitetura" em diferentes idiomas. A presença dessas palavras-chave serve para que a intenção da chamada natural do usuário seja mapeada com facilidade pelo modelo.

Analogia: As tags de indicação do catálogo. Assim como marcadores em livros ("Ideal para jantares rápidos") ajudam a encontrar receitas adequadas, a description funciona como a tag de mapeamento da Skill—o Claude compara os termos da conversa com as descrições indexadas, carregando o manifesto que apresentar maior compatibilidade lógica.

A árvore de execução lógica do acionamento segue este fluxo:

Instrução do usuário → Comparação pelo Claude com as descrições (description) → Mapeamento de compatibilidade → Carregamento do SKILL.md correspondente → Execução das instruções.

A assertividade do acionamento depende diretamente do alinhamento entre as palavras da descrição e a forma como você se comunica no chat. Caso o acionamento autônomo falhe, revise estes termos.

O diagrama ilustra o ciclo operacional de acionamento em quatro etapas: entrada de texto do usuário → comparação lógica de palavras-chave nas descrições indexadas → carregamento das instruções do SKILL.md correspondente → processamento e entrega do arquivo final no repositório. Essa árvore ajuda a rastrear a origem de eventuais falhas de execução.

💡 Resumo em uma frase: Uma Skill é composta por um diretório contendo o arquivo SKILL.md; a propriedade description mapeia a intenção da chamada e determina o carregamento sob demanda das instruções.

---

03 Prática: Acionando uma Skill por intenção natural

Com o catálogo auditado e a estrutura mapeada, vamos executar o acionamento do baoyu-diagram usando a abordagem mais comum: intenção natural em chat padrão.

Essa é a grande conveniência das Skills: não há sintaxe rígida obrigatória; o Claude detecta a intenção correta e escolhe a ferramenta adequada.

Passo 1: Inicialize o Claude Code na raiz do projeto de teste:

claude

Saída esperada: O console do chat será aberto com o campo de mensagens ativo.

Passo 2: Digite a solicitação de forma direta—observe que não utilizaremos o identificador baoyu-diagram de forma explícita:

Desenhe um diagrama do ciclo de raciocínio "pensar-agir-inspecionar" (think-act-inspect) do Claude

Saída esperada: O Claude associará o termo "diagrama" à description da Skill baoyu-diagram, carregando-a automaticamente no chat. O modelo lerá a documentação de estilo de fluxogramas (references/flowchart.md), aplicará as cores do design system escuro, estruturará os elementos SVG e rodará o script de compilação em imagem PNG @2x.

Ao concluir, o console indicará o caminho dos arquivos gerados no projeto:

Diagramas gerados com sucesso:
  docs/claude-code/assets/27-agent-loop.svg
  docs/claude-code/assets/27-agent-loop@2x.png

A criação desses arquivos confirma o acionamento e a execução da Skill. Todo o fluxo foi gerenciado sem parametrizações manuais.

Abaixo está o comparativo prático entre usar Skills e conduzir chamadas no chat de forma comum:

Fluxo	❌ Sem Skill	✅ Com Skill
Instruções do usuário	Descrever paletas, fontes, dimensões e comandos de conversão em cada conversa	Digitar uma frase simples sobre o objetivo do diagrama
Consistência da saída	Resultados variados de estilo e paletas em cada tentativa	Layouts consistentes alinhados ao design system padrão
Memorização de rotinas	Mapear parâmetros e scripts repetidamente	Nenhuma ação adicional requerida

Em essência, a Skill automatiza etapas repetitivas estruturando diretrizes duradouras. Você solicita o objetivo final, e as regras da Skill gerenciam a formatação técnica.

Invocação manual por comandos slash

Se preferir pular a comparação lógica de intenção do Claude e forçar o uso de uma Skill específica, invoque-a de forma direta pelo console com a tecla /:

/baoyu-diagram desenhar um diagrama de sequência de login de usuário

Saída esperada: O Claude ignora a etapa de comparação da description e carrega o baoyu-diagram instantaneamente, tratando o texto inserido após o comando como a instrução de entrada.

Critério sugerido para escolha do acionamento:

• Fase de pesquisa ou solicitações livres: fale de forma natural e deixe o Claude escolher o assistente (o mapeamento lógico pode encontrar caminhos mais adequados).
• Tarefas estritas ou críticas: utilize comandos slash / manuais, principalmente para ações de escrita ou infraestrutura (como deploys locais, homologação ou commits do git). A documentação sugere usar esse método para evitar acionamentos automáticos indesejados pelo modelo.

💡 Resumo em uma frase: Use intenção natural para delegação autônoma e comandos slash / para execuções manuais forçadas; o primeiro garante flexibilidade de uso, e o segundo assegura controle rígido.

---

04 Diagnóstico: Três passos para resolver falhas de acionamento

Durante o desenvolvimento, é comum notar momentos em que o Claude executa a tarefa no chat de forma comum, ignorando a Skill instalada no diretório. Abaixo estão os três motivos clássicos para essa falha, listados em ordem de recorrência.

Analogia: Receita não executada. O prato não foi preparado porque: as instruções da conversa não foram associadas ao título da receita, o manual do prato não consta na cozinha ou a solicitação inicial foi vaga demais. Isole as etapas para identificar a causa.

Passo 1: Identificar instruções vagas (o motivo mais comum).

Na maioria dos casos, as palavras usadas na conversa não foram associadas aos termos cadastrados na description. Se a Skill mapeia chaves como "diagrama" ou "desenho" e você digita "crie uma representação visual", o Claude pode falhar em associar a intenção à ferramenta.

Solução: Reformule a instrução utilizando verbos e termos idênticos aos cadastrados na description:

Desenhe um diagrama de arquitetura

O uso de termos explícitos como "diagrama" ou "desenhar" eleva as chances de detecção lógica pelo Claude. Esse ajuste costuma resolver a maioria dos casos de falhas de acionamento.

Passo 2: Auditar se a Skill consta no catálogo.

Use a instrução de auditoria vista na Seção 01:

Quais skills estão disponíveis no momento?

Saída esperada: Caso o identificador da Skill não apareça na lista, ela não foi carregada no ambiente (devido a falhas de Workspace Trust, diretório físico incorreto ou ausência de instalação). Nesse cenário, foque em carregar o arquivo no sistema antes de testar novos termos no chat (a Seção 05 detalha a ativação de itens locais de projeto).

Passo 3: Forçar o acionamento manual via / como兜底.

Se o identificador consta na lista e novos termos naturais não surtiram efeito, evite depurações excessivas no chat e force a chamada via console manual /:

/baoyu-diagram desenhar um diagrama de arquitetura

Se o item está indexado, a chamada forçada por / funcionará obrigatoriamente (pois ignora o julgamento lógico do modelo). Essa etapa ajuda a isolar o problema: se o comando / executa com sucesso, a infraestrutura da Skill está correta e o problema reside apenas na falta de palavras-chave adequadas na description.

Mantenha este guia de depuração de três etapas de fácil acesso:

Falha identificada	Auditoria inicial	Solução prática
Claude executa a tarefa sem carregar a Skill	Compatibilidade dos termos da conversa	Reformule a instrução aproximando as chaves de busca da description
Novos termos naturais falham	Presença do identificador no catálogo	Execute Quais skills estão disponíveis?; se ausente, carregue a pasta correspondente
Skill indexada continua inativa	Falha de delegação de intenção	Invoque manualmente usando /nome-da-skill e ajuste as chaves da description posterior

⚠️ Caso ocorra o oposto—acionamentos excessivos (Skills ativando sem necessidade)—a solução é tornar as chaves de busca na description mais restritas, ou configurar o frontmatter com disable-model-invocation: true para restringir o processamento exclusivamente a chamadas manuais /. A edição de manifestos será abordada no próximo artigo.

💡 Resumo em uma frase: Três passos de depuração—reformule os termos do chat, valide a indexação no catálogo e force a chamada via /; essa rotina soluciona a maior parte das falhas de chamadas.

---

05 Compartilhamento em equipe: Versionamento de Skills no projeto

Sabendo utilizar as Skills, resta resolver o escopo de uso: arquivos salvos no diretório global do usuário ~/.claude/skills/ ficam restritos à sua máquina local, indisponíveis para outros desenvolvedores.

Para padronizar rotinas e ferramentas entre todos os membros do time, salve-as no escopo de Skills locais de projeto.

Analogia: O manual da equipe. Em vez de colar o roteiro de tarefas em post-its na sua mesa, salve o arquivo na pasta compartilhada do projeto. Qualquer um que clonar o repositório terá acesso direto às mesmas instruções de build ou deploy. As Skills locais são versionadas junto com o código-fonte.

Comparativo de escopos globais vs locais:

Propriedade	Skill Global (User)	Skill Local (Project)
Localização física	~/.claude/skills/<nome>/SKILL.md	.claude/skills/<nome>/SKILL.md no repositório
Escopo de uso	Apenas o seu usuário em qualquer projeto local	Todos os desenvolvedores que clonarem o repositório
Controle de versão	Ignorado (fora da pasta do repositório)	Sim (comitado no git)
Casos de uso típicos	Atalhos e hábitos pessoais do seu desenvolvedor	Padronizações da equipe (logs, commits, deploys)

Roteiro para implementação em equipe:

Passo 1: Salvar a pasta de Skills locais no repositório (em vez do home do usuário):

seu-projeto/
└── .claude/
    └── skills/
        └── team-commit/
            └── SKILL.md

Passo 2: Comitar as configurações no controle de versão (git):

git add .claude/skills/
git commit -m "feat: adiciona skill team-commit para padronização de mensagens"

Passo 3: Atualizar o ambiente da equipe. Ao clonar o repositório ou executar git pull, as Skills locais estarão imediatamente prontas para uso no console dos outros desenvolvedores, dispensando etapas manuais de instalação. O time passará a gerar diagramas, logs ou commits sob as mesmas diretrizes automaticamente.

Um aviso crítico de segurança do Claude Code: abrir projetos que contenham Skills locais exige a confirmação do aviso de Workspace Trust (Confiança do Workspace) na inicialização. Essa validação existe porque os parâmetros em allowed-tools concedem privilégios ao script. Sempre audite manifestos de Skills em repositórios externos antes de aceitar permissões globais, protegendo seu ambiente local.

Revise as skills do projeto antes de confiar no repositório, pois uma skill pode conceder a si mesma amplo acesso a ferramentas.

Isso deve se tornar um hábito ao importar códigos de repositórios públicos. Antes de conceder confiança, leia os manifestos em .claude/skills/ para verificar se há privilégios amplos concedidos a ferramentas de console (como Bash).

💡 Resumo em uma frase: Padronize rotinas de equipe salvando as Skills em .claude/skills/ com versionamento no git; sempre audite os privilégios solicitados antes de aceitar o Workspace Trust em repositórios de terceiros.

---

06 Prática: Escrevendo e executando uma Skill do zero

Para consolidar o conhecimento, criaremos um manifesto de Skill global básico, validando o fluxo completo de "salvar arquivo → indexar no catálogo → acionar no chat" sem scripts auxiliares.

Nosso objetivo: configurar uma Skill que instrua o Claude a explicar trechos de código em estilo informal de conversa de café.

Passo 1: Criar a pasta global de Skills (PowerShell)

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

O comando cria a subpasta global explain-casual para o seu usuário.

Passo 2: Escrever o manifesto SKILL.md

Com seu editor de código, crie o arquivo SKILL.md na pasta correspondente contendo:

---
description: Explica trechos de código de forma didática com tom de conversa de café. Usar quando o usuário disser "explique este código em termos simples", "o que esta lógica faz" ou "detalhe este método".
---

## Tarefa

Explique o trecho de código fornecido de forma leve, didática e coloquial, como se estivesse conversando com um colega em um café. Evite termos técnicos excessivos:

1. Resuma o objetivo geral do código em uma frase no início.
2. Destaque duas ou três linhas críticas e descreva o funcionamento delas de forma didática.
3. Finalize apontando se há pontos vulneráveis ou passíveis de otimização na estrutura.

Atenção: o campo description foi populado com as frases em linguagem natural que você usaria no chat. Esse alinhamento facilita o mapeamento automático.

Passo 3: Validar a indexação no catálogo. Nota importante: diretórios raiz de Skills criados com o console aberto exigem a reinicialização da sessão para indexação. Feche e abra o console para indexar a pasta explain-casual:

claude

Execute a pergunta de auditoria:

Quais skills estão disponíveis no momento?

Saída esperada: O console retornará a listagem contendo o identificador explain-casual com a respectiva descrição. Isso confirma a carga de arquivos no boot do sistema. (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: Acionar a Skill por intenção natural (sem comandos /):

Explique este código em termos simples:
def average(numbers):
    return sum(numbers) / len(numbers)

Saída esperada: O Claude detectará a intenção, carregará as diretrizes do explain-casual e responderá dividindo a lógica em três pontos: objetivo geral (média simples de valores), detalhamento lógico do cálculo (sum / len) e a observação de vulnerabilidade se a lista fornecida estiver vazia (causando divisão por zero, atendendo ao passo 3 do manual da Skill). O tom de voz será informal.

Passo 5: Testar o acionamento manual via comando /:

/explain-casual def average(numbers): return sum(numbers) / len(numbers)

Saída esperada: A Skill é acionada diretamente, aplicando as mesmas regras de formatação informal sem passar pela comparação lógica de intenções no chat.

Essas cinco etapas completam o fluxo operacional de ponta a ponta: "criação de arquivos → indexação de boot → delegação por intenção → chamada manual". O comportamento de qualquer outra Skill de produção seguirá este mesmo padrão de infraestrutura.

⚠️ Se o identificador explain-casual não constar na lista do Passo 3: verifique se reiniciou o terminal após salvar o diretório (etapa necessária para indexar pastas novas). Se o problema persistir, certifique-se de que o arquivo Markdown chama-se exatamente SKILL.md (em letras maiúsculas).

💡 Resumo em uma frase: Escreva um manifesto simples, reinicie o terminal para indexá-lo no catálogo e teste o acionamento automático no chat—executar esse fluxo ensina a usar qualquer pacote de Skills compartilhado na comunidade.

---

07 Resumo

Revisão das rotinas essenciais:

Objetivo	Comando / Ação	Ponto-chave
Listar Skills ativas	Pergunta natural Quais skills estão disponíveis? ou menu /skills	Certifique-se do registro antes de usar
Inspecionar regras	Ler o arquivo SKILL.md correspondente	O campo description no YAML define a associação de termos
Acionar a automação	Intenção natural no chat ou comando manual /nome-da-skill	Intenção natural para uso flexível e comandos slash para controle estrito
Depurar falhas	Refinar termos → confirmar registro → forçar chamada via /	A maioria das falhas deve-se a palavras-chave vagas
Compartilhar com time	Salvar em .claude/skills/ com comissão no git	Revise chaves de permissão em allowed-tools antes de aceitar o Workspace Trust

Agora você deve ser capaz de: Listar as habilidades registradas no console, inspecionar manifestos SKILL.md locais, utilizar os dois modos de acionamento em tarefas, identificar e corrigir falhas de associação e versionar configurações compartilhadas com o time via git. Esses passos habilitam você a aproveitar Skills de terceiros distribuídas na comunidade, integrando rotinas de desenvolvimento prontas no seu fluxo de trabalho.

---

No próximo artigo, 28 "Criador de Skills (Skill Creator)"—sabendo usar referências prontas, o passo seguinte é criar suas próprias Skills de produção. O Claude Code disponibiliza um utilitário nativo chamado skill-creator projetado para automatizar a redação de novos manifestos Markdown. Veremos como transformar rotinas informais coladas repetidamente no console em atalhos inteligentes persistentes.

---

Leitura Recomendada

• Configuração de variáveis de ambiente no Claude Code
• Utilizando comandos de voz com o Voice Mode
• Manual de Plugins: empacotando e distribuindo configurações