Skills e plugins

Esta aula responde a uma pergunta que aparece assim que você usa o Claude Code por algum tempo: como ensinar ao agente um procedimento que você repete todo dia, sem colar o mesmo texto em toda conversa, e como empacotar esse conhecimento, junto com comandos, subagents e servidores MCP, para que o time inteiro use a mesma versão? A resposta envolve dois mecanismos que se confundem com facilidade. Uma skill é um procedimento que o modelo lê quando precisa dele. Um plugin é a caixa que transporta skills e outras peças de um projeto para outro, ou de uma pessoa para outra.

Ao terminar, você consegue dizer o que é um arquivo SKILL.md, quando o modelo o carrega, em que ele difere de um comando e de um subagent, onde uma skill pode morar e qual versão vence quando dois nomes colidem. Também consegue explicar o que um plugin empacota, como ele é instalado e o que custa em contexto, e decidir se uma instrução nova vira skill, plugin ou fica no CLAUDE.md.

A aula parte do zero. Não pressupõe que você já tenha escrito uma skill nem instalado um plugin. Os nomes de arquivos, de campos e de comandos vêm da documentação oficial do Claude Code, consultada em 18 de outubro de 2026, e os exemplos de arquivo foram validados com a CLI na versão 2.1.296. Onde a documentação não confirma um ponto, a aula diz isso.

Esta aula cobre a customização agêntica do Claude Code. Ela se apoia na nota Agents. A nota Agents trata a personalização por instruções, ferramentas e subagents. Esta aula cobre o que falta: skills, plugins e a forma de distribuí-los.

Mapa da aula

Pré-requisito: ter lido a nota Agents, porque subagents aparecem aqui como contraste. Ajuda ter passado pela aula 6.2 Gestão de configuração, porque escopos e arquivos de configuração são os mesmos.

Parte 1: skills

1. O que é uma skill

Pense num cozinheiro novo que chega ao restaurante. Ele sabe cozinhar, mas não sabe que a casa faz o molho de tomate com manjericão colhido de manhã. Em vez de repetir o treinamento inteiro toda semana, a cozinha pendura uma ficha plastificada na parede, com o passo a passo do molho. Quem precisa do molho lê a ficha. Quem faz só grelhados nem olha para ela, e a ficha não ocupa a cabeça de ninguém enquanto está na parede.

Uma skill é essa ficha. Tecnicamente, é uma pasta com um arquivo chamado SKILL.md. Esse arquivo tem duas partes. No início fica um cabeçalho em YAML, entre duas linhas de três traços, que a documentação chama de frontmatter. Depois vêm as instruções, escritas em Markdown, como se você estivesse explicando o procedimento a um colega. O campo mais importante do frontmatter é description, que diz o que a skill faz e em que situação ela deve ser usada. É esse texto que o modelo lê para decidir se a skill serve ao pedido. A pasta pode trazer outros arquivos, como um checklist ou uma referência de API. Eles só entram na conversa se o texto do SKILL.md mandar ler.

O porquê disso tem a ver com o custo de contexto. Antes das skills, a forma comum de ensinar um procedimento era colar o texto no CLAUDE.md ou no próprio prompt. Os dois entram na conversa inteira desde o início. Um checklist de revisão de segurança com trinta itens ocuparia espaço em toda sessão, inclusive nas sessões em que ninguém pede revisão de nada. A skill separa duas coisas que estavam juntas: o que o modelo precisa saber que existe, que é a descrição, e o que ele precisa ler para executar, que é o corpo. Só a primeira parte fica sempre presente.

2. Quando o modelo carrega uma skill

Ao iniciar, o Claude Code monta uma listagem com o nome e a descrição de cada skill disponível. Essa listagem é o catálogo que o modelo consulta. Quando um pedido casa com a descrição de alguma skill, o modelo carrega o SKILL.md inteiro, e o texto passa a fazer parte da conversa. Você também pode chamar a skill diretamente, digitando / seguido do nome. Por isso a descrição funciona como o roteador da skill: uma descrição vaga como “ajuda com código” quase nunca dispara, e uma descrição que usa as palavras que você de fato escreve dispara com frequência.

A documentação faz duas recomendações sobre a descrição. A primeira é colocar o caso de uso principal no começo, porque o texto combinado de description e de when_to_use é cortado em 1.536 caracteres na listagem. A segunda vem da própria implementação: a listagem tem um orçamento de cerca de 1% da janela de contexto do modelo. Com muitas skills, o Claude Code corta primeiro as descrições das skills menos invocadas, o que significa que uma skill pouco usada pode, com o tempo, ficar sem o texto que a faria disparar. A skill continua listada pelo nome, mas o modelo perde as palavras que a ligariam ao seu pedido.

Dois campos do frontmatter controlam quem pode chamar a skill. A tabela resume o efeito de cada um, segundo a documentação.

O primeiro caso serve a fluxos com efeito colateral, como um deploy, que não devem começar porque o modelo achou que faziam sentido. O segundo serve a conhecimento de fundo que não é uma ação, como uma convenção de nomes, que o Claude deve aplicar sem que alguém o chame pelo nome.

Depois de carregada, a skill não é relida. A documentação diz que o conteúdo renderizado do SKILL.md entra na conversa como uma única mensagem e permanece nela nas trocas seguintes. Há consequências práticas nisso. Uma instrução do tipo “rode os testes” vale como um passo único, enquanto uma instrução “rode os testes depois de cada edição” funciona como regra permanente, e é a segunda que deve ser escrita. Outra consequência aparece na compactação. Quando a conversa é resumida para liberar espaço, o Claude Code reanexa a invocação mais recente de cada skill, guardando as primeiras 5.000 tokens de cada uma, dentro de um orçamento combinado de 25.000 tokens. Se você invocou muitas skills numa sessão longa, as mais antigas podem sair por completo. Por isso o trecho mais importante de um SKILL.md deve vir no começo.

O campo allowed-tools segue outra regra. Ele libera ferramentas sem pedir permissão durante o turno em que a skill foi invocada, e essa liberação termina na sua próxima mensagem. A instrução continua na conversa, mas a permissão não.

Um arquivo de exemplo ajuda a fixar os campos. O arquivo abaixo cria uma skill de revisão de segurança. Ele foi gravado numa pasta de rascunho, dentro de um plugin de teste, e não faz parte do vault.

---
name: revisao-seguranca
description: Revisa um diff procurando segredos, permissões amplas e chamadas a rede não declaradas. Use quando o usuário pedir revisão de segurança de uma mudança.
disable-model-invocation: false
allowed-tools: Read, Grep, Glob
---

Revise o diff atual em busca de:

1. chaves, tokens ou senhas escritos no código;
2. regras de permissão mais amplas do que a tarefa exige;
3. chamadas de rede para domínios que não estão na documentação do projeto.

Para cada achado, cite o arquivo e a linha.

O campo disable-model-invocation: false já é o padrão, e está escrito só para mostrar onde ele fica. Para conferir que o frontmatter é lido como YAML, extraí o bloco entre as duas linhas de três traços com um script Python e obtive esta saída:

name: revisao-seguranca
description: Revisa um diff procurando segredos, permissões amplas e chamadas a rede não declaradas. Use quando o usuário pedir revisão de segurança de uma mudança.
disable-model-invocation: false
allowed-tools: Read, Grep, Glob

A validação oficial exige um manifesto de plugin, e a aula usa o plugin de teste que contém essa skill. Rodei claude plugin validate sobre a pasta do plugin e a saída foi esta, com o caminho abreviado:

Validating plugin manifest: <rascunho>/plugin-ex/.claude-plugin/plugin.json

⚠ Found 1 warning:

  ❯ author: No author information provided. Consider adding author details for plugin attribution

✔ Validation passed with warnings

O aviso sobre o autor não impede nada. O que importa é que o frontmatter foi aceito. Essa validação também tem um detalhe que voltaremos a ver na seção 9: apontar o comando para uma pasta só de skills, sem manifesto, falha com a mensagem “No manifest found in directory”. A documentação de skills sugere validar .claude/skills diretamente, e esse exemplo não funcionou na versão testada.

3. Skill, comando e subagent

Antes de comparar com outros mecanismos, vale resolver a confusão mais comum. O Claude Code aceita dois formatos para criar um atalho com barra: um arquivo em .claude/commands/ e uma skill em .claude/skills/. A documentação diz que os dois foram unificados. Um arquivo em .claude/commands/deploy.md e uma skill em .claude/skills/deploy/SKILL.md criam ambos o comando /deploy e funcionam da mesma forma. Os arquivos de comando antigos continuam funcionando, mas o caminho recomendado para trabalho novo é a skill.

A diferença que sobra é de capacidade. Um comando é um arquivo solto, sem pasta própria, então não tem onde guardar arquivos de apoio. Uma skill tem pasta, pode trazer referências e scripts e pode ser carregada pelo próprio Claude quando a descrição casa com o pedido. Quando o nome colide, a skill vence o arquivo de comando. Por isso, na prática, quem escreve algo novo escreve skill.

O subagent é outra coisa, e a diferença é mais importante. Uma skill comum roda na conversa principal. O procedimento entra no contexto da conversa, e o modelo que já estava trabalhando passa a seguir esse procedimento. Um subagent roda numa janela própria. A documentação diz que ele começa com um contexto novo e isolado, que não vê o histórico da conversa, nem as skills já invocadas, nem os arquivos que o Claude já leu. Quando termina, devolve ao contexto principal apenas o resumo.

A skill pode pedir esse isolamento pelo campo context: fork. Com ele, o Claude Code inicia um subagent do tipo indicado em agent e entrega a esse subagent o conteúdo da skill como prompt. Os valores aceitos para agent são Explore, Plan, general-purpose ou um subagent personalizado da pasta .claude/agents/. Como o subagent não vê a conversa, a skill precisa se sustentar sozinha, com todas as informações de que o subagent vai precisar.

4. Contexto, isolamento e capacidade externa

Existem três formas de estender o que o agente sabe ou faz, e elas respondem a perguntas diferentes. A figura mostra o mesmo agente principal conectado às três.

O ramo de cima é o contexto, e é onde a skill mora. A skill acrescenta instruções à conversa que já existe. Imagine a skill de revisão de segurança da seção 2. Quando você pede “revise este diff”, o modelo lê o checklist e passa a olhar o diff com essas três perguntas em mente. Nada novo é executado e nenhuma ferramenta nova aparece. O que muda é a maneira como o agente pensa o próprio trabalho. O custo é o espaço que o texto ocupa na janela, e por isso a skill deve conter só o que o procedimento exige.

O ramo do meio é o isolamento, e é onde mora o subagent. Imagine que você pede ao agente principal para investigar por que um serviço falhou durante a madrugada. Os logs somam quarenta mil linhas. Se o agente principal lesse tudo, a conversa ficaria cheia de texto que não será usado de novo. Em vez disso, ele delega a investigação a um subagent, que lê os logs na própria janela e devolve três achados com a linha de cada um. O ganho é que o volume fica fora da conversa principal. O custo é que o subagent não sabe nada do que vocês conversaram, então o brief precisa ser completo. Uma correção à nota Agents cabe aqui: a nota diz que subagents não herdam as skills da conversa e que, portanto, é preciso listá-las no campo skills. A documentação diz algo mais preciso. O campo skills pré-carrega o conteúdo das skills listadas, até 32 nomes distintos, e não restringe o acesso. Sem esse campo, o subagent ainda pode descobrir e invocar skills de projeto, pessoais e de plugins pela ferramenta Skill. A lista serve para carregar o texto de antemão, e não para liberar ou bloquear o acesso.

O ramo de baixo é a capacidade externa, e é onde mora o servidor MCP. Um servidor MCP conecta o agente a um sistema que está fora do modelo, como um banco de dados, um tracker de tarefas ou uma API interna. Ele expõe ferramentas, ou seja, ações que o agente pode pedir para executar, com nomes e parâmetros declarados. Pense numa tomada padronizada: o agente não precisa saber como a energia é gerada do outro lado, só que o plugue encaixa. O servidor não ensina um procedimento. Ele dá ao agente uma porta que antes não existia. O detalhe de transporte, autenticação e schemas está na nota MCP, e aqui basta a distinção: o MCP acrescenta alcance, a skill acrescenta método, e o subagent acrescenta uma janela separada.

A tabela resume a comparação para a prova, que costuma perguntar qual mecanismo resolve um problema dado.

Os três podem aparecer juntos, e um caso comum mostra isso. Uma skill de revisão pode usar context: fork para rodar num subagent, que chama um servidor MCP do seu tracker para buscar a tarefa associada ao diff. Cada peça responde a uma pergunta diferente, e confundir as três leva a escolhas ruins, como colocar um servidor MCP onde bastaria uma instrução, ou delegar a um subagent algo que só precisava de três linhas no contexto.

5. Onde moram e quem vence

Uma skill pode viver em vários lugares, e cada lugar define quem a enxerga. A documentação lista os seguintes locais para o SKILL.md. Na empresa, ele fica no diretório de configurações gerenciadas, em .claude/skills/<nome>/SKILL.md, e chega às máquinas por um mecanismo que a organização controla. Na sua conta pessoal, fica em ~/.claude/skills/<nome>/SKILL.md e vale em todos os seus projetos. No projeto, fica em .claude/skills/<nome>/SKILL.md, dentro do repositório, e pode ser versionado para que o time receba a mesma skill. Há ainda as skills de subdiretórios, que entram só quando o Claude lê ou edita um arquivo daquela parte do repositório, e as pastas passadas com --add-dir. Dentro de um plugin, a skill fica em <plugin>/skills/<nome>/SKILL.md. As skills ligadas à conta do claude.ai também existem, mas ficam fora do foco desta aula.

O projeto tem uma regra de alcance que vale a pena conhecer. O Claude Code carrega as skills de .claude/skills/ no diretório onde você iniciou a sessão e em todos os diretórios acima dele, até a raiz do repositório. Assim, uma sessão iniciada em packages/frontend/ ainda enxerga as skills definidas na raiz. Uma skill de subdiretório, em contrapartida, só entra quando você mexe em algum arquivo daquela subpasta. O mecanismo é o mesmo que 6.2 Gestão de configuração descreve para o CLAUDE.md em subpastas, com a diferença de que o corpo da skill é que fica de fora até ser necessário.

Quando o mesmo nome aparece em mais de um lugar, a documentação define a precedência, e ela é diferente da regra das configurações. Para skills, a ordem é empresa sobre pessoal, e pessoal sobre projeto. Se existe uma skill deploy em ~/.claude/skills/ e outra em .claude/skills/ do projeto, o comando /deploy executa a pessoal. A skill do projeto continua existindo, mas fica escondida na sua máquina, e os colegas que não têm a skill pessoal veem a do projeto. É por isso que 6.2 Gestão de configuração recomenda evitar nomes que colidam. A documentação também diz que skills de plugin não entram nessa disputa, porque são identificadas com o prefixo do plugin, como /revisao-tools:revisao-seguranca, e as duas versões coexistem. A figura mostra esse caso com os quatro escopos.

A figura lê de cima para baixo. Os três primeiros escopos disputam o mesmo nome, e a seta grossa da empresa indica que ela vence. A seta da skill pessoal vence a do projeto, e a do projeto aparece pontilhada, porque fica escondida. O plugin fica à direita, com o nome revisao:deploy separado, e os dois comandos não se encontram. Um detalhe que a figura não mostra, mas que a documentação permite: a configuração skillOverrides em settings.json pode colocar uma skill em "off" ou "name-only" sem tocar no SKILL.md. Isso serve para desligar uma skill compartilhada do projeto na sua máquina.

Uma observação de honestidade sobre o que não está confirmado. A documentação define precedência para empresa, pessoal e projeto, e diz que skills de plugin são namespaceadas. Não encontrei, nas páginas consultadas, regra explícita de colisão entre skills vindas de --add-dir e as dos outros escopos, e a aula não a afirma.

Parte 2: plugins

6. O que um plugin empacota

Uma skill sozinha resolve o problema de uma pessoa num projeto. Quando o time quer o mesmo conjunto em várias máquinas, ou quando um conjunto de skills depende de um servidor MCP e de um hook para funcionar, copiar pastas à mão vira uma fonte de erro. Um plugin existe para isso. A documentação o define como um diretório de componentes, com um manifesto em JSON, que o Claude Code instala e carrega como uma unidade só. O manifesto fica em .claude-plugin/plugin.json e dá nome ao plugin, além de versão, descrição e outros metadados.

Os componentes são as peças que o plugin acrescenta ao Claude Code. Skills ficam em skills/<nome>/SKILL.md, com o mesmo formato da seção 2. Comandos ficam em commands/, e agents, que são subagents, ficam em agents/. Hooks ficam em hooks/hooks.json, e servidores MCP são declarados em .mcp.json na raiz do plugin. A documentação também cita outros tipos, como módulos de hooks escritos em JavaScript, que não cobrimos aqui.

O nome do plugin entra em todos os comandos que ele cria. Uma skill em skills/revisao-seguranca/SKILL.md, dentro do plugin revisao-tools, aparece para o usuário como /revisao-tools:revisao-seguranca. Esse prefixo é o que impede a colisão da seção 5. Se o plugin tem uma skill chamada deploy e o projeto também tem, as duas coexistem, uma sob cada nome. A consequência para quem escreve plugin é que o nome do plugin precisa ser bem escolhido, porque ele faz parte de todo comando que o plugin oferece.

Há um detalhe que confunde iniciantes. Criar uma skill não exige plugin, e uma skill solta continua funcionando sozinha. A documentação diz isso com clareza: skills, subagents, hooks e servidores MCP funcionam por conta própria. O plugin serve quando você quer agrupar vários desses componentes numa unidade que pode ser instalada, atualizada e removida de uma vez.

7. Como um plugin é instalado e o que custa

A distribuição passa por um marketplace. Um marketplace é um catálogo, um repositório ou diretório com um arquivo .claude-plugin/marketplace.json que lista plugins e diz onde buscar cada um. Ele não é uma loja hospedada. Você registra o marketplace uma vez e depois instala plugins dele pelo nome. A documentação dá como exemplo o comando /plugin marketplace add owner/repo para registrar um marketplace do GitHub, e /plugin install nome@marketplace para instalar. O mesmo pode ser feito no shell, com claude plugin install nome@marketplace. Para desenvolver um plugin sem marketplace, a documentação recomenda carregá-lo direto da pasta com --plugin-dir, que vale só para a sessão.

Na hora de instalar, você escolhe um escopo, e o escopo define quem fica com o plugin habilitado e em qual arquivo de configuração essa escolha é registrada. O escopo de usuário habilita o plugin em todos os seus projetos, e a entrada vai para enabledPlugins em ~/.claude/settings.json. O escopo de projeto grava a entrada em .claude/settings.json, que você versiona, e vale para quem trabalha no repositório. Mesmo assim, cada colega ainda precisa instalar o plugin na própria máquina, porque o arquivo versionado só liga o plugin, sem baixá-lo. O escopo local grava em .claude/settings.local.json e vale só para você, neste repositório. Quando o mesmo plugin aparece em mais de um escopo, o local vence o do projeto, e o do projeto vence o do usuário. Essa regra é específica de plugins. As chaves de configuração em geral seguem a precedência de 6.2 Gestão de configuração, em que a organização vem primeiro e o usuário por último.

Dois comportamentos merecem atenção. O primeiro é o custo. Um plugin habilitado faz parte de toda sessão em que está ativo, não só das sessões em que você o usa. Para cada skill e agent que o Claude pode invocar por conta própria, o nome e a descrição ficam no contexto em todo turno, para que o modelo saiba que existem. Esses tokens contam no uso e reduzem o espaço da janela, mesmo quando nada do plugin é executado. O corpo de uma skill, em compensação, só carrega quando é usado. Para plugins do marketplace oficial, a tela de detalhes mostra uma estimativa de custo antes da instalação. Depois de instalado, o comando claude plugin details <nome> mostra o custo sempre presente e o componente que mais contribui.

O segundo comportamento é de segurança. O que um plugin executa, ele executa com o seu usuário. Os hooks rodam comandos nos eventos do ciclo de vida, e os servidores MCP se conectam a sistemas externos. A documentação de segurança pede que você revise o conteúdo do plugin antes de instalá-lo, sobretudo se ele vem de um marketplace que você não conhece. 6.2 Gestão de configuração trata a mesma preocupação do lado do time, com revisão de pull request de .mcp.json e .claude/.

Há ainda um caso de ambiente. Uma sessão na nuvem, incluindo a que roda no navegador em claude.ai/code, não carrega os plugins instalados na sua máquina. Já um comando claude -p, que roda sem sessão interativa, carrega os plugins que já estão instalados. A instalação em si não é feita por ele, porque /plugin não funciona nesse modo, e a instalação é feita pelo shell.

Parte 3: decisão e prática

8. Skill, plugin ou CLAUDE.md

Chegou o momento de decidir, porque essa é a pergunta que a prova e a prática cobram. Uma instrução nova pode caber em três lugares, e a escolha depende de três fatores: quanto ela custa em contexto, quem precisa dela e se ela precisa ser garantida.

O CLAUDE.md é carregado em toda sessão. Por isso, ele serve para o que vale sempre e é curto, como o comando de teste do projeto, a convenção de nomes e a arquitetura geral. Uma instrução que só importa em uma tarefa em cada dez não deve morar lá, porque paga o custo em todas as sessões.

A skill serve ao procedimento que aparece às vezes. Ela custa a descrição em toda sessão e o corpo só quando é usada. Se o procedimento é seu e vale para todos os seus projetos, a skill vai para a pasta pessoal. Se é do projeto e o time deve compartilhá-lo, vai para .claude/skills/ versionada.

O plugin serve quando o pacote precisa de mais de uma peça, ou precisa ir para outros repositórios e para outras pessoas. Se a sua skill depende de um servidor MCP e de um hook, empacotar tudo num plugin evita que cada colega monte a mesma combinação. O plugin também é o formato para publicar uma versão e atualizá-la depois.

Resta a regra que não pode falhar. A documentação de skills é clara ao dizer que uma regra que precisa valer em todo momento deve virar um hook, porque o hook roda a cada evento, esteja ou não o modelo seguindo a skill. O mesmo raciocínio vale para o CLAUDE.md, que orienta sem garantir, como 6.2 Gestão de configuração mostra. A skill também orienta, e só um mecanismo determinístico, como permissões ou um hook, garante. A tabela resume a decisão.

9. Erros comuns e boas práticas

O primeiro erro é escrever a descrição para quem lê, e não para o modelo. “Ferramenta de análise” é uma descrição que parece clara para um humano e que o modelo não associa a nenhum pedido. “Revisa um diff procurando segredos e permissões amplas. Use quando o usuário pedir revisão de segurança” diz as palavras que o pedido vai conter. A descrição é o roteador, e um roteador que não reconhece o pedido deixa a skill parada.

O segundo erro é tratar a skill como garantia. Uma skill que diz “nunca rode migrações em produção” é um pedido que o modelo tende a respeitar, e não uma barreira. Se a regra precisa valer sempre, ela vai para permissões ou para um hook.

O terceiro erro é o SKILL.md longo, com o procedimento inteiro dentro dele. A documentação recomenda manter o arquivo abaixo de 500 linhas e mandar o modelo ler arquivos de apoio quando precisar. Como o corpo entra inteiro na conversa e fica lá, um texto de mil linhas pesa em todas as trocas seguintes, e a parte final pode ser perdida numa compactação.

O quarto erro é a colisão de nomes. Uma skill pessoal chamada deploy pode esconder, na sua máquina, a do projeto, e nem você nem o colega percebem a diferença sem olhar. Dê nomes específicos, ou use um plugin, cujo prefixo evita a disputa.

O quinto erro é esperar isolamento de uma skill comum. Se o procedimento gera muito texto intermediário, como a leitura de logs, uma skill comum enche a conversa principal. Para isolar, use context: fork, e lembre que o subagent não vê a conversa.

O sexto erro é instalar um plugin sem olhar o conteúdo. Hooks e servidores MCP rodam com o seu usuário, e o custo de contexto aparece em toda sessão. Antes de instalar, leia o que ele adiciona, e depois confira o custo com claude plugin details.

O sétimo erro é a validação mal entendida. Quando testei a validação sobre uma pasta só de skills, a CLI respondeu que não havia manifesto. A saída está na própria mensagem: a validação espera um plugin, com .claude-plugin/plugin.json, ou um marketplace. Se a documentação sugere outra forma, confira a versão da CLI antes de concluir que o arquivo está errado.

Como boas práticas, a regra prática é escrever descrições com as palavras do pedido, deixar o procedimento curto e com o essencial no começo, separar o que é pessoal do que é do time, usar plugin para pacotes e hook para o que não pode falhar.

10. Exercícios

Estes exercícios podem ser feitos num repositório de teste.

Primeiro exercício: crie uma skill em .claude/skills/resumo-tarefa/SKILL.md, com uma descrição que use as palavras que você vai pedir ao Claude. Pergunte ao Claude quais skills estão disponíveis, como sugere a documentação, e confirme que ela aparece. Depois faça um pedido que use as palavras da descrição e outro que não use, e observe se a skill dispara nos dois casos. Explique o resultado pela descrição, e não pelo nome.

Segundo exercício: crie uma skill deploy na sua pasta pessoal e outra deploy no projeto, cada uma com uma instrução diferente. Rode /deploy e verifique qual instrução foi seguida. Explique a escolha com a ordem empresa, pessoal, projeto, e depois mude o nome da pessoal e compare.

Terceiro exercício: empacote uma skill num plugin com a estrutura .claude-plugin/plugin.json e skills/<nome>/SKILL.md, carregue-o com --plugin-dir numa sessão e confirme o comando com prefixo. Rode claude plugin validate sobre a pasta do plugin e leia cada aviso.

Quarto exercício: escreva uma skill com context: fork e agent: Explore que leia um diretório de logs e devolva três achados. Compare o resultado com a mesma tarefa pedida em uma skill comum, e anote o que muda no tamanho da conversa principal.

11. Glossário

Skill: pasta com um SKILL.md que o modelo pode carregar quando a descrição casa com o pedido, ou que você chama com /nome.

SKILL.md: arquivo principal de uma skill, com frontmatter em YAML e instruções em Markdown.

Frontmatter: bloco de metadados no início de um arquivo, entre duas linhas de três traços, lido como YAML.

Description: campo do frontmatter que diz o que a skill faz e quando usá-la. É o texto que o modelo compara com o pedido.

Listagem de skills: catálogo com nome e descrição de cada skill, sempre presente no contexto, com orçamento limitado.

Invocação: uso de uma skill, seja pelo usuário com a barra, seja pelo modelo por conta própria.

Subagent: agente delegado, com janela de contexto e ferramentas próprias, que devolve um resumo ao agente principal.

Context fork: context: fork no frontmatter de uma skill, que faz a skill rodar num subagent isolado.

Plugin: diretório de componentes com manifesto, instalado e carregado como unidade.

Manifesto: arquivo .claude-plugin/plugin.json, que dá nome e metadados ao plugin.

Marketplace: catálogo que lista plugins e indica onde buscar cada um.

Escopo: lugar onde uma configuração ou um plugin vale, como usuário, projeto ou local.

Namespace: prefixo que identifica a origem de um comando, como /revisao-tools:revisao-seguranca.

Servidor MCP: processo que expõe ferramentas externas ao agente, declarado em .mcp.json.

Fontes

Consultadas em 18 de outubro de 2026, na documentação oficial do Claude Code. A consulta foi feita por ferramenta de leitura de páginas, que resumiu o texto. As citações são paráfrases fiéis do que a página diz, e não transcrições literais verificadas uma a uma.

• Skills: https://code.claude.com/docs/en/skills
• Plugins, visão geral: https://code.claude.com/docs/en/plugins
• Instalação e escopos de plugins: https://code.claude.com/docs/en/plugins/install
• Componentes de plugin: https://code.claude.com/docs/en/plugins/components
• Configurações e precedência: https://code.claude.com/docs/en/settings
• Subagents: https://code.claude.com/docs/en/sub-agents
• Diretório .claude: https://code.claude.com/docs/en/claude-directory

Validação local feita com Claude Code 2.1.296, em 18 de outubro de 2026, sobre um plugin de teste.

O que não ficou confirmado: os campos obrigatórios do manifesto além de name (a página de referência do manifesto não foi lida nesta consulta); a regra de colisão entre skills de --add-dir e as dos outros escopos; e o exemplo de validação de uma pasta só de skills sugerido pela documentação, que na versão testada exige manifesto.

Relacionados

• Agents
• 6.2 Gestão de configuração
• MCP