aqui na Ratos de IA (o canal no YouTube onde eu, o Dudu, mostro IA na prática toda semana) a gente manda uma newsletter toda semana com o que rolou no vídeo, e ela sai de uma skill. é um arquivo de texto que ensina o Claude a pegar a transcrição do episódio (o vídeo semanal do canal) e devolver a newsletter no nosso formato, com o nosso tom. as skills do Claude são isso: uma pasta com um arquivo SKILL.md que guarda um processo teu, pra tu explicar uma vez e o agente repetir do mesmo jeito sempre. nesse post eu mostro o que é uma skill, a diferença pra prompt, MCP e agente, como é o arquivo por dentro e como criar a tua primeira.
pra ter uma ideia do quanto isso pegou aqui: hoje o repositório da DobraLabs (o laboratório de design, tecnologia e IA por trás do canal; repositório é a pasta de trabalho do time, versionada com git) tem 49 skills na raiz e mais 42 só na pasta de produção do Ratos de IA. tem skill pra proposta comercial, pra relatório de anúncio, pra descrição do YouTube, pra fechar a sessão de trabalho. quase tudo que a gente faz mais de duas vezes vira uma.
o que é uma skill do claude
uma skill do Claude é uma pasta com um arquivo SKILL.md dentro. o arquivo tem um cabeçalho curto (nome e descrição) e, embaixo, as instruções em texto comum. a pasta pode levar junto o que a tarefa precisar: um template, um exemplo aprovado, um guia de estilo, um script.
o que faz a skill funcionar é a descrição. segundo a documentação do Claude Code, numa sessão normal o Claude mantém só as descrições das skills no contexto, pra saber o que tem disponível, e carrega o conteúdo inteiro quando a skill é usada. a Anthropic chama isso de carregamento progressivo. na prática, tu pode ter dezenas de skills instaladas e o Claude só lê a que interessa naquela hora.
tem dois jeitos de uma skill rodar:
- sozinha: o Claude percebe que o teu pedido bate com a descrição e carrega a skill
- chamada: tu digita
/nome-da-skillno começo da mensagem
e um detalhe que confunde muita gente: os comandos personalizados antigos do Claude Code (os arquivos em .claude/commands/) foram juntados às skills. a doc diz que .claude/commands/deploy.md e .claude/skills/deploy/SKILL.md criam o mesmo /deploy. a skill só ganha a pasta pros arquivos de apoio e o disparo automático.
skill, prompt, CLAUDE.md, MCP e agente: qual a diferença
essa é a pergunta que mais aparece na Comunidade (o grupo de alunos que estuda IA com a gente), porque os cinco nomes parecem a mesma coisa. a tabela resume como a gente separa:
| o quê | serve pra | quando carrega | exemplo nosso |
|---|---|---|---|
| prompt | pedir uma coisa uma vez | só naquela mensagem | ”resume esse e-mail” |
| CLAUDE.md / AGENTS.md | regras e fatos que valem sempre | toda sessão, desde o começo | ”português do Brasil, sem travessão” |
| skill | um processo que se repete | quando o pedido bate com a descrição | /newsletter, /fechar |
| MCP | conectar um sistema de fora | as ferramentas aparecem quando precisa | Canva, Supabase |
| agente (subagente) | um trabalhador separado, com contexto próprio | quando o Claude delega | pesquisar 10 fontes em paralelo |
a régua prática: se tu cola o mesmo prompt toda semana, ele quer virar skill. se é uma regra curta que vale pra tudo, vai no arquivo de instruções do projeto, o CLAUDE.md ou o AGENTS.md. se o Claude precisa mexer num sistema que não está na tua pasta, aí entra o MCP. e na dúvida entre skill e agente, começa pela skill: ela gasta bem menos token.
como é o SKILL.md por dentro
o arquivo é texto com um cabeçalho entre ---. esse aqui é um modelo simples, no formato que a gente usa:
---
name: proposta-comercial
description: gera proposta comercial em HTML no padrão da casa. usar quando
pedirem proposta, orçamento ou escopo pra cliente.
---
# como montar a proposta
1. ler o briefing e listar o que o cliente pediu
2. usar o template.html desta pasta como base, sem mudar as cores
3. o preço vem depois da prova, nunca antes
4. no fim, perguntar se quer a versão com parcelamento
o que cada parte faz:
- name: vira o comando do menu
/. no Claude Code, se tu não puser, ele usa o nome da pasta - description: o que a skill faz e quando usar. é o campo que decide se ela dispara sozinha. a doc recomenda sempre preencher, e corta a descrição em 1.536 caracteres na listagem
- corpo: o passo a passo. escreve como se fosse pra alguém que acabou de entrar no time
no padrão aberto (agentskills.io), name e description são o mínimo. no Claude Code tem campos extras, tipo disable-model-invocation: true, que impede a skill de disparar sozinha (bom pra coisa que publica site ou manda mensagem) e deixa ela rodar só quando tu chama.
a doc também sugere manter o SKILL.md com menos de 500 linhas e mandar o material longo pra arquivos do lado (referencia.md, exemplos.md), citados dentro do SKILL.md. o Claude só abre esses arquivos quando precisa.
como criar a tua primeira skill, passo a passo
o jeito que eu mais recomendo pra quem está começando é fazer a tarefa uma vez com o Claude e só depois transformar em skill. assim tu ensina o processo que já deu certo, com os ajustes que tu fez no caminho.
- escolhe uma tarefa que tu repete. relatório da semana, resposta de orçamento, legenda de post. uma só, pequena
- faz ela uma vez numa conversa com o Claude. corrige até ficar do jeito que tu quer
- pede pra virar skill. algo como: “transforma o que a gente fez aqui numa skill chamada relatorio-semanal, com os passos e as correções que eu pedi”. o Claude Code tem o skill creator, uma skill da própria Anthropic que te entrevista e escreve o arquivo; no episódio em que a Anthropic lançou a versão nova dele a gente testou e a skill ficou com 92% de nota contra 83% sem ela (detalhes no post da DobraLabs sobre o teste A/B das skills)
- salva no lugar certo. se é só tua e vale pra tudo,
~/.claude/skills/relatorio-semanal/SKILL.md. se é do projeto e o time vai usar,.claude/skills/relatorio-semanal/SKILL.mddentro da pasta do projeto - testa dos dois jeitos. chama
/relatorio-semanale vê se sai certo. depois abre uma conversa nova e pede com outras palavras (“monta o relatório dessa semana”), pra ver se ela dispara sozinha - ajusta a descrição. não disparou, a descrição está vaga. disparou na hora errada, está ampla demais
no Claude do navegador e do app também dá. a central de ajuda da Anthropic manda ligar a execução de código em Settings › Capabilities, compactar a pasta da skill num ZIP e subir em Customize › Skills, no botão ”+”.
se tu quer as cinco formas de criar, incluindo a de gravar a tela fazendo a tarefa, tem o nosso guia de como criar skill no Claude.
exemplos das skills que a gente usa
três que rodam toda semana aqui, pra tu ver o tamanho real da coisa:
newsletter: pega a transcrição do episódio e devolve a newsletter pro Substack, a plataforma onde ela é enviada. a descrição diz exatamente quando usar (“quando o usuário enviar uma transcrição de vídeo do Ratos de IA e pedir para criar a newsletter”). títulos e descrição do YouTube ficam numa outra skill, adescricao-youtube, e cada uma faz uma coisa sófechar: no fim de uma sessão de trabalho, guarda o que aconteceu no lugar certo (documentação do projeto, decisões, o CRM, que é o sistema onde a gente acompanha clientes e propostas). dispara com frases como “fecha a sessão” ou “atualiza os docs”. o arquivo inteiro tem 98 linhasaprender-ratos: tu manda uma lista de links (vídeo, post, artigo), ela transcreve tudo e devolve o que as fontes ensinam em comum e onde discordam. no fim oferece transformar o aprendizado numa skill nova. essa a gente empacotou e vende na vitrine de skills
o padrão que se repete nas três: descrição com as frases que a pessoa realmente fala, uma tarefa por skill e exemplo aprovado na pasta quando o tom importa.
os erros mais comuns ao criar skill
pelo que a gente vê na Comunidade e pelas cagadas que a gente mesmo fez:
- descrição genérica. “ajuda com marketing” não dispara nunca, ou dispara sempre. escreve o “usar quando” com as palavras do teu pedido
- skill que faz tudo. uma skill de “conteúdo” que faz post, carrossel e e-mail vira uma bagunça. quebra em três
- regra que deveria estar no arquivo do projeto. “sempre em português” não precisa de skill, vai no CLAUDE.md ou no AGENTS.md
- chave de API dentro da skill. a pasta vai pro repositório e pode ir pra outras pessoas. a gente guarda chave num cofre de senhas e a skill só aponta pra ela
- instalar skill de qualquer lugar sem ler. skill pode rodar script na tua máquina. na Ratoeira, o portal que a gente fez pra rodar Claude Code, Codex e Grok num servidor pelo navegador, as skills da comunidade passam por revisão do time antes de aparecer na loja, e mesmo assim nenhuma roda com sudo
skill do claude roda em outro agente?
roda, e isso é o melhor argumento pra investir tempo em skill. a Anthropic lançou as skills em outubro de 2025, publicou o formato como padrão aberto em dezembro de 2025 e, em 22 de outubro de 2026, doou o Agent Skills pra Agentic AI Foundation, a fundação da Linux Foundation que já cuida do MCP. segundo o anúncio, mais de 70 plataformas leem o formato, entre elas ChatGPT, Cursor, GitHub Copilot e VS Code.
a gente comentou a doação no episódio #39, com uma alfinetada: o Claude ainda procura as skills na pasta .claude, e o resto do mercado usa .agents. aqui a gente resolveu com um atalho de sistema: a pasta real é .claude/skills e o .agents/skills aponta pra ela, então o Claude Code e o Codex leem as mesmas 49 skills da raiz. o passo a passo está no nosso guia de vários agentes num repositório só.
se tu ainda está chegando no Claude Code, começa pelo post de o que é o Claude Code e como começar e volta aqui pra primeira skill. escolhe a tarefa mais chata da tua semana e transforma ela hoje. a primeira versão sai meia-boca, e tudo bem: tu ajusta o arquivo e ela fica melhor a cada uso.