Guia Completo para Iniciantes em Agent Skills: Criando sua Primeira Skill

Todo mundo que trabalha com IA já enfrentou esse problema:

Você ensina algo, começa uma nova conversa no dia seguinte, e tudo volta ao zero.

Você passa três dias ajustando um fluxo de trabalho, indo e voltando com o Claude para acertar, só para ter que explicar tudo de novo no dia seguinte.

Você salva prompts nas suas anotações e os cola toda vez, mas colar uma instrução de 500 palavras todos os dias durante um mês faz você se perguntar: é assim que a IA deveria ser usada?

A Skill nasceu especificamente para resolver esse problema.

Foi lançada pela Anthropic em outubro de 2025 e se tornou um padrão aberto em dezembro.

Hoje, a internet inteira grita "Skills transformam produtividade", mas a maioria das pessoas só ouviu falar disso sem realmente entender a diferença entre Skills, prompts, bases de conhecimento, MCP e agentes—muito menos construir uma por conta própria.

Este artigo explica tudo de uma vez.

Primeiro, entenda uma coisa: Skills não estão vinculadas a nenhuma IA específica.

Muitas pessoas ouvem "Claude Skills" e pensam que é um recurso exclusivo do Claude, mas não é. O Agent Skills é um padrão aberto lançado pela Anthropic; o Claude é apenas o principal implementador.

A mesma pasta de Skill pode ser colocada em ~/.claude/skills/ para o Claude Code, ~/.cursor/skills/ para o Cursor, ou usada com OpenAI Codex, Gemini CLI, VS Code Copilot e JetBrains Junie.

A Skill que você escreve hoje pode ser transferida perfeitamente para outro Agente amanhã; seu investimento não ficará preso a uma única empresa.

Este artigo usará principalmente o Claude Code como exemplo (já que é o criador do padrão com o ecossistema mais completo), mas todos os princípios, métodos de escrita e experiências de solução de problemas se aplicam a todas as ferramentas de IA que suportam Agent Skills.

Quando você vir "Claude Skill", pense em "Agent Skill".

1. O que é exatamente uma Skill?

Definição em uma frase:

Uma Skill é uma pasta, centrada em um arquivo Markdown chamado SKILL.md, que diz a uma IA como executar de forma estável um tipo específico de trabalho profissional de acordo com um SOP que você define.

Ela encapsula "como um certo tipo de coisa deve ser feita" em um módulo de capacidade reutilizável e acionado automaticamente.

Essencialmente, é um "pacote de expansão" para IA de uso geral.

A IA geral é como uma máquina básica—inteligente, mas sem conhecimento de domínio. Uma Skill é um módulo plug-and-play: instale uma "Skill de Estilo Xiaohongshu", e a IA imediatamente se torna um editor que entende sua marca; instale uma "Skill de Relatório Semanal", e a IA gera imediatamente relatórios no formato da sua empresa.

E esse "pacote de expansão" não é exigente com a IA: Claude Code, Codex, Cursor, Gemini CLI e Junie reconhecem o mesmo formato.

Você está fazendo um Agent Skill, não um script exclusivo do Claude.

Limites com quatro outros conceitos:

Muitas pessoas confundem Skills com prompts, bases de conhecimento, MCP e agentes, mas eles são distintos:

Analogias comuns:

• Prompt = Enviar uma mensagem no WhatsApp para um funcionário; eles esquecem quando termina.
• Skill = Escrever um manual para o funcionário e colocá-lo em sua mesa, junto com uma caixa de ferramentas.
• Base de Conhecimento = Uma biblioteca que diz o que existe no mundo.
• MCP = Vários utensílios de cozinha que resolvem o problema "dá para fazer".
• Agente = Todo o sistema de funcionários, com memória e tomada de decisão; uma Skill é apenas uma parte dele.

Esses quatro não são mutuamente exclusivos.

No trabalho real, eles são frequentemente combinados: o MCP permite que o Claude se conecte ao Reddit para extrair dados, uma Skill o ensina a filtrar/classificar/recomendar esses dados, uma Base de Conhecimento fornece materiais da marca, e o Agente é o sistema inteiro executando o processo.

2. Arquitetura e Mecanismo de Operação

Estrutura de Arquivos

Cada subdiretório resolve um problema diferente, mas serve ao mesmo objetivo—economizar contexto e estabilizar a qualidade:

• scripts/: Cálculos precisos sem consumir contexto.
• references/: Carregado sob demanda para evitar desperdício de espaço.
• assets/: Padroniza formatos de saída.

Revelação Progressiva em Três Camadas—A Alma do Design de Skills

O mecanismo central de uma Skill é o carregamento em três camadas, que é o motivo pelo qual dezenas de Skills podem coexistir sem explodir o contexto:

Por exemplo:

Quando o Claude inicia, ele apenas folheia as "capas" de todas as Skills para decidir qual usar; só quando é hora de trabalhar ele abre o texto principal; e só quando precisa verificar um apêndice ele vai para as referências.

Esse mecanismo permite que você tenha 17 Skills ativas simultaneamente sem entupir a janela de contexto de 200K.

Metadados YAML

Descrições dos campos:

A Descrição Determina o Sucesso ou o Fracasso

Na arquitetura de três camadas, a descrição L1 é a mais crítica—ela determina se sua Skill será acionada.

Fatos importantes:

1. O Claude só lê as descrições de todas as Skills na inicialização.
2. Ele faz julgamentos semânticos com base na descrição, não em correspondência de palavras-chave.
3. O Claude tende a ser conservador: se não tiver certeza, não aciona. Em testes, descrições vagas tiveram uma precisão de acionamento de apenas 55%.

Exemplo negativo (nunca será acionado):

[Descrição vaga]

Exemplo positivo (estilo "insistente" recomendado pela Anthropic):

[Descrição específica]

Três Regras de Ouro para escrever descrições:

1. Escreva O QUE + QUANDO juntos: Diga o que faz e quando usar.
2. Liste palavras-gatilho em português e inglês: Corresponda ao que o usuário disser.
3. Seja insistente em vez de conservador: A Anthropic afirma explicitamente que o principal problema é o baixo acionamento.

3. Princípios Principais para Escrever Boas Skills

Três Princípios Principais

Como lidar com a liberdade:

Cinco Padrões de Design

A Anthropic resumiu cinco padrões de design de Skills de usuários iniciais:

Skills úteis geralmente misturam vários padrões. Você não precisa segui-los à risca, mas saber que eles existem ajuda a projetar com mais estrutura.

Regra de Ouro: Use "Por que" em vez de "Deve"

Esta é uma citação do código-fonte do skill-creator (a meta-skill oficial da Anthropic para fazer Skills):

"Tente explicar ao modelo por que as coisas são importantes em vez de usar 'DEVE' pesado e impositivo."

Exemplo negativo:

[Regras estritas de DEVE]

Exemplo positivo:

[Explicando o raciocínio]

No primeiro caso, o Claude seguirá apenas essas duas regras. Em situações não cobertas pelas regras (como um comando aparentemente seguro, mas arriscado), ele fica travado. No segundo caso, o Claude entende "por que a segurança é importante" e tenderá à cautela mesmo em áreas cinzentas.

Razões permitem que o modelo generalize; regras cobrem apenas cenários que você pode imaginar. A única exceção é o formato de saída: requisitos mecânicos como "a saída deve usar este modelo" não têm um "porquê" para explicar, então apenas codifique-os diretamente.

Propriedade da Informação: Não se Repita

O skill-creator também tem uma regra inflexível:

"A informação deve existir em SKILL.md ou nas referências—não em ambos."

O SKILL.md deve conter apenas procedimentos básicos; mova os detalhes para references/. O armazenamento duplicado leva a inconsistências quando você atualiza um local, mas esquece o outro.

Arquivos a Evitar

Skills são para IA, não para humanos. Não adicione README.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md ou CHANGELOG.md. Esses documentos humanos apenas desperdiçam contexto.

4. Construindo Sua Primeira Skill

As Seis Etapas Oficiais da Anthropic

O processo padrão definido dentro do skill-creator:

1. Capturar Intenção: Esclarecer o que fazer / quando acionar / formato de saída / necessidades de teste.
2. Entrevistar e Pesquisar: Casos extremos / formatos de E/S / arquivos de exemplo / dependências.
3. Escrever SKILL.md: Escrever o rascunho.
4. Casos de Teste: Escrever 2-3 casos de teste reais.
5. Executar e Avaliar: Executar com a skill e a linha de base (sem skill) lado a lado para uma referência.
6. Iterar: Modificar com base no feedback e reexecutar até ficar satisfeito.

Quatro Caminhos Rápidos para Usuários Comuns

skill-creator: A Meta-Skill para Escrever Skills

Eu recomendo fortemente instalar o skill-creator oficial da Anthropic primeiro. É uma Skill projetada para ajudá-lo a fazer Skills. Depois de iniciado, o Claude vai entrevistá-lo—perguntando sobre seu fluxo de trabalho, condições de acionamento e limites—e então gerar automaticamente o SKILL.md e a estrutura de pastas.

Comando de instalação:

[Comando]

Ele não apenas produz saída; ele também ajuda você a:

• Avaliar: Gerar automaticamente casos de teste para verificar se a Skill é acionada corretamente.
• Melhorar: Otimizar automaticamente descrições e instruções com base nos resultados dos testes, usando uma divisão de 60/40 treino/teste para evitar overfitting.
• Comparar: Acompanhar taxas de sucesso e uso de tokens, até mesmo executando testes A/B entre duas versões.

Um Exemplo Mínimo

Suponha que você seja um blogueiro de comida do Xiaohongshu que deseja reescrever receitas normais no estilo Xiaohongshu:

Coloque-o em ~/.claude/skills/xiaohongshu-recipe/SKILL.md. No futuro, dizer "converta para a versão Xiaohongshu" acionará automaticamente.

Desde a criação do arquivo até o uso, leva menos de 20 minutos.

5. Instalação, Armazenamento e Uso Entre Ferramentas

Prioridade de Carregamento (4 Níveis)

O Claude Code pesquisa na seguinte ordem; locais mais específicos têm prioridade mais alta:

Dica: A menos que seja específico do projeto, mantenha-os no diretório pessoal ~/.claude/skills/ para gerenciamento unificado.

Três Métodos de Instalação:

Lembre-se de reiniciar o Claude Code após a instalação.

Compatibilidade Entre Ferramentas (Enfatizado Novamente)

Como mencionado, Skills não estão vinculadas ao Claude. Aqui estão as comparações de caminho:

Significado operacional: Você pode criar um link simbólico da mesma pasta SKILL.md para diferentes diretórios de ferramentas. Este é o maior benefício do Agent Skills como um padrão aberto.

Pontos Problemáticos para Usuários Domésticos

• Claude oficial é caro: Use APIs de proxy para melhor custo-benefício.
• CC Switch: Uma ferramenta de código aberto para gerenciar e alternar várias configurações de API (github.com/farion1231/cc-switch).
• Instalação nativa é mais estável que npm: curl -fsSL https://claude.ai/install.sh | bash.

6. Avançado—Arquitetura de Colaboração Multi-Skill

Granularidade

Princípio Central: Uma tarefa clara por Skill. Não crie uma "Skill universal."

Se a granularidade for muito grossa, a descrição fica pouco clara e os acionamentos são imprecisos. Se for muito fina, os custos de gerenciamento aumentam. Uma granularidade razoável é uma Skill por categoria de problema, com um corpo de SKILL.md de cerca de 200-500 linhas.

Estudo de Caso: Suíte de Skill para Escrita de Blog

Não crie uma "Skill de Escrita Tudo-em-Um." Divida-a em 5 Skills colaboradoras:

Modo de colaboração: A Skill principal chama explicitamente outras Skills em sua seção ## Etapas.

Benefícios dessa divisão:

Cinco Experiências de Engenharia

1. Granularidade fina: Uma tarefa clara por Skill.
2. Colaboração explícita: Use ## Etapas na Skill principal para chamar outras.
3. Scripts para cálculo: Use scripts para contagens de caracteres SEO ou estatísticas de links; não deixe o modelo estimar.
4. Guias de estilo independentes: Coloque conhecimento estável (estilo de escrita/especificações da marca) em references/ para que você mude apenas um arquivo para atualizar o estilo.
5. Plano de fallback de modelo: Os modelos fornecem uma garantia de linha de base para que a saída não saia muito do esperado.

7. Avaliação e Iteração Profissionais

Sistema de Avaliação:

O processo padrão do skill-creator:

1. Escreva prompts de teste em evals/evals.json.
2. Execute with_skill e baseline (sem skill) simultaneamente para uma comparação duplo-cega.
3. Pontue cada afirmação usando agents/grader.md.
4. Use aggregate_benchmark para gerar um relatório sobre pass_rate / time / tokens.

Otimização Automática de Descrição

A parte mais valiosa do skill-creator é a Otimização de Descrição:

• Escreva 20 consultas de avaliação de acionamento (8-10 devem acionar + 8-10 não devem).
• Dificuldade: "Quase acertos" para não-acionamentos—consultas que compartilham palavras-chave, mas precisam de outras ferramentas.
• Script de otimização: 60% treino + 40% teste retido para evitar overfitting.
• Execute 5 rodadas e escolha a descrição com a maior pontuação de teste.

Bons exemplos de acionamentos: Não escreva apenas "extrair tabela PDF"; escreva como um usuário real:

"ok, então meu chefe acabou de me enviar este arquivo xlsx (está nos meus downloads, chamado algo como 'vendas Q4 final FINAL v2.xlsx') e ela quer que eu adicione uma coluna que mostre a margem de lucro como porcentagem."

Isso inclui caminhos de arquivo, contexto pessoal, nomes de colunas, linguagem casual e possíveis erros de digitação.

Mentalidade de Iteração

Quatro pontos do skill-creator:

1. Generalize a partir do feedback: Não adicione regras complicadas para um único caso. Se um problema se repetir, tente uma metáfora ou fluxo de trabalho diferente.
2. Mantenha enxuto: Verifique as transcrições em busca de instruções que desperdiçam tempo e exclua partes que não ajudam.
3. Explique o porquê: LLMs têm teoria da mente e podem generalizar.
4. Encontre trabalho redundante: Se todo subagente está escrevendo create_docx.py de forma independente, agrupe-o em scripts/.

A primeira versão nunca é perfeita.

Um caso real de iteração: A skill /daily de um autor levou 6 versões para se estabilizar.

• v1: Etapas pouco claras, caminhos errados.
• v2: Adicionou integração com sistema de descoberta de conteúdo.
• v3: Corrigiu erros de cálculo de progresso semanal.
• v4: Adicionou acionamentos automáticos (lembretes de terça-feira, arquivamento de fim de mês).
• v5: Adicionou modo claro do iPhone (pulando etapas do Python no celular).
• v6: Finalmente "bom de usar."

Uma Skill não é um arquivo de configuração que você configura e esquece; é um documento vivo do seu fluxo de trabalho.

8. Quando Você Deve Criar uma Skill?

Nem tudo vale uma Skill. Aja apenas quando um desses três sinais aparecer:

Por outro lado: Quando NÃO criar uma

• Tarefas únicas: Apenas use um prompt.
• Encapsulamento excessivo: Dividir Skills após apenas três usos; custos de manutenção superam os benefícios.
• Busca pela perfeição: Tentar fazer a v1 perfeita; você descobrirá que as necessidades eram imaginárias quando realmente usá-la.

9. Lista de Verificação de Armadilhas

10. Ecossistema e Lista de Itens Essenciais

Mapa de Recursos de Skills

Lista de Skills Essenciais

11. Potencial Comercial das Skills

Skills são mais do que ferramentas de eficiência pessoal; elas estão redefinindo como os aplicativos de IA são produzidos.

No passado, desenvolver um aplicativo de IA vertical exigia ciclos longos, altos custos e equipes técnicas. Agora:

• Limiar zero de código: Construa Agentes verticais sem programação.
• Validação rápida: Ciclos de desenvolvimento comprimidos de semanas para minutos.
• Serviço de API: Empacote uma Skill como uma API para potencializar produtos existentes.
• Skills como produtos: Semelhante a vender coleções de prompts, mas com maior valor.

Casos reais:

• Article-Copilot: Uma única Skill para toda a cadeia, desde a limpeza do material até a escrita.
• AI Partner Skill: Dá aos Agentes gerais memória profunda para se tornarem verdadeiros companheiros.
• Interview Prep Skill: Gera relatórios completos com base na empresa/cargo/currículo. Alguém usou isso para conseguir uma entrevista na Hithink RoyalFlush.
• Método do Super Huang: Dezenas de Skills + cron jobs executando relatórios por hora enquanto ele dorme.

Qualquer pessoa que seja profunda em um setor pode destilar sua experiência em uma Skill para economizar tempo ou vender como produto.

Conclusão

Se um Agente é o corpo do mundo da IA, uma Skill é a alma injetada nele.

É como a relação entre o Steam e a Workshop; a arquitetura extensível dá aos jogos vida infinita.

Skills não são difíceis—são apenas Markdown com alguma estrutura. Mas a tendência que elas representam é vital: a IA passando de "você tem que ensinar toda vez" para "você só ensina uma vez."

E o padrão é aberto. A Skill que você escreve para o Claude Code hoje pode ser movida para o Cursor ou Gemini amanhã.

Para aqueles que ainda estão observando:

Skills não são projetadas; elas crescem a partir do trabalho repetido.

Execute uma coisa primeiro, depois encapsule-a. Bons fluxos de trabalho são iterados, não planejados.

Abra seu terminal, instale o skill-creator e transforme aquele parágrafo que você repetiu três vezes hoje no seu primeiro SKILL.md.