# Claude Code Skills em 2026: como criar uma biblioteca de skills para si > Como criar Claude Code Skills: estrutura do SKILL.md, fórmula para a descrição, coleções prontas da Anthropic e práticas a evitar. Passo a passo em 30 minutos. Source: https://ailoot.ai/blog/pt-pt/claude-code-skills-library/ Canonical: https://ailoot.ai/blog/pt-pt/claude-code-skills-library/ Language: pt-PT Publisher: Ailoot (https://ailoot.ai/) Translation: guide-213 Revision: sha256-44d3c2d1d2588c06cd7d65ec5e1ad8bb035c7bbdbf06ce84a76e25b3d8102332
Pontos principais As Claude Code Skills são pastas que contêm um ficheiro SKILL.md, carregado para o contexto pelo Claude apenas quando necessário. O CLAUDE.md permanece sempre na memória e consome o orçamento de tokens, enquanto uma skill é carregada quando é acionada — e podem coexistir facilmente dezenas de skills num só projeto. A parte mais importante de uma skill é a sua descrição: é com base nela que o Claude decide se deve ativá-la. Neste artigo, explico a estrutura do SKILL.md, a fórmula para a descrição, coleções prontas e como criar a sua primeira skill em 30 minutos.
[Documentação da Ailoot: API, chaves e configuração](https://ailoot.ai/docs/). ## O que é uma skill no Claude Code e porque não é apenas «um prompt maior»?
Pontos principais Uma skill é um diretório que contém um ficheiro SKILL.md com instruções sobre quando e como aplicar uma metodologia específica. A Anthropic compara uma skill às instruções dadas a um novo colaborador: não lhe dita cada passo todos os dias; dá-lhe um procedimento, que ele próprio aplica nas situações certas. A principal diferença em relação ao CLAUDE.md é que uma skill só é carregada no contexto quando necessário, pelo que podem existir dezenas de skills num projeto sem esgotar o orçamento de tokens.
Claude Code Skills é uma funcionalidade nativa do Claude Code, lançada pela Anthropic em outubro de 2025 para os planos Pro/Max/Team/Enterprise. Mais tarde, a Anthropic disponibilizou a especificação [Agent Skills](https://agentskills.io) como norma que também funciona fora do Claude. No código, é simplesmente uma pasta: ``` .claude/skills/ ├── deploy-to-prod/ │ ├── SKILL.md │ └── scripts/ │ └── check-migrations.sh ├── weekly-content-plan/ │ └── SKILL.md └── triage-support-tickets/ └── SKILL.md ``` Cada pasta corresponde a uma skill. O ficheiro `SKILL.md` é um documento Markdown com YAML frontmatter no início e instruções correntes abaixo. Quando um utilizador pede «vamos fazer a implementação em produção», o Claude vê a descrição da skill `deploy-to-prod`, reconhece o acionador «fazer a implementação em produção», carrega o corpo do SKILL.md para o contexto e segue os passos. ### Três níveis de carregamento progressivo A Anthropic concebeu as skills com carregamento progressivo: os dados são carregados por camadas, conforme necessário. No blogue da Anthropic Engineering, a equipa descreve-o como o «princípio de conceção fundamental que torna os Agent Skills flexíveis e escaláveis» ([Anthropic Engineering](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)). Os três níveis de carregamento: 1. **Metadados (sempre)** — quando uma sessão começa, o Claude vê apenas `name` e `description` de cada skill. Orçamento: cerca de 100 tokens por skill. 2. **Instruções (quando acionada)** — quando o utilizador diz algo relevante, o Claude carrega o corpo do SKILL.md. Orçamento: menos de 5000 tokens. 3. **Recursos (a pedido)** — os ficheiros incluídos (exemplos, modelos, conjuntos de dados) só são obtidos quando o próprio modelo os procura. Orçamento: ilimitado. Anteriormente, o [CLAUDE.md](https://ailoot.ai/blog/pt-pt/claude-md-template/) tinha de conter tudo aquilo de que a IA devia «lembrar-se» — e um projeto com 50 regras atingia rapidamente o limite de contexto. Com as skills, podem coexistir facilmente dezenas delas num projeto, porque apenas as respetivas descrições entram no contexto inicial. ### Onde guardar as skills: quatro níveis | Nível | Caminho | Aplica-se a | |------------|-----------------------------------|--------------------| | Enterprise | Definições da organização gerida | Todos os utilizadores da empresa | | Pessoal | `~/.claude/skills//SKILL.md` | Todos os seus projetos | | Projeto | `.claude/skills//SKILL.md` | Apenas este projeto | | Plugin | `/skills//SKILL.md` | Onde o plugin estiver ativado | Prioridade: enterprise sobrepõe-se às definições pessoais, e as pessoais às do projeto. Os plugins usam o espaço de nomes `plugin-name:skill-name` e não entram em conflito. É prático: coloque as skills profissionais gerais em `~/.claude/skills/` e as específicas do projeto em `.claude/skills/`, no repositório. ## O que contém um SKILL.md?
Pontos principais O SKILL.md é um ficheiro Markdown com YAML frontmatter no início e texto de instruções abaixo. Tem, no mínimo, dois campos: name (até 64 caracteres) e description (até 1024 caracteres). O esquema completo inclui allowed-tools, disable-model-invocation, paths, context: fork, agent e hooks. A Anthropic recomenda manter o corpo das instruções abaixo das 500 linhas e colocar tudo o resto em ficheiros de referência próximos.
Eis um exemplo mínimo — vinte linhas e a skill está pronta: ```markdown --- name: weekly-content-plan description: Prepara um plano semanal de publicações para um canal de Telegram e vídeos curtos. Acionadores — «cria um plano de publicações», «o que devo publicar esta semana», «um plano de 7 dias para o canal». Não ativar se o pedido for sobre um site ou uma newsletter por e-mail. --- # Plano semanal de conteúdos ## Passos 1. Lê `knowledge/audience.md` — para quem escrevemos 2. Lê `knowledge/tone-of-voice.md` — como escrevemos 3. Lê as últimas 10 publicações do canal — o que já foi abordado 4. Propõe 7 temas para a semana: 3 orientados para vendas, 2 especializados, 2 pessoais 5. Para cada tema, apresenta uma frase de abertura e três pontos sobre a publicação 6. Apresenta o resultado numa tabela: dia da semana | tipo | frase de abertura | plano ``` É suficiente. Se um utilizador escrever «vamos planear as publicações para esta semana», o Claude reconhece o acionador na descrição, carrega o SKILL.md, lê os ficheiros indicados e apresenta uma tabela. ### Limites a ter em conta A [documentação oficial da API do Claude](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) define limites rigorosos: - **`name`**: até 64 caracteres; apenas letras minúsculas, números e hífenes, sem etiquetas XML. `anthropic` e `claude` estão reservados. - **`description`**: até 1024 caracteres na API; obrigatório e sem etiquetas XML. - **Orçamento da listagem**: no Claude Code, as descrições de todas as skills ocupam, em conjunto, cerca de 1% da janela de contexto. Se houver muitas skills, as descrições serão truncadas — e as palavras-chave de que o Claude precisa para identificar uma correspondência podem desaparecer. - **Corpo do SKILL.md**: a Anthropic recomenda manter o corpo abaixo das 500 linhas. Transfira tudo o que for mais extenso para ficheiros `references/`, `scripts/` e `examples/` e carregue-os através das instruções. Após a compactação do contexto (`/compact`), o Claude retém os primeiros 5000 tokens de cada skill anteriormente invocada; o orçamento total para todas as skills novamente anexadas é de 25 000 tokens. Se uma skill não couber, o seu comportamento será «esquecido». ### Esquema completo do frontmatter Use pelo menos `name` e `description`. As skills de produção também usam outros campos: | Campo | Finalidade | Exemplo | |----|----|----| | `name` | Nome da skill; se for omitido, usa-se o nome da pasta | `deploy-to-prod` | | `description` | Acionador para invocação automática | Consulte a fórmula abaixo | | `when_to_use` | Frases de acionamento adicionais | `["deploy", "vamos publicar"]` | | `allowed-tools` | Ferramentas que podem ser usadas sem pedir autorização | `["Read", "Bash(npm run build)"]` | | `disable-model-invocation` | `true` — só o utilizador pode invocá-la | Para operações perigosas | | `user-invocable` | `false` — só o Claude pode invocá-la | Para conhecimento de fundo | | `paths` | Padrões glob que determinam onde a skill está ativa | `["src/**/*.ts"]` | | `context: fork` | Executa num subagente isolado | Quando o contexto é extenso | | `agent` | Tipo de subagente a iniciar | `Explore`, `Plan`, `general-purpose` | | `effort` | Nível de raciocínio | `low`, `medium`, `high`, `xhigh`, `max` | | `model` | Modelo atribuído à skill | `claude-opus-4-7` | | `hooks` | Hooks no ciclo de vida da skill | Consulte a secção sobre hooks | O campo `disable-model-invocation: true` é essencial para tudo o que não deve ser executado automaticamente. Por exemplo, uma skill `deploy-to-prod` com esta opção só pode ser invocada se o utilizador escrever explicitamente `/deploy-to-prod`. Sem esta opção, o Claude poderia fazer a implementação porque «o código parece estar pronto». ## Porque é que a descrição representa 90% do trabalho e como se escreve uma?
Pontos principais A descrição é o único campo que o Claude vê no início de uma sessão. Se estiver mal escrita, a skill não funcionará, mesmo que o corpo das instruções seja perfeito. Uma boa descrição tem três partes: o que faz + frases de acionamento entre aspas + quando NÃO deve ser utilizada. No seu próprio `skill-creator`, a Anthropic recomenda descrições «ligeiramente insistentes» — o Claude tende a acioná-las menos do que devia.
O erro mais comum dos vibe-coders é escrever uma descrição como «Ajuda com X». A skill existe fisicamente na pasta, mas o Claude não a invoca. ### Uma descrição má ```yaml description: Cria painéis de controlo. ``` O que o Claude não consegue perceber: quando o utilizador pede «mostra-me as vendas da semana», trata-se de um painel de controlo? Quando pede um «gráfico de receitas», trata-se de um painel ou apenas de um gráfico em geral? Um «relatório mensal» não é certamente um painel de controlo? O próprio [skill-creator da Anthropic](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md) apresenta a recomendação de forma direta:

Atualmente, o Claude tem tendência para «não acionar suficientemente» as skills — ou seja, não as utiliza quando seriam úteis. Para contrariar esta tendência, torne as descrições das skills um pouco «insistentes».

— Anthropic Skill Creator (SKILL.md), https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md
### A fórmula para uma boa descrição Três partes: 1. **O que faz** — uma frase sobre o resultado, não sobre o processo. Não «gera SQL», mas «exporta as vendas para uma tabela num canal de Telegram». 2. **Quando a acionar** — 3–5 frases entre aspas que os utilizadores dizem realmente. Não adivinhe; consulte o histórico das suas conversas e do suporte. 3. **Quando NÃO a acionar** — 1–2 frases sobre tarefas semelhantes às quais a skill não deve responder. Sem esta secção, duas skills semelhantes continuarão em conflito. Um exemplo de uma descrição eficaz do meu projeto (simplificado e anonimizado): ```yaml description: | Escreve e publica um guia de SEO no blogue, seguindo a política editorial. Acionadores: «escreve um guia sobre X», «vamos criar um novo pilar», «um artigo de blogue sobre Y», «cria um guia de blogue sobre Z». Não ativar se o pedido for sobre uma newsletter por e-mail, uma publicação no Telegram ou uma instrução interna para a equipa — essas tarefas pertencem a outras skills. ``` O que funciona aqui: - O verbo «escreve e publica», em vez de «ajuda com», especifica um resultado concreto. - Quatro frases de acionamento entre aspas abrangem diferentes formulações. - Também é incluído um acionador em inglês — a skill continuará a funcionar se o utilizador mudar para o idioma da equipa. - Uma secção separada «não ativar se» evita conflitos com as skills de e-mail e de publicações. ### Como testar uma descrição No seu `skill-creator`, a Anthropic incluiu uma metodologia de trigger-evals: 20 prompts para verificar se uma skill é ativada. Dez devem acioná-la e dez não (incluindo situações semelhantes em que a formulação é próxima, mas a tarefa é diferente). Em termos de vibe-coder, isto significa que, depois de escrever a descrição, deve abrir uma conversa em branco e experimentar 5 frases que utiliza mesmo, mais 3 frases semelhantes com outro significado. Se a skill não for ativada quando devia, ou for ativada quando não devia, reveja a descrição. Só depois escreva o corpo das instruções. ## Que 5 skills instalaria primeiro?
Pontos principais A estratégia mais rápida para um empreendedor é começar com coleções prontas e personalizá-las. A Anthropic e a Vercel publicaram coleções públicas que podem ser instaladas com um só comando e abrangem tarefas habituais, como documentos e design. Em maio de 2026, o repositório oficial `anthropics/skills` tinha cerca de 138 000 estrelas.
Passar as primeiras duas semanas a escrever skills próprias é uma estratégia perdedora. Comece por instalar algumas prontas e perceber como foram criadas; depois acrescente as suas, seguindo a mesma abordagem. É mais barato pegar em coleções comprovadas por outras pessoas e personalizá-las do que construir tudo de raiz. Estas são cinco coleções por onde começaria: ### 1. anthropics/skills — coleção oficial com skill-creator Repositório: [github.com/anthropics/skills](https://github.com/anthropics/skills). 138 000 stars no GitHub. Contém skills oficiais da equipa da Anthropic: `skill-creator` (uma meta-skill que escreve outras skills), `claude-api` (ajuda a criar integrações com APIs) e skills prontas para documentos PowerPoint, Excel, Word e PDF. Instalação no Claude Code: ```bash /plugin marketplace add anthropics/skills /plugin install document-skills@anthropic-agent-skills /plugin install example-skills@anthropic-agent-skills ``` O principal valor está na `skill-creator`. Com base na sua descrição, escreve um SKILL.md, executa 20 trigger-evals e revê a descrição até a skill começar a ser ativada nas situações certas. Em essência, é «uma skill para criar skills». ### 2. mattpocock/skills — a coleção viral de um especialista em TypeScript Contém 12 skills ativas, incluindo: Instalação: ```bash npx skills@latest add mattpocock/skills /setup-matt-pocock-skills ``` ### 3. coreyhaines31/marketingskills — uma coleção para profissionais de marketing Se gere programas online, trabalha como profissional de marketing freelancer ou gere uma agência, não precisa de passar seis meses a escrever as suas próprias skills. Metade das tarefas já está preparada. ### 4. vercel-labs/agent-skills — design sem aspeto de IA Repositório: [github.com/vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills). A sua skill de maior destaque é `web-design-guidelines`. Audita o código da interface segundo regras de acessibilidade, desempenho e facilidade de utilização. A par desta, existe a [frontend-design da Anthropic](https://github.com/anthropics/skills/tree/main/skills/frontend-design), com mais de 110 000 instalações semanais. Faz com que a IA escolha um estilo antes de começar a escrever código. Sem ela, todas as páginas geradas pelo Claude têm o tipo de letra Inter, um gradiente roxo e cartões em grelha. O resultado é igual para toda a gente. ### 5. obra/superpowers — workflow multiagente Em suma, se instalar as três primeiras coleções da lista — `anthropics/skills`, `mattpocock/skills` e `coreyhaines31/marketingskills` — o seu Claude Code terá dezenas de skills prontas a utilizar para a maioria das tarefas de um empreendedor logo no primeiro mês. Quer não só instalar skills prontas, mas também criar **uma configuração que faça do Claude o seu verdadeiro assistente**? As skills são um dos três pilares da metodologia. Uma configuração funcional tem três partes: **clone de IA** (Skills como conhecimentos especializados empacotados) + **[Segundo Cérebro](https://ailoot.ai/blog/pt-pt/claude-code-second-brain/)** (uma estrutura de conhecimento para fornecer contexto) + **Engenharia de Contexto** (a forma como o Claude vê o projeto como um todo). Esta configuração transforma o Claude de um assistente que adivinha numa ferramenta que pensa segundo a sua lógica. ## Que tarefas repetitivas deve transformar numa skill?
Pontos principais A regra é simples: qualquer atividade que faça mais de duas vezes por semana e que siga, grosso modo, os mesmos passos pode ser uma skill. Não um «relatório para o auditor, uma vez por ano» complexo, mas trabalho rotineiro: um plano de conteúdos para um canal, a verificação de recibos de clientes ou um e-mail de boas-vindas para um novo participante. Uma skill transforma uma tarefa pontual num recurso que funciona sem si.
No trabalho com clientes e em projetos de outras pessoas, já vi este padrão dezenas de vezes. Alguém tem «aquela tarefa que faz sempre de raiz». Todas as segundas-feiras, escreve o mesmo tipo de relatório. Sempre que chega um novo cliente, segue o mesmo procedimento. Cada publicação usa o mesmo modelo. E cada vez demora 30–90 minutos, porque é preciso recordar os passos, abrir os ficheiros certos e voltar a formular o prompt para o Claude. A solução é transformar esse procedimento numa skill uma única vez. Depois, basta dizer uma frase: o Claude carrega a metodologia, lê as fontes necessárias e produz o resultado. Eis três exemplos de áreas diferentes: ### Exemplo 1. Profissional de marketing freelancer — skill `weekly-content-plan` O que faz manualmente: todas as segundas-feiras prepara as publicações semanais de Telegram para três clientes. Abre o guia de voz da marca do cliente, revê as publicações recentes, pensa em temas com base no calendário de produtos e cria uma tabela com frases de abertura e pontos principais. Como skill, transforma-se numa instrução de cinco passos: ler o ficheiro sobre o tom de voz do cliente, ler o calendário de produtos, verificar as últimas 10 publicações para evitar repetições, propor sete temas por tipo (vendas, especializados e pessoais) e apresentar uma tabela. O comando «vamos planear as publicações da semana para o cliente X» transforma uma hora de preparação em três minutos de espera. O profissional de marketing verifica o resultado, faz alterações específicas e envia-o ao cliente. ### Exemplo 2. Contabilista externo — skill `monthly-receipts-close` (exemplo do autor) O que faz manualmente: todos os meses, para cada cliente da carteira, exporta o extrato bancário, reconcilia-o com os pagamentos no sistema de contabilidade, assinala os pagamentos não classificados, prepara um relatório preliminar de rendimentos e compara a estrutura dos rendimentos com a do mês anterior. A skill consiste numa instrução de seis passos e em alguns scripts shell na pasta `scripts/` para analisar extratos bancários. O acionador «fecha maio para o cliente X» leva o Claude a produzir, em 4–5 minutos, um relatório com as anomalias assinaladas. ### Exemplo 3. Criador de um programa online — skill `welcome-letter-new-participant` O que faz manualmente: um novo participante pagou e é preciso escrever-lhe um e-mail de boas-vindas. Uma boa mensagem é pessoal: tem em conta o canal de onde veio, o produto que comprou, o grupo em que está e os materiais que deve receber. Um modelo com «olá, ficamos muito contentes» não faz isso. A skill instrui o Claude a ler `knowledge/audience.md` (quem são estas pessoas), `knowledge/products/.md` (o que recebem) e os três últimos e-mails de boas-vindas (para evitar repetições); depois, deve escrever o e-mail com esta estrutura: frase de abertura — detalhes do produto — três primeiros passos — despedida. Muito mais rápido do que fazê-lo manualmente. A qualidade é mais consistente porque o Claude se lembra de consultar três fontes, enquanto uma pessoa com pressa pode ignorar uma delas. ### O que NÃO deve transformar numa skill - **Tarefas pontuais.** Se só faz algo uma vez por ano, ao entregar a declaração de impostos, basta descrevê-lo ao Claude no chat. Uma skill compensa após 3+ repetições. - **Tarefas demasiado gerais.** «Ajuda-me com o marketing» não é uma skill; abrange todo o marketing. Uma skill é «plano semanal de conteúdos» — uma atividade específica com um resultado específico. - **Tarefas sem passos repetíveis.** Se o processo muda todas as vezes, não é uma skill; é trabalho pontual. ## Como é que o Skill Creator escreve skills por si?
Pontos principais O Skill Creator é uma meta-skill da Anthropic, lançada com o comando `/skill-creator`. Guia-o por seis passos: elaborar, testar, avaliar, iterar, otimizar e empacotar. O resultado é um SKILL.md pronto a usar, testado com 20 trigger-evals (10 em que deve ser acionado e 10 em que não deve). Para quem não programa, é a forma mais rápida de escrever uma primeira skill funcional — sem ter de aprender YAML nem de discutir com o Claude.
A dificuldade é escrever uma boa skill à primeira. A descrição acaba muitas vezes demasiado específica ou demasiado abrangente, não inclui as frases que os utilizadores realmente usam ou entra em conflito com uma skill próxima. A Anthropic respondeu a este problema ao lançar o [skill-creator](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md), uma meta-skill capaz de criar outras skills. Depois de instalar `anthropics/skills`, diga ao Claude `/skill-creator` (ou simplesmente «vamos criar uma skill para o relatório semanal») e siga um workflow de seis fases: 1. **Elaboração** — o skill-creator faz perguntas: o que deve fazer a skill, que frases a devem acionar, que fontes deve consultar e que passos deve seguir. O resultado é a primeira versão do SKILL.md. 2. **Teste** — o skill-creator gera 20 prompts de teste: 10 que devem acionar a skill e 10 que parecem acionadores, mas não a devem acionar (casos semelhantes, mas não correspondentes). 3. **Avaliação** — executa cada prompt numa conversa nova e verifica se a skill foi ativada. Se for ativada quando não devia ou não for ativada quando devia, assinala o resultado. 4. **Iteração** — reescreve a descrição com base nas falhas e volta a executar os testes. 5. **Otimização** — retoques finais: verifica se o limite de 1024 caracteres foi ultrapassado e se há conflitos com skills existentes do projeto. 6. **Empacotamento** — organiza o SKILL.md final e os ficheiros de referência na estrutura correta. Na prática, funciona assim: conversa com o Claude durante 15–20 minutos, responde a 7–8 perguntas de esclarecimento e, no fim, obtém uma skill pronta e testada, que é ativada pelos acionadores certos. Outra vantagem é que o `skill-creator` demonstra um estilo exemplar de escrita para SKILL.md. Pode abrir o ficheiro dele e ver o formato, o tom e a estrutura dos passos. É um caso em que a ferramenta se demonstra a si própria — lê-se e aprende-se a criar uma skill. ## Skills, CLAUDE.md, subagentes, MCP, Hooks: qual deve utilizar?
Pontos principais O Claude Code tem cinco mecanismos distintos para expandir o comportamento, e não são intercambiáveis. CLAUDE.md contém conhecimento permanente sobre o projeto. As skills são workflows repetíveis ativados por acionadores. Os subagentes executam trabalho em paralelo, num contexto separado. O MCP liga sistemas externos (APIs, bases de dados). Os hooks reagem automaticamente a eventos. O erro mais comum dos vibe-coders é colocar tudo no CLAUDE.md ou tentar criar uma skill com um hook.
O problema mais comum nos projetos que revi é encontrar no CLAUDE.md as regras do projeto, instruções passo a passo para publicar, um modelo de commit e a descrição da base de dados, tudo junto. Isto sobrecarrega o contexto e também falha na prática: o Claude não executa a instrução «quando o utilizador pedir para publicar», porque o modelo trata todo o CLAUDE.md como contexto geral sem acionadores explícitos. A solução é atribuir cada elemento ao mecanismo adequado: | O quê | Quando utilizar | Exemplo | |----|----|----| | **CLAUDE.md** | Conhecimento necessário SEMPRE | «O projeto tem um idioma definido», «não usar travessões longos no texto», «a marca escreve-se com um “o”» | | **Skills** | Processo repetível ativado por um acionador | «Implementar em produção», «plano semanal de publicações», «fechar a contabilidade mensal do cliente» | | **Subagents** | Trabalho paralelo ou isolamento de um contexto extenso | «Auditoria de segurança enquanto planeio uma nova funcionalidade», «rever a base de código numa sessão separada» | | **MCP** | Ligação a um sistema externo | «Obter dados do CRM», «ir buscar tarefas ao sistema de acompanhamento», «verificar o site num browser» | | **Hooks** | Resposta automática a um evento | «Executar uma verificação após Edit», «bloquear comandos perigosos», «enviar uma notificação de Telegram quando terminar» | Em suma, tudo se resume a uma lógica simples: as Skills e o MCP abrangem a maioria dos fluxos de trabalho; os Hooks automatizam tarefas de rotina — verificações de código, testes e proteções. Os subagentes são necessários quando o contexto se torna extenso. O erro mais comum é criar um subagente quando devia usar-se uma skill. ### Árvore de decisão Quando pensa «preciso que o Claude faça X»: 1. **Este conhecimento é sempre necessário?** Por exemplo, «o projeto tem um idioma definido» ou «não usamos travessões longos». → Coloque-o no `CLAUDE.md`. 2. **É um procedimento acionado por uma situação que agora executa manualmente?** Por exemplo, «escrevo um relatório todas as segundas-feiras». → Crie uma **skill**. 3. **Precisa de aceder a um sistema externo?** Por exemplo, à API Stripe ou ao CRM. → Ligue um **servidor MCP**. 4. **O Claude Code deve reagir automaticamente a um evento?** Por exemplo, executar um linter após cada Edit. → Crie um **hook**. 5. **A tarefa é pesada, vai consumir todo o contexto e precisa de fazer outra coisa em paralelo?** → Execute um **subagente**. 90% das tarefas de um empreendedor vibe-coder pertencem às categorias 1–3. Os Hooks e subagentes são ferramentas mais avançadas, para quando já ultrapassou a fase de «uma tarefa de cada vez». ### Os comandos Slash e as skills são a mesma coisa O Claude Code teve uma alteração importante: o antigo sistema de comandos slash (`.claude/commands/`) e as skills fundiram-se, na prática. O ficheiro `.claude/commands/deploy.md` e `.claude/skills/deploy/SKILL.md` criam ambos um comando `/deploy`. Se os nomes coincidirem, a skill prevalece. Por isso, se ainda usa o antigo formato de comandos slash, passe para as skills: a sintaxe é mais clara e há mais funcionalidades. ## 7 erros que impedem uma skill de funcionar
Pontos principais Os problemas mais comuns das skills não são falhas do Claude; são erros na própria skill. Uma descrição sem acionadores, um SKILL.md sobrecarregado com 2 000 linhas, duas skills semelhantes em conflito ou uma tentativa de descarregar «tudo o que existe no marketplace». Cada um destes erros prejudica a ativação da skill ou o seu funcionamento.
### 1. Descrição sem acionadores: a skill não é ativada Sintoma: escreveu uma skill, verificou a estrutura e tudo está válido, mas o Claude não a invoca perante os pedidos dos utilizadores. A causa é quase sempre a mesma: uma descrição como «Ajuda a escrever conteúdos». O Claude não sabe a que frases deve responder. Solução: inclua diretamente na descrição 3–5 frases reais dos utilizadores, entre aspas. ### 2. SKILL.md com mais de 500 linhas: a atenção dispersa-se A Anthropic [recomenda expressamente](https://code.claude.com/docs/en/skills) manter o corpo do ficheiro abaixo das 500 linhas. Se as suas instruções tiverem 2 000 linhas, o Claude perde o foco, segue apenas parte dos passos e confunde-se com a ordem. Solução: mova secções extensas para ficheiros próximos — `examples/`, `references/`, `scripts/` — e faça referência a esses ficheiros no SKILL.md. ### 3. Uma skill para «tudo sobre conteúdos» em vez de três pequenas É tentador criar uma grande skill `content` com publicações de Telegram, landing pages e e-mails. Não funciona. A skill é ativada para pedidos errados, mistura metodologias e produz um resultado mediano. Solução: uma skill = uma atividade repetível. Se tem mesmo três rotinas de «conteúdos», crie três skills: `telegram-post`, `landing-section`, `email-broadcast`. ### 4. Skill sem uma secção «Quando NÃO a utilizar»: conflitos Sintoma: há duas skills semelhantes no projeto e o Claude invoca a errada. Por exemplo, uma skill trata de uma newsletter por e-mail e outra especificamente dos e-mails de boas-vindas para participantes de um programa. Sem uma cláusula explícita «não ativar se o pedido for sobre uma lista de distribuição geral», a skill de boas-vindas será acionada sempre que houver uma referência a «e-mail». Solução: especifique os casos negativos na descrição. ### 5. 50 skills num projeto: as descrições são truncadas Da [documentação do Claude Code](https://code.claude.com/docs/en/skills):

Os nomes das skills são sempre incluídos, mas, se houver muitas, as descrições são truncadas para respeitar o limite de caracteres. Isto pode remover as palavras-chave que o Claude usa para associar o seu pedido. Orçamento — 1% da janela de contexto do modelo.

— Claude Code Documentation, https://code.claude.com/docs/en/skills
Se descarregou 50 coleções de skills de um marketplace, algumas descrições serão truncadas. As palavras-chave em que contava podem desaparecer. Solução: mantenha as 10–15 skills mais úteis no projeto ativo. Mantenha as restantes num arquivo inativo fora de todas as pastas de descoberta, por exemplo `skill-archive/` separado nos seus materiais. Instale só as necessárias no âmbito do projeto ou pessoal. `~/.claude/skills/` é biblioteca pessoal instalada disponível entre projetos; movê-las para aí não as retira da descoberta. ### 6. Skills de fontes não verificadas: risco de segurança A Anthropic alerta para este risco na [documentação oficial](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview):

Utilize skills apenas de fontes fidedignas: as que criou ou recebeu da Anthropic. Uma skill maliciosa pode levar o Claude a chamar ferramentas ou executar código de formas diferentes da finalidade declarada da skill.

— Anthropic Agent Skills Overview, https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
Um repositório aleatório do GitHub pode conter uma skill que revela as suas chaves de API na primeira vez que a invoca. Solução: abra o SKILL.md e leia-o antes de instalar. Não execute skills de autores desconhecidos em projetos importantes. ### 7. Uma skill sem uma pasta de conhecimento produz um «ChatGPT mediano» O antipadrão mais subtil e mais comum. Uma skill é uma metodologia, mas, sem contexto, a metodologia por si só não significa nada. Se escrever uma skill «criar um e-mail de boas-vindas», mas o projeto não tiver um ficheiro que descreva o público nem um ficheiro sobre a voz da marca, o Claude vai escrever um e-mail mediano, indistinguível dos de toda a gente. Uma skill funciona melhor quando já criou o [Segundo Cérebro](https://ailoot.ai/blog/pt-pt/claude-code-second-brain/) do projeto de acordo com os princípios do [guia sobre o CLAUDE.md](https://ailoot.ai/blog/pt-pt/claude-md-template/). Primeiro, construa a estrutura de conhecimento; depois, crie skills que se apoiem nela. Se inverter a ordem, terá um trabalho rotineiro e mediano em vez de trabalho personalizado ao seu estilo. ## Como criar a sua primeira skill em 30 minutos
Pontos principais Um guia passo a passo para criar a sua primeira skill funcional: escolha uma atividade repetível, escreva os passos, crie a estrutura de pastas, escreva a descrição usando a fórmula, teste-a com 5–8 prompts e continue a iterar até ser ativada nas situações certas. Um prazo realista para a primeira skill é 30–40 minutos. Cada uma das seguintes demora 10–15 minutos, porque já conhecerá o formato.
Eis o plano concreto que usei para criar as primeiras skills dos meus projetos: ### Passo 1. Escolha uma atividade repetível Abra o calendário do último mês. Encontre uma tarefa que tenha executado pelo menos 4–5 vezes e que demore 30–60 minutos de cada vez. Não algo abrangente como «marketing», mas algo específico: «relatório de vendas de segunda-feira», «integração de um novo cliente» ou «atualização da tabela de preços para uma promoção». Quanto mais específica for a formulação, mais simples será a skill e mais preciso o acionador. ### Passo 2. Escreva o processo manualmente Num ficheiro separado ou numa conversa com o Claude (não para a skill, mas como rascunho), escreva os passos que segue: ``` 1. Abre a base de dados de clientes 2. Filtra pelo estado "à espera do e-mail de boas-vindas" 3. Verifica por que canal o cliente chegou 4. Vai buscar à pasta "templates" o modelo de e-mail para esse canal 5. Preenche o nome, o produto e a data de início 6. Envia ``` Isto ainda não é uma skill; são notas. Mas, sem estas notas, vai começar por se atrapalhar ao escrever o SKILL.md. ### Passo 3. Crie a estrutura de pastas ```bash mkdir -p .claude/skills/welcome-email-new-client touch .claude/skills/welcome-email-new-client/SKILL.md ``` Ou, se quiser utilizar a skill em todos os seus projetos, coloque-a em `~/.claude/skills/`. ### Passo 4. Escreva o SKILL.md usando o modelo Estrutura básica: ```markdown --- name: welcome-email-new-client description: | Prepara um e-mail de boas-vindas para um novo cliente, utilizando o modelo do canal de aquisição. Acionadores: «escreve um e-mail de boas-vindas para o novo cliente X», «integra o novo participante Y», «e-mail de boas-vindas para cliente vindo do canal Z». Não ativar se o pedido for sobre uma lista de distribuição geral ou uma campanha de e-mail — essas tarefas pertencem a outras skills. --- # E-mail de boas-vindas para um novo cliente ## Passos 1. Lê `knowledge/audience/segments.md` — que segmentos de clientes temos 2. Lê `knowledge/templates/welcome/` — modelos por canal 3. Identifica o canal do cliente a partir do contexto do pedido 4. Insere o nome do cliente, o nome do produto e a data de início 5. Verifica o comprimento — não deve ultrapassar 800 caracteres 6. Apresenta o texto final do e-mail num formato pronto a copiar ## Importante - Não uses «caro amigo» nem «olá» — escreve de forma natural - Um parágrafo, uma ideia - Termina com uma chamada à ação, não duas ``` ### Passo 5. Teste com 5–8 prompts Abra uma conversa em branco com o Claude Code neste projeto. Experimente 5 frases que utiliza mesmo e 3 semelhantes que não devem ativar a skill: Devem acionar: - «Escreve um e-mail de boas-vindas para o novo cliente Ivanov» - «Integra um novo participante que comprou o programa X» - «E-mail de boas-vindas para um cliente vindo do Instagram» Não devem acionar: - «Envia um e-mail promocional para a lista toda» - «Campanha de e-mail para as festas de Ano Novo» - «Escreve um e-mail de seguimento para um cliente que ainda não pagou» Em cada caso, verifique se a skill foi ativada. Se for ativada nos casos errados, torne a descrição mais específica. Se não for ativada nos casos certos, alargue as frases de acionamento. ### Passo 6. Itere sobre a descrição Depois de cada teste falhado, altere apenas a descrição — não mexa no corpo das instruções. Após 2–3 iterações, a skill começa a ser ativada de forma fiável. Guarde-a, faça commit e depois utilize-a todos os dias. Conselho final: não tente tornar a sua primeira skill perfeita. Faça-a funcionar. O aperfeiçoamento virá depois da quinta ou décima skill, quando começar a detetar padrões na forma como escreve e nas respostas do Claude. Escolha uma tarefa recorrente do seu calendário para esta semana, reserve 30 minutos e siga os seis passos acima. Depois, o Claude trabalhará de acordo com a sua metodologia em vez de adivinhar.
### Fontes - [Amplie o Claude com skills — documentação do Claude Code](https://code.claude.com/docs/en/skills) - [Visão geral dos Agent Skills — documentação da plataforma Claude](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) - [Preparar os agentes para o mundo real com Agent Skills — blogue Anthropic Engineering](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) - [anthropics/skills — repositório oficial com skill-creator](https://github.com/anthropics/skills) - [Skill Creator SKILL.md — origem da metodologia trigger-evals](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md) - [vercel-labs/agent-skills — diretrizes de design](https://github.com/vercel-labs/agent-skills) - [Norma aberta Agent Skills — especificação](https://agentskills.io)
A configuração funcional é **clone de IA + Segundo Cérebro + Engenharia de Contexto**. Três partes de uma só metodologia. Se precisa de aceder a modelos de IA através da Ailoot, consulte a [Ailoot](https://ailoot.ai/). ## Perguntas frequentes ### Mover uma skill para ~/.claude/skills/ torna-a inativa? Não. É o âmbito pessoal instalado, disponível nos projetos. Guarde pacotes sem uso num arquivo fora de todas as pastas descobertas e instale só os necessários. ### Como verifico se uma descrição aciona corretamente? Experimente cinco frases que devem invocar a skill e três pedidos próximos que não devem. Use chats novos, registe a skill carregada e ajuste a descrição perante falhas ou correspondências indevidas. ## Ailoot · A empresa e a sua carteira de projetos A Ailoot assenta numa experiência operacional consolidada, numa ampla base de clientes, num serviço estável e no acompanhamento contínuo dos KPI. A empresa e a sua carteira de projetos: milhões de clientes; vendas mensais na ordem dos milhares de milhões. A Ailoot aplica essa experiência operacional ao acesso por API a funcionalidades de IA nos produtos dos clientes, agentes, aplicações e automatizações.