PodcastsHear the voice. See the shape of the thought.

O Claude Code já vem com subagentes embutidos, mas os personalizados permitem configurar comportamentos especializados para tarefas específicas. Este tutorial cria um subagente de revisão de código do zero — percorrendo o comando `/agents`, a seleção de ferramentas, a escolha do modelo e os campos do arquivo de configuração que controlam quando e como o Claude delega para ele. ## [00:03] O que são subagentes personalizados O Claude Code inclui subagentes embutidos, mas você também pode criar os seus próprios, especializados em tarefas específicas. Um subagente personalizado é um arquivo markdown com YAML front matter: o front matter indica ao Claude quando rotear para aquele agente e quais capacidades ele possui, enquanto o corpo markdown é o prompt de sistema sob o qual o subagente opera. > *"Custom sub aents are markdown files with YAML front matter. These markdown files contain configuration that helps claude understand when to use the sub aent and provides directions to the sub aent itself."* ## [00:28] Criando um subagente com /agents O comando `/agents` abre o painel de gerenciamento de agentes. Selecionar "Criar novo agente" levanta duas perguntas: escopo (projeto atual ou compartilhado em todos os projetos da máquina) e método de geração. O caminho recomendado é deixar o Claude gerar o agente automaticamente — o narrador digita um pedido em linguagem natural para um subagente que revisa qualidade de código e problemas de segurança, e o Claude cuida do resto. > *"Now, the easiest way to create a sub agent is with the / agents command. Next, you can create a sub agent manually, but we recommend using claw code to automatically generate it for you."* ## [00:56] Configurando ferramentas, modelo e cor Antes de o Claude escrever o arquivo, você escolhe quais ferramentas o subagente pode acessar. Um agente de revisão de código não precisa estritamente de ferramentas de edição, mas manter a execução habilitada facilita a inspeção de mudanças pendentes. Depois das ferramentas, você escolhe o modelo: haiku para velocidade, opus para profundidade, sonnet para o meio-termo. A última escolha é uma cor — ela aparece na interface para que você identifique o subagente rapidamente. > *"Now, given that our sub agent is only responsible for reviewing code, you might decide to disallow tools for editing, but I'll leave an execution to allow the sub agent to more easily identify pending changes."* ## [01:43] Entendendo o arquivo de configuração O arquivo gerado é salvo no projeto no caminho exibido na janela de resumo. Quatro campos são mais importantes. `name` é o identificador único — você pode referenciá-lo digitando `@agent-code-quality-reviewer` em uma mensagem. `description` é o que o Claude lê para decidir se delega; deve ficar em uma única linha (caracteres `\n` escapados são literais). Adicionar "proativamente" à descrição faz o Claude recorrer ao agente com mais frequência; adicionar conversas de exemplo torna o roteamento mais preciso. `tools` espelha o acesso concedido durante a geração, mas pode ser editado diretamente no arquivo. > *"If you want Claude to use the sub agent automatically more often, add in the word proactively to the description."* ## [02:41] O prompt de sistema e como o Claude o utiliza O campo `model` aceita `haiku`, `sonnet`, `opus` ou `inherit` — `inherit` executa o subagente no mesmo modelo da conversa principal. Tudo abaixo do front matter é o prompt de sistema: ele guia o subagente em sua tarefa e diz como devolver os resultados ao agente principal. > *"The system prompt will provide guidance to the sub agent, helping it understand how to complete its task and how it should return information back to the main agent."* ## [03:15] Testando seu subagente Depois de salvar a configuração, faça algumas alterações no código e peça ao Claude para revisá-las. Se o subagente não disparar quando esperado, o campo `description` é o primeiro lugar para ajustar — exemplos mais específicos afinam a percepção do Claude sobre quando delegar. > *"If the sub agent isn't being used when you expect, check your description. Adding more specific examples helps Claude understand when to delegate."* ## Entidades - **Anthropic Tutorial Narrator** (Pessoa): único apresentador deste episódio; narra a série de tutoriais sobre subagentes do Claude Code no canal oficial da Anthropic no YouTube - **Claude Code** (Software): assistente de programação com IA da Anthropic; suporta subagentes embutidos e subagentes personalizados criados pelo usuário - **Subagente personalizado** (Conceito): arquivo markdown com YAML front matter que configura o Claude Code para delegar tarefas específicas a uma instância de agente especializada - **/agents command** (Conceito): ponto de entrada na interface do Claude Code para criar e gerenciar subagentes; oferece escopo de projeto ou global - **Prompt de sistema** (Conceito): o corpo markdown de um arquivo de configuração de subagente; fornece orientação de tarefa e instruções de formato de saída ao subagente em tempo de execução - **Anthropic** (Organização): criadora do Claude e da plataforma Claude Code

Este tutorial da série Claude Code da Anthropic apresenta quatro padrões concretos que separam subagentes confiáveis daqueles que derivam, travam ou mexem em arquivos que não deveriam. O narrador percorre cada padrão usando subagentes de revisão de código e busca na web como exemplos recorrentes, mostrando exatamente quais configurações ajustar e por quê. ## [00:03] Controlando o comportamento do subagente com nome e descrição Toda mensagem enviada ao agente principal inclui o nome e a descrição de cada subagente registrado no prompt de sistema. Isso significa que a descrição cumpre dois papéis: informa ao orquestrador *quando* lançar o subagente e serve de modelo para a redação do prompt de entrada. O tutorial demonstra com um subagente de revisão de código. Na configuração original, o orquestrador redige um prompt genérico pedindo que o subagente execute `git diff` por conta própria. Ao atualizar a descrição para "você deve informar ao agente precisamente quais arquivos deseja que ele revise", a responsabilidade pela seleção de arquivos passa ao orquestrador — na próxima execução, o prompt de entrada se torna visivelmente mais específico. O mesmo recurso funciona para subagentes de busca na web: adicionar "retorne fontes que possam ser citadas" à descrição faz com que o agente principal inclua essa instrução automaticamente ao delegar a tarefa. > *"Se você quiser controlar melhor quando o agente principal lança um subagente automaticamente, deve modificar o nome e a descrição."* ## [01:41] Definindo formatos de saída O narrador aponta o formato de saída como a melhoria isolada de maior impacto. Sem um formato definido, o subagente não tem um sinal claro de quando terminou — continua rodando, acumulando contexto e consumindo tokens. Um formato de saída estruturado cria um ponto de parada natural. O subagente sabe que concluiu quando os campos obrigatórios estão preenchidos. Na prática, isso significa adicionar um esquema explícito — um bloco de resumo, uma lista de descobertas, um campo de status — diretamente ao prompt de sistema do subagente. > *"Sem um formato de saída definido, os subagentes têm dificuldade em decidir quando a pesquisa está suficientemente completa e tendem a rodar muito mais do que subagentes com um formato de saída definido."* ## [02:04] Relatando obstáculos no resumo Quando um subagente resolve um problema — um conflito de dependência, um comando que exige flags inesperadas, uma peculiaridade do ambiente — o agente principal precisa dessa informação, ou repetirá o mesmo obstáculo no próximo passo. A solução é exigir o relato de obstáculos no próprio formato de saída. O narrador lista as categorias que devem sempre aparecer: obstáculos encontrados, problemas de configuração, soluções alternativas descobertas, comandos que precisaram de flags ou configurações especiais, e importações ou dependências que causaram problemas. Incorporar esses itens ao esquema de saída obrigatório garante que o agente principal herde as descobertas do subagente em vez de redescobri-las do zero. > *"Caso contrário, o agente principal precisa redescobrir as mesmas soluções, obstáculos encontrados, quaisquer problemas de configuração, soluções alternativas descobertas ou peculiaridades do ambiente, comandos que precisaram de flags ou configuração especial, dependências ou importações que causaram problemas."* ## [02:42] Limitando o acesso a ferramentas por função O controle de acesso a ferramentas não é apenas uma medida de segurança — é também uma ferramenta de clareza. Um subagente somente leitura, com acesso apenas a `glob`, `grep` e `read`, não consegue modificar arquivos por acidente, o que torna sua função inequívoca para qualquer pessoa que leia a configuração. O narrador mapeia três níveis de acesso a três funções de subagente: um subagente de pesquisa recebe acesso somente leitura porque explorar o código-fonte nunca exige escrita; um revisor recebe `bash` para `git diff`, mas ainda sem ferramentas de edição; apenas subagentes explicitamente responsáveis por alterar código — como um que aplica atualizações de CSS — recebem `edit` e `write`. Com vários subagentes em operação, a lista de ferramentas se torna um resumo legível por máquina do que cada um deve fazer. > *"Dê edit e write apenas aos subagentes que realmente devem alterar seu código, como um agente de estilização aplicando atualizações de CSS."* ## [03:27] Quatro padrões para subagentes eficazes O tutorial encerra com um resumo de uma frase para cada um dos quatro padrões: saída estruturada, relato de obstáculos, descrições específicas e acesso restrito a ferramentas. Cada padrão reforça os demais — descrições precisas reduzem ambiguidade nos prompts de entrada, formatos de saída criam pontos de parada, o relato de obstáculos preserva o contexto entre fronteiras de agentes, e o acesso mínimo a ferramentas previne efeitos colaterais que amplificariam qualquer ambiguidade restante. > *"Portanto, subagentes eficazes usam saída estruturada, relatam obstáculos, têm descrições específicas e limitam o acesso a ferramentas."* ## Entidades - **Anthropic Tutorial Narrator** (Pessoa): apresentador da série de tutoriais Claude Code sobre subagentes, representando a Anthropic - **Claude Code** (Software): ferramenta de programação agêntica da Anthropic que orquestra subagentes para executar tarefas de engenharia em múltiplas etapas - **Subagente** (Conceito): uma instância especializada do Claude lançada por um agente orquestrador, com seu próprio prompt de sistema, acesso a ferramentas e prompt de entrada - **Formato de saída** (Conceito): um esquema obrigatório definido no prompt de sistema do subagente que cria uma condição de parada e estrutura as informações retornadas ao agente principal - **Relato de obstáculos** (Conceito): padrão que exige que os subagentes exponham soluções alternativas, problemas de dependência e peculiaridades do ambiente em sua saída, para que o orquestrador não precise redescobri-los - **Controle de acesso a ferramentas** (Conceito): restrição de cada subagente apenas às ferramentas que sua função exige — somente leitura para pesquisa, bash para revisão, edit/write apenas para agentes que devem modificar arquivos - **Anthropic** (Organização): criadora do Claude e da plataforma de programação agêntica Claude Code

Subagentes são assistentes especializados para os quais o Claude Code pode delegar tarefas — cada um roda em sua própria janela de contexto isolada, executa o trabalho de forma autônoma e devolve um resumo focado, enquanto todo o rastro intermediário é descartado. Este tutorial de dois minutos da Anthropic explica por que esse isolamento importa para manter a janela de contexto principal utilizável, mostra um cenário concreto de exploração de código que ilustra o custo-benefício e lista os subagentes nativos que o Claude Code já traz por padrão. ## [00:03] O que são subagentes Um subagente roda em sua própria janela de contexto de conversa separada, inicializada com um system prompt personalizado que você define. O agente principal (Claude Code na thread principal) passa ao subagente uma descrição de tarefa com base no que você pediu. O subagente a resolve de forma autônoma e devolve um resumo para a thread principal — enquanto todo o trabalho intermediário permanece isolado. > *"Sub-agents are specialized assistants that Claude can delegate tasks to."* O ponto de design crítico: quando o subagente termina, toda a sua thread de conversa é completamente descartada. Apenas o resumo retornado sobrevive de volta à conversa principal. ## [00:24] Gerenciando a janela de contexto Cada chamada de ferramenta que o Claude faz na thread principal — leituras de arquivo, buscas, rastreamentos de função — se acumula na janela de contexto principal. Em uma sessão longa, isso enche rápido. Subagentes existem justamente para descarregar tarefas discretas de pesquisa ou ação, de modo que esse custo não recaia na janela principal. > *"Each sub-agent runs in its own conversation contacts window with a custom system prompt that you define."* O custo-benefício é explícito: a janela principal ganha um contexto limpo, mas perde visibilidade sobre como o subagente chegou às suas conclusões e o que descobriu pelo caminho. Você recebe a resposta, não o rastro de raciocínio. ## [01:13] Um exemplo concreto: o sistema de pagamentos Imagine que você está usando o Claude Code para descobrir qual serviço lida com reembolsos em uma base de código desconhecida. Sem subagente, o Claude pode ler 15 arquivos, executar várias buscas e rastrear múltiplas chamadas de função — e tudo isso enche a janela de contexto principal, mesmo que você só precisasse de uma informação. > *"With a sub-agent, you get the answer without the journey."* O subagente explora o código, descobre a resposta e devolve um resumo focado — mantendo seu contexto principal limpo. A visibilidade perdida é o custo: você não verá quais arquivos foram lidos nem quais rastros foram seguidos para chegar lá. ## [02:00] Os subagentes nativos do Claude Code O Claude Code vem com três subagentes nativos prontos para uso imediato: - **Subagente de uso geral** — para tarefas de múltiplas etapas que exigem exploração e ação. - **Subagente Explore** — busca rápida em bases de código sem a sobrecarga de um loop completo de tarefas. - **Subagente Plan** — executa durante o modo de planejamento para pesquisar e analisar o código antes de apresentar um plano para você. > *"And you can also create your own sub-agents with custom system prompts and tool access."* Além desses três, você pode definir subagentes personalizados com seus próprios system prompts e listas de acesso a ferramentas, adaptados a fluxos de trabalho específicos. ## [02:30] Quando usar subagentes Subagentes compensam quando você tem uma pergunta ou tarefa discreta e autocontida que, de outra forma, despejaria muito contexto intermediário na sua janela principal. > *"Sub-agents like Claude Code break work into focused pieces, keep your main context window clean, and bring back just what you need, whether you're using the built-in ones or creating your own."* Eles são mais valiosos em sessões longas do Claude Code, onde a pressão sobre a janela de contexto se acumula — delegar uma subtarefa a um subagente, em vez de deixá-la se espalhar diretamente pela thread principal, estende diretamente a eficácia da sessão. ## Entidades - **Anthropic Tutorial Narrator** (Pessoa): narrador da série de tutoriais "Claude Code subagents" produzida pela Anthropic - **Claude Code** (Software): assistente de programação agêntico da Anthropic; o ambiente host no qual os subagentes operam - **Claude** (Software): o modelo de IA subjacente que alimenta o Claude Code e seus subagentes - **Subagente** (Conceito): um assistente especializado para o qual o Claude Code delega tarefas, rodando em uma janela de contexto isolada com seu próprio system prompt - **Janela de contexto** (Conceito): o buffer de tokens finito que armazena todo o histórico de conversa, chamadas de ferramentas e resultados; subagentes impedem que ele seja preenchido com trabalho intermediário - **Subagente de uso geral** (Software): subagente nativo do Claude Code para tarefas de exploração e ação em múltiplas etapas - **Subagente Explore** (Software): subagente nativo do Claude Code otimizado para busca rápida em bases de código - **Subagente Plan** (Software): subagente nativo do Claude Code que pesquisa o código durante o modo de planejamento antes de apresentar um plano - **Anthropic** (Organização): criadora do Claude e do Claude Code; produtora desta série de tutoriais

As skills do Claude Code são arquivos markdown reutilizáveis que codificam conhecimento especializado uma única vez — o Claude então as ativa automaticamente sempre que uma solicitação corresponde, sem que o usuário precise repetir instruções ou digitar um comando. Este tutorial de três minutos explica o que são skills, onde ficam armazenadas, como diferem dos arquivos CLAUDE.md e o sinal que indica que é hora de criar uma. ## [00:03] O problema de repetição que as skills resolvem Toda vez que você explica os padrões de código da sua equipe, redescreve como quer o feedback de PR estruturado ou lembra o Claude do formato de commit message preferido, você está se repetindo. O narrador abre com três exemplos consecutivos para nomear exatamente o ponto de atrito que as skills resolvem. > *"Toda vez que você explica os padrões de código da sua equipe ao Claude, está se repetindo."* ## [00:20] O que é uma skill e como Claude escolhe uma Uma skill é um arquivo markdown que ensina o Claude a fazer algo uma vez. O Claude armazena a instrução e a aplica automaticamente sempre que a situação exige. No Claude Code, esse arquivo é o SKILL.md. O campo de descrição dentro desse arquivo é o mecanismo central: quando você pede ao Claude para revisar um PR, ele compara sua solicitação com todas as descrições de skills disponíveis e ativa a que corresponder. > *"Claude lê sua solicitação, compara com todas as descrições de skills disponíveis e ativa as que correspondem."* ## [01:05] Onde guardar skills: pessoal versus projeto As skills ficam em dois lugares, dependendo de quem precisa delas. As skills pessoais vão em ~/.claude/skills e acompanham você em todos os projetos: estilo de commit message, formato de documentação, como você prefere que o código seja explicado. As skills de projeto ficam em .claude/skills na raiz do repositório; qualquer pessoa que clonar o repositório as recebe automaticamente. É esse segundo local que guarda os padrões da equipe: diretrizes de marca, fontes e cores preferidas para design web. > *"Qualquer pessoa que clonar o repositório recebe essas skills automaticamente."* ## [01:42] Skills vs CLAUDE.md: automáticas e eficientes em contexto O Claude Code oferece várias camadas de personalização, e as skills ocupam um nicho distinto. Os arquivos CLAUDE.md carregam em toda conversa de forma incondicional — ideal para regras como "sempre use TypeScript strict mode". As skills carregam sob demanda, apenas quando correspondem à solicitação atual, e somente o nome e a descrição entram no contexto nesse momento. O corpo completo da skill só é carregado quando acionada. Isso mantém o checklist de revisão de PR fora da janela de contexto enquanto você está depurando, e o traz apenas quando você de fato pede uma revisão. Slash commands exigem que você os digite; skills, não. > *"Skills são únicas porque são automáticas e específicas para a tarefa."* ## [02:27] Quando criar uma skill Skills funcionam melhor para conhecimento especializado ligado a tarefas específicas: padrões de revisão de código que sua equipe segue, formatos de commit message, diretrizes de marca. A regra final é direta e prática: se você se pega explicando a mesma coisa ao Claude repetidamente, isso é uma skill esperando para ser criada. > *"Se você se pega explicando a mesma coisa ao Claude repetidamente, bem, isso é uma skill esperando para ser criada."* ## Entidades - **Anthropic Tutorial Narrator** (Pessoa): narrador e apresentador da série de tutoriais de skills do Claude Code - **Claude Code** (Software): assistente de programação de IA da Anthropic; o ambiente onde as skills são descobertas e aplicadas - **SKILL.md** (Conceito): o arquivo markdown que define uma skill — contém nome, descrição e instruções para o Claude - **CLAUDE.md** (Conceito): arquivo de instruções em nível de projeto ou global que carrega em toda conversa do Claude Code de forma incondicional, em contraste com as skills - **Anthropic** (Organização): criadora do Claude e do Claude Code

Uma skill de revisão de PR usada por um único engenheiro é útil; a mesma skill implantada em toda a equipe padroniza as revisões de código e cria uma experiência consistente em toda a organização. Este tutorial percorre quatro métodos concretos de distribuição — commits em repositório, plugins, configurações gerenciadas corporativas e sub-agentes personalizados — e explica exatamente quando cada um se aplica. A seção de sub-agentes traz um detalhe não óbvio: sub-agentes não herdam skills automaticamente, e agentes nativos não conseguem acessá-las de forma alguma. ## [00:01] Por que compartilhar multiplica o valor das skills Uma skill restrita a um desenvolvedor faz seu trabalho. A mesma skill distribuída para toda a equipe consolida padrões, elimina variações individuais e garante que cada revisão tenha o mesmo aspecto e sensação. O narrador abre com um contraste direto entre uso individual e em escala de equipe, antes de listar os quatro mecanismos de compartilhamento. > *"A PR review skill that only you use is helpful. The same skill shared across your team standardizes code review and provides a consistent experience amongst your organization which is much better."* ## [00:18] Enviando skills para o repositório O método de menor atrito: coloque as skills em `.claude/skills` dentro do repositório do projeto. Qualquer pessoa que clonar o repositório recebe essas skills imediatamente — sem etapa de instalação, sem ferramentas extras. As atualizações chegam pelo ciclo normal de `git pull`. Esse caminho é ideal para padrões de codificação da equipe, fluxos de trabalho específicos do projeto e skills que referenciam a própria estrutura da base de código. > *"Anyone who clones the repository gets these skills automatically. No extra installation, it's just what you're doing already."* ## [00:45] Distribuindo skills por plugins Plugins estendem o Claude Code com funcionalidades personalizadas projetadas para ir além de um único projeto. Dentro do projeto do plugin, um diretório `skills/` espelha a estrutura de `.claude/` — nome da skill, `SKILL.md`. Uma vez publicado em um marketplace, qualquer usuário do Claude Code pode baixar e ativar o plugin. Esse canal é mais adequado para skills genéricas o suficiente para servir à comunidade em geral, e não apenas às convenções de uma equipe. > *"Think of plugins as ways to extend Claude Code with custom functionality, but designed to be shared across teams and projects."* ## [01:26] Implantação corporativa via configurações gerenciadas Administradores podem distribuir skills para todos os desenvolvedores de uma organização por meio das configurações gerenciadas. Skills corporativas têm a mais alta prioridade: sobrepõem skills pessoais, de projeto e de plugins que compartilhem o mesmo nome. O uso pretendido é para padrões obrigatórios — requisitos de segurança, fluxos de conformidade, práticas de codificação que precisam ser uniformes. O narrador enfatiza explicitamente a palavra "obrigatório": não são sugestões. > *"This is for mandatory standards, security requirements, compliance workflows, or coding practices that must be consistent across the organization."* ## [01:52] Sub-agentes personalizados e carregamento explícito de skills Sub-agentes não herdam as skills da conversa principal. Agentes nativos (explorer, planner, verify) não conseguem acessar skills de forma alguma. Apenas sub-agentes personalizados — definidos por um arquivo `agent.md` em `.claude/agents` — podem usar skills, e somente as listadas explicitamente no campo `skills:` desse arquivo. As skills são carregadas quando o sub-agente inicia, não sob demanda, portanto a lista deve ser enxuta: apenas as skills sempre relevantes ao propósito do agente. O tutorial demonstra como criar um sub-agente com o criador de sub-agentes do Claude Code e como anexar skills a um `agent.md` existente. > *"Built-in agents like the explorer, planner, and verify can't access skills at all. Only custom sub-agents you define can use them, and only when you explicitly list them."* ## [03:18] Recapitulando: escolhendo o método de distribuição certo A conclusão mapeia cada método ao seu cenário: diretórios de projeto para acesso em equipe, plugins para compartilhamento entre repositórios, implantação corporativa para padrões obrigatórios em toda a organização, e listas explícitas de skills para sub-agentes com delegação de tarefas isoladas. O lembrete sobre sub-agentes volta mais uma vez — liste apenas as skills sempre relevantes ao trabalho de um determinado agente, pois elas são carregadas na inicialização, não de forma preguiçosa. > *"Share skills through project directories for team access, plugins for cross-repository distribution, or enterprise deployment for organization-wide standards."* ## Entidades - **Anthropic Tutorial Narrator** (Pessoa): apresentador único da série de tutoriais de skills do Claude Code - **Claude Code** (Software): assistente de codificação com IA da Anthropic; o ambiente de execução onde as skills são criadas e implantadas - **Skills** (Conceito): conjuntos de instruções reutilizáveis em `.claude/skills` que estendem o comportamento do Claude Code - **Plugins** (Conceito): pacotes distribuíveis que agrupam skills para compartilhamento entre equipes e usuários de marketplace - **Managed settings** (Conceito): mecanismo de administrador corporativo para implantar skills em toda a organização com prioridade máxima de sobreposição - **Sub-agents** (Conceito): agentes personalizados do Claude Code definidos via `agent.md` em `.claude/agents`; o único tipo de agente que pode carregar skills, e somente quando listadas explicitamente - **Anthropic** (Organização): empresa que construiu o Claude Code e produz a série de tutoriais de skills do Claude Code

Um tutorial de quatro minutos da série Claude Code skills cobrindo os campos de configuração avançados que transformam uma skill básica em uma ferramenta confiável e eficiente no uso de contexto. O narrador percorre o conjunto completo de campos do padrão agentskills.io — `name`, `description`, `allowed_tools`, `model` — e explica como estruturar skills maiores usando divulgação progressiva, de modo que o material de referência e os scripts só sejam carregados quando necessário, não a cada invocação. ## [00:02] Visão geral dos campos avançados de skill O padrão aberto agentskills.io define vários campos além dos obrigatórios `name` e `description`. `name` deve ser em minúsculas com hífens, limitado a 64 caracteres, e deve corresponder ao nome do diretório. `description` tem no máximo 1.024 caracteres e é o principal sinal que o Claude usa para correspondência de skills. Dois campos opcionais completam a configuração: `allowed_tools`, que restringe quais ferramentas a skill pode invocar, e `model`, que vincula a skill a uma versão específica do Claude. > *"A basic skill works with just a name and description, but here are some other advanced tips that can make your skills really effective in Claude Code."* ## [00:39] Escrevendo descrições eficazes Uma descrição vaga — "ajudar com cães" — deixa o Claude adivinhando escopo e gatilhos. Uma boa descrição responde exatamente a duas perguntas: o que essa skill faz e quando o Claude deve usá-la? Alinhar palavras-chave à linguagem natural das solicitações dos usuários é o mecanismo para corrigir skills que não disparam corretamente. > *"A good description answers two questions. What does this skill do? And when should Claude use it?"* ## [01:20] Restringindo ferramentas com allowed_tools `allowed_tools` é o mecanismo para limitar uma skill a uma superfície definida — acesso somente leitura para fluxos de trabalho sensíveis à segurança, por exemplo. Com o campo configurado, o Claude só pode chamar essas ferramentas sem pedir permissão; sem edição, escrita ou Bash. Omitir o campo deixa o modelo de permissões normal do Claude intacto. > *"When this skill is active, Claude can only use those tools without asking permission. No editing, no writing, no bash commands."* ## [01:49] Divulgação progressiva para skills com múltiplos arquivos As skills compartilham a janela de contexto do Claude com a conversa em andamento. Colocar tudo em um único `SKILL.md` de 20.000 linhas infla o contexto a cada invocação e torna o arquivo difícil de manter. A solução: colocar as instruções essenciais no `SKILL.md` e mover o material de referência para arquivos separados que o Claude lê apenas quando a solicitação do usuário realmente os exige. O padrão sugere três diretórios de suporte — `scripts/` para código executável, `references/` para documentação e `assets/` para imagens e templates. Um link no `SKILL.md` funciona como uma entrada de sumário; se o tópico nunca aparecer, o arquivo nunca é carregado. Scripts no diretório da skill são executados sem que seu código-fonte seja carregado no contexto — apenas a saída consome tokens. O narrador recomenda manter o `SKILL.md` com menos de 500 linhas; ultrapassar esse limite é sinal de que a skill deve ser dividida. > *"It's like having a table of contents in the context window rather than fitting the whole entire document in there."* ## [03:18] Recapitulação: metadados de skill e boas práticas O tutorial encerra reafirmando a superfície de configuração completa: `name` e `description` são obrigatórios; `allowed_tools` restringe a superfície de ferramentas; `model` fixa a versão do Claude. As descrições precisam de verbos de ação concretos e frases de gatilho para corresponder com confiança. Para skills maiores, a divulgação progressiva mantém o `SKILL.md` abaixo de 500 linhas e adia os arquivos de suporte até que sejam realmente necessários. Scripts executam sem carregar o código-fonte, mantendo o contexto enxuto. > *"Scripts can execute without loading their contents, keeping context efficient."* ## Entidades - **Anthropic Tutorial Narrator** (Pessoa): apresentador único desta série de tutoriais, explicando a configuração de skills do Claude Code. - **Claude Code** (Software): ferramenta CLI da Anthropic que carrega e executa skills seguindo o padrão agentskills.io. - **agentskills.io** (Organização): padrão aberto que define o schema do manifesto de skills, incluindo `name`, `description`, `allowed_tools`, `model` e convenções de diretório. - **SKILL.md** (Conceito): arquivo de manifesto principal de uma skill do Claude Code; deve ter menos de 500 linhas com links para arquivos de suporte. - **allowed_tools** (Conceito): campo opcional de skill que lista ferramentas específicas do Claude em uma whitelist, permitindo modos somente leitura ou em sandbox. - **Progressive disclosure** (Conceito): estruturar uma skill com múltiplos arquivos de modo que arquivos de referência e scripts sejam carregados no contexto apenas quando a solicitação ativa os exige. - **Context window** (Conceito): orçamento de tokens compartilhado entre a conversa e qualquer arquivo de skill que o Claude carrega; o principal recurso que a divulgação progressiva foi projetada para conservar.

Este tutorial de 3 minutos mostra como construir uma skill pessoal no Claude Code partindo do zero: criar um diretório com um arquivo SKILL.md, verificar se a skill é carregada na inicialização e observar o Claude aplicando-a em uma solicitação real. A segunda metade explica como funciona o pipeline de carregamento de skills — desde os quatro locais de varredura e a passagem inicial só com nome, até a confirmação do usuário e a hierarquia de quatro camadas que resolve conflitos de nomenclatura. ## [00:03] O Que Este Tutorial Constrói O narrador começa com o objetivo concreto: uma skill que ensina o Claude a explicar código usando diagramas visuais e analogias. Depois de criá-la, o tutorial acompanha o que acontece internamente quando o Claude identifica e executa uma skill. > *"Essa skill vai ensinar ao Claude como gostaríamos que ele explicasse código usando diagramas visuais e analogias."* ## [00:18] Criando o Arquivo de Skill Skills pessoais ficam no diretório home, não dentro de um projeto — então o primeiro passo é criar um novo diretório com o nome da skill dentro de `~/.claude/skills/`. Dentro desse diretório vai um único arquivo `SKILL.md`. Três seções são essenciais: `name` (o identificador que o Claude armazena na inicialização), `description` (os critérios que o Claude usa para decidir se invoca a skill) e tudo após o segundo delimitador `---` (as instruções que o Claude segue quando a skill é ativada). > *"Leve em conta que estamos criando um diretório com o nome da skill dentro do diretório de skills."* ## [00:52] Carregando e Testando Sua Skill O Claude Code varre skills na inicialização, não sob demanda — portanto é preciso reiniciar a sessão após criar o arquivo. Executar `/skills` deve listar "PR description" (ou a skill que acabou de ser criada). Para testar, crie uma branch com algumas alterações e envie a solicitação em linguagem natural "Write a PR description for my changes." O Claude indica que está invocando a skill de PR description, lê o diff e escreve uma descrição seguindo o modelo — no mesmo formato todas as vezes. > *"O Claude vai mostrar que está usando a skill de PR description."* ## [01:25] Como o Claude Carrega Skills Internamente Na inicialização, o Claude Code varre quatro locais: configurações corporativas gerenciadas, `~/.claude/skills/` pessoal, o diretório `.claude/` do projeto e plugins instalados. Ele carrega apenas o `name` e a `description` — não o conteúdo completo. Quando uma solicitação chega, o Claude compara com as descrições armazenadas; "explique o que esta função faz" se sobrepõe a "explicar código com diagramas visuais", então a skill corresponde. O Claude pede confirmação antes de ler o SKILL.md completo, mantendo o usuário ciente do contexto injetado. > *"Ele carrega apenas o nome e a descrição de cada skill, não o conteúdo completo. Isso é importante mais adiante."* ## [02:02] Regras de Prioridade e Conflitos de Nome Clonar um repositório que já traz suas próprias skills pode criar colisões de nome. O Claude resolve isso com uma hierarquia fixa: corporativo (maior prioridade) → pessoal → projeto → plugins (menor prioridade). Uma skill `code-review` corporativa sempre prevalece sobre a pessoal. A solução prática é usar nomes descritivos — `security-review` ou `frontend-pr-review` em vez do genérico `review` — para que conflitos nunca ocorram. > *"Se sua empresa tem uma skill corporativa de code review e você cria uma skill pessoal de code review, a versão corporativa tem precedência."* ## [02:52] Atualizando e Removendo Skills Atualizar uma skill é uma edição direta de arquivo: abra o SKILL.md, faça as alterações e salve. Remover uma skill significa apagar o diretório. Ambas as operações exigem reiniciar o Claude Code para entrar em vigor — a lista de skills é construída uma vez na inicialização da sessão, sem monitoramento de alterações ao vivo. > *"Edite o arquivo skill.md para atualizar uma skill e reinicie o Claude Code para que as mudanças entrem em vigor."* ## Entidades - **Narrador do Tutorial Anthropic** (Pessoa): apresentador único que conduz o tutorial de criação de skills para a série Claude Code skills - **Claude Code** (Software): CLI da Anthropic para Claude; varre skills na inicialização e as aplica quando solicitações do usuário correspondem às descrições das skills - **SKILL.md** (Conceito): o arquivo único que define uma skill — contém frontmatter YAML (name, description) e texto de instrução livre após o segundo delimitador `---` - **Skills** (Conceito): conjuntos de instruções reutilizáveis e nomeados que ensinam ao Claude um padrão de comportamento consistente; armazenados como diretórios contendo um arquivo SKILL.md - **Enterprise Skills** (Conceito): skills gerenciadas pela organização que ficam no topo da hierarquia de quatro camadas, sobrepondo-se a skills pessoais, de projeto e de plugins - **Anthropic** (Organização): criadora do Claude e do Claude Code; produz esta série de tutoriais em claude.com/resources/courses

O Claude Code oferece aos desenvolvedores cinco formas distintas de customização — Skills, CLAUDE.md, subagentes, hooks e servidores MCP — cada uma projetada para um propósito diferente. Este tutorial de três minutos mapeia cada opção ao seu caso de uso correto, para que você não recorra a Skills quando CLAUDE.md resolve, nem configure um hook quando o que precisa é de um subagente. ## [00:02] Cinco opções de customização, um problema de decisão O Claude Code oferece cinco maneiras de moldar seu comportamento: Skills, CLAUDE.md, subagentes, hooks e servidores MCP. O narrador apresenta todos os cinco rapidamente e reorienta a questão de "o que são esses recursos?" para "qual deles serve aqui?" > *"Eles resolvem problemas diferentes. Saber quando usar cada um evita que você construa a coisa errada."* O restante do tutorial é essencialmente uma resposta a essa frase. ## [00:18] CLAUDE.md vs Skills: sempre ativo vs sob demanda CLAUDE.md é um arquivo que o Claude lê no início de cada conversa, sem necessidade de ativação. É o lugar certo para restrições do projeto que nunca podem ser esquecidas — escolhas de framework, estilo de código, regras de banco de dados. As Skills, por sua vez, carregam sob demanda: seu checklist de revisão de PRs só entra no contexto quando você realmente pede uma revisão, não enquanto está escrevendo código novo. > *"Use Claude MD para padrões do projeto que sempre se aplicam — restrições como nunca modificar o schema do banco de dados, preferências de framework e estilo de código."* A linha divisória é permanência versus relevância. Se a instrução deve valer para todo prompt do projeto, ela pertence ao CLAUDE.md. Se é útil apenas às vezes, ela pertence a uma Skill. ## [01:03] Skills vs Subagentes: contexto compartilhado vs execução isolada As Skills injetam conhecimento na conversa atual — suas instruções se integram ao contexto existente. Os subagentes funcionam de forma diferente: recebem uma tarefa, criam um contexto de execução separado, trabalham de forma independente e devolvem os resultados sem tocar na conversa principal. > *"Use subagentes quando quiser delegar uma tarefa a um contexto de execução separado. Você precisa de acesso a ferramentas diferentes das da conversa principal. Quer isolamento entre o trabalho delegado e seu contexto principal."* Use Skills quando o conhecimento deve guiar o raciocínio do Claude ao longo de uma conversa em andamento. Use subagentes quando quiser uma fronteira clara entre a sessão principal e uma unidade de trabalho delegada — ferramentas diferentes, sem contaminação cruzada. ## [01:42] Hooks vs Skills: orientado a eventos vs orientado a requisições Hooks disparam automaticamente em resposta a eventos — executar um linter toda vez que o Claude salva um arquivo, validar uma entrada antes de uma chamada de ferramenta específica. Eles não são ativados pelo que você pede; são ativados pelo que o Claude faz. Skills são o oposto: orientadas a requisições, ativando quando uma consulta corresponde a elas. > *"Um hook pode executar um linter toda vez que o Claude salva um arquivo ou validar a entrada antes de certas chamadas de ferramenta. São todos orientados a eventos, enquanto as skills são orientadas a requisições. Elas ativam com base no que você está pedindo."* Se o comportamento deve ocorrer incondicionalmente em um evento do sistema, é um hook. Se deve moldar como o Claude pensa quando solicitado, é uma Skill. ## [02:15] Combinando todos os cinco para customização abrangente Uma configuração bem estruturada do Claude Code usa cada ferramenta em seu papel natural: CLAUDE.md para padrões do projeto sempre ativos, Skills para conhecimento específico de tarefas que não deve poluir todo prompt, hooks para efeitos colaterais automatizados, subagentes para trabalho delegado isolado e servidores MCP para acesso a ferramentas externas. Não são alternativas — eles se compõem. > *"Não force tudo em skills quando outra opção se encaixa melhor. Você pode usar múltiplas ao mesmo tempo."* Skills ativam automaticamente quando um tema é relevante; CLAUDE.md está sempre presente; subagentes rodam em isolamento; hooks disparam em eventos; MCP fornece ferramentas externas. Escolha a camada certa para cada preocupação e combine-as livremente. ## Entidades - **Anthropic Tutorial Narrator** (Pessoa): Apresentador desta série de tutoriais de skills do Claude Code, em nome da Anthropic. - **Claude Code** (Software): Assistente de programação baseado em IA da Anthropic; objeto da série de tutoriais. - **Skills** (Conceito): Pacotes de conhecimento sob demanda que ativam quando o Claude reconhece uma requisição do usuário; injetam instruções no contexto da conversa atual. - **CLAUDE.md** (Conceito): Arquivo de configuração carregado automaticamente em toda conversa do Claude Code; usado para padrões e restrições do projeto sempre ativos. - **Subagentes** (Conceito): Contextos de execução separados criados para lidar com tarefas delegadas em isolamento da conversa principal. - **Hooks** (Conceito): Automação orientada a eventos que dispara em ações específicas do Claude, como salvar um arquivo ou fazer chamadas de ferramenta, independentemente das requisições do usuário. - **MCP Servers** (Software): Servidores do Model Context Protocol que fornecem ferramentas externas às sessões do Claude Code. - **Anthropic** (Organização): Criadora do Claude Code e publicadora da série de tutoriais de skills do Claude Code.