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

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

Você ensina algo a ela, inicia 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 este 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 mudam a produtividade", mas a maioria das pessoas só ouviu falar sem realmente entender a diferença entre Skills, prompts, bases de conhecimento, MCP e agentes—muito menos criar 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 é. 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 Claude Code, ~/.cursor/skills/ para Cursor, ou usada com OpenAI Codex, Gemini CLI, VS Code Copilot e JetBrains Junie.

A Skill que você escreve hoje pode ser movida 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 definidor de padrões 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 "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.

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 se torna imediatamente 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 este "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 uma 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 WeChat para um funcionário; eles esquecem assim que 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 "se pode ser feito".
• Agente = Todo o sistema de funcionários, com memória e tomada de decisão; uma Skill é apenas uma parte dele.

Estes quatro não são mutuamente exclusivos.

No trabalho real, eles são frequentemente combinados: MCP permite que o Claude se conecte ao Reddit para extrair dados, uma Skill ensina como 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.

Divulgaçã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 é a razão pela qual uma dúzia 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.

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

Metadados YAML

Descrições dos campos:

Descrição Determina Sucesso ou 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. 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 na correspondência de palavras-chave.
3. 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 acionamento insuficiente.

3. Princípios Centrais 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 frequentemente misturam vários padrões. Você não precisa segui-los estritamente, mas saber que eles existem ajuda a projetar com mais estrutura.

Regra de Ouro: Use "Porquê" 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 rígido."

Exemplo negativo:

[Regras estritas de DEVE]

Exemplo positivo:

[Explicando o raciocínio]

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

Razões permitem que o modelo generalize; regras só cobrem 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 de ferro:

"A informação deve existir em SKILL.md ou references—não em ambos."

SKILL.md deve conter apenas procedimentos básicos; mova os detalhes para references/. O armazenamento duplicado leva a inconsistências quando você atualiza um lugar, 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

Seis Passos 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. Entrevista e Pesquisa: 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-skill e linha de base (sem skill) lado a lado para um benchmark.
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. Uma vez iniciado, Claude irá 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:

• Eval: Gerar automaticamente casos de teste para verificar se a Skill é acionada corretamente.
• Improve: Otimizar automaticamente descrições e instruções com base nos resultados do teste, usando uma divisão 60/40 treino/teste para evitar overfitting.
• Benchmark: 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 culinária do Xiaohongshu que quer reescrever receitas comuns no estilo Xiaohongshu:

Coloque em ~/.claude/skills/xiaohongshu-recipe/SKILL.md. No futuro, dizer "converter para versão Xiaohongshu" irá acioná-la automaticamente.

Desde criar o arquivo até usá-lo leva menos de 20 minutos.

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

Prioridade de Carregamento (4 Níveis)

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 caminhos:

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 múltiplas 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 de Múltiplas Skills

Granularidade

Princípio Central: Uma tarefa clara por Skill. Não faça 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 Skills para Escrita de Blog

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

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

Benefícios desta divisão:

Cinco Experiências de Engenharia

1. Granularidade fina: Uma tarefa clara por Skill.
2. Colaboração explícita: Use ## Steps 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. Fallback de modelo: Modelos fornecem uma garantia de linha de base para que a saída não fique muito distante.

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

Sistema de Eval:

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 / tempo / 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 acionadores: 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 uma 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 caso isolado. 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 cada subagente está escrevendo create_docx.py independentemente, 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: Passos pouco claros, caminhos errados.
• v2: Adicionada integração com sistema de descoberta de conteúdo.
• v3: Corrigidos erros de cálculo de progresso semanal.
• v4: Adicionados acionadores automáticos (lembretes de terça-feira, arquivamento de fim de mês).
• v5: Adicionado modo claro do iPhone (pulando etapas do Python no celular).
• v6: Finalmente "boa de usar."

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

8. Quando Você Deve Fazer uma Skill?

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

Por outro lado: Quando NÃO fazer uma

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

9. Lista de Verificação de Armadilhas

10. Ecossistema e Lista de Imperdíveis

Mapa de Recursos de Skill

Lista de Skills Imperdíveis

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.
• Skill de Parceiro de IA: Dá aos Agentes gerais memória profunda para se tornarem verdadeiros companheiros.
• Skill de Preparação para Entrevistas: 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 de hora em hora enquanto ele dorme.

Qualquer pessoa com profundidade 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á vida infinita aos jogos.

Skills não são difíceis—elas são apenas Markdown com alguma estrutura. Mas a tendência que 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 em seu primeiro SKILL.md.