OpenCode skills: o que são skills em agentes de código e como funcionam na prática

Você abre uma sessão nova do agente e lá vai colar de novo o mesmo bloco de instrução

o padrão de commit, a estrutura de pastas, aquela regra chata que só esse projeto tem

e amanhã, tudo outra vez 🙂

Se você chegou aqui procurando por OpenCode skills, provavelmente quer entender o que essa palavra significa ANTES de sair instalando qualquer coisa, e isso é o mais saudável a fazer

Então bora do começo: o que é uma skill, como o arquivo é montado por dentro, como o OpenCode carrega ela e o que muda de verdade em relação a jogar prompt solto no chat…

Como uma skill é feita por dentro

Uma skill é bem menos misteriosa do que o nome sugere

É uma pasta com um arquivo SKILL.md dentro, só isso

O arquivo tem duas partes: um frontmatter YAML no topo (com campos como name e description) e, embaixo, o corpo em Markdown com as instruções

---
name: revisao-antes-do-commit
description: Usar quando o pedido envolver revisar mudanças de codigo antes de commitar neste projeto
---

# Revisao antes do commit

Siga esta ordem:

1. Liste os arquivos alterados
2. Confira se cada mudanca tem teste
3. Escreva a mensagem de commit no padrao do repositorio

Se você já escreveu um post em Markdown com frontmatter, ou mexeu em qualquer gerador de site estático, o formato vai parecer familiar demais

E qual campo importa mais? A description

Ela é o que decide se a skill é anunciada ao modelo: skill sem descrição simplesmente não aparece pro agente

O name do frontmatter serve como rótulo de exibição, o nome bonitinho que você lê na tela

Por que isso pesa tanto? Porque no OpenCode as skills são carregadas sob demanda por uma ferramenta nativa chamada skill: o modelo enxerga nome e descrição de cada skill instalada e só carrega o conteúdo completo quando decide que aquela ali se aplica ao que você pediu

Ou seja: a descrição é o índice do livro

Se o índice está mal escrito, ninguém abre o capítulo, por melhor que ele seja

Escrever a description é metade do trabalho, se liga nisso

Onde o OpenCode procura suas skills e como controlar o acesso

Saber o formato não adianta se o arquivo estiver no lugar errado, então vamos aos caminhos que a documentação de skills do OpenCode lista

1. Caminhos do projeto, que ficam versionados junto do código:

.opencode/skills/*/SKILL.md
.claude/skills/*/SKILL.md
.agents/skills/*/SKILL.md

O erro comum deste passo é montar a pasta certinha, com o arquivo certinho, e esquecer a description no frontmatter: a skill existe no disco e continua invisível pro agente

2. Caminhos globais do usuário, pras skills que você quer em qualquer projeto:

~/.config/opencode/skills/*/SKILL.md
~/.claude/skills/*/SKILL.md
~/.agents/skills/*/SKILL.md

O erro comum aqui é jogar no global aquilo que é regra de UM projeto só, tipo convenção de pasta de um repositório específico, e depois estranhar o agente aplicando isso onde não devia

3. Skills vêm habilitadas por padrão no OpenCode, e dá pra desligar por agente com tools.skill = false, seja no frontmatter do agente customizado, seja no opencode.json (por exemplo agent.plan.tools.skill = false)

Com a ferramenta desligada, a seção available_skills é omitida, ou seja, aquele agente nem fica sabendo que existe skill

O erro comum é desligar pra um agente e continuar esperando que ele use suas skills

4. Acesso granular por permissão: o opencode.json aceita uma permissão skill com as ações allow, ask e deny, e os padrões aceitam curinga (internal-* casa tanto internal-docs quanto internal-tools)

As mesmas regras podem ficar sob agents.<id>.permissions, se você quiser um recorte por agente, como explica a documentação de permissões

Tome cuidado com um detalhe aqui: deny não é um "esconder da lista" apenas

Ele remove a skill da descoberta E recusa o carregamento

O ask é o meio termo: anuncia a skill normalmente, mas pede aprovação na hora de usar

De onde veio o formato SKILL.md (e por que ele não é só do OpenCode)

Esse formato não nasceu dentro do OpenCode

O Agent Skills foi criado pela Anthropic e anunciado publicamente em 16 de outubro de 2025

Depois, em 18 de dezembro de 2025, a Anthropic publicou o Agent Skills como padrão aberto, com especificação e documentação em agentskills.io e a spec mantida no GitHub, em github.com/agentskills/agentskills

E é aí que a coisa fica interessante pra quem usa mais de um agente

O Claude Code lê o mesmo formato de pasta com SKILL.md, procurando skills pessoais em ~/.claude/skills/ e skills do projeto em .claude/skills/

Repara na lista de caminhos lá de cima: o OpenCode também olha .claude/skills e ~/.claude/skills

Tradução prática: a mesma skill pode servir os dois agentes sem você duplicar arquivo nenhum

muito massa isso, né? 😀

Skill x prompt solto: a diferença no dia a dia

Dá pra viver colando prompt, claro, é o que a maioria faz

Mas a diferença estrutural entre as duas abordagens é essa aqui:

O que muda no seu fluxo quando a instrução vira skill

A leitura prática da tabela é simples: o conhecimento repetido sai do seu histórico de mensagens e vira arquivo do projeto

Quem entra no repositório amanhã herda a mesma instrução, sem você explicar de novo

E muda também de quem é a decisão

Antes o esforço era "lembrar de colar"

Agora o esforço é "escrever uma descrição que o modelo entenda", porque é ela que faz a skill ser anunciada ou ignorada

É um trabalho diferente, e sinceramente é um trabalho mais barato: você escreve uma vez e revisa quando a regra muda

Só não vamos vender fumaça aqui: skill é instrução organizada e carregada na hora certa, não é um plugin que sai executando sozinho

Quem quer coisa rodando sem ninguém no volante está falando de outro assunto, mais perto de automação de fluxos com n8n, e não de um arquivo Markdown com boas instruções

Que tipo de tarefa repetitiva uma skill resolve

O critério é bem direto: repete, tem regra estável e você já se cansou de explicar

Se os três batem, vira skill

• Padrão de commit e de revisão do repositório: formato da mensagem, o que conferir antes de commitar, o que nunca entra no commit
• Convenções de código e estrutura de pastas: onde mora cada camada, como nomear arquivo, qual padrão o time já decidiu que usa
• Roteiro fixo de investigação de bug: qual log olhar primeiro, como reproduzir, o que registrar antes de sair mexendo
• Checklist antes de publicar: build, testes, variáveis de ambiente, aquilo que você SEMPRE esquece e descobre em produção
• Regra de domínio do produto: o vocabulário do negócio, o que pode e o que não pode, algo bem parecido com a lógica de agentes de IA para nichos específicos, onde o contexto da área vale mais que o modelo

O que NÃO vira skill é decisão de uma vez só

Pedido pontual continua sendo prompt mesmo, e tudo bem

As skills que eu encadeei num projeto do zero

Aqui eu preciso ser honesto sobre o cenário do teste: esse fluxo eu rodei no Claude Code, que lê o mesmo formato de SKILL.md, e não dentro do OpenCode

A lógica de encadeamento vale igual, o produto é que foi outro

O encadeamento foi este, nesta ordem:

• Brainstorm: entrevista pra levantar requisito antes de escrever uma linha de código
• Escrita de plano: transforma o documento de design em tarefas com ordem, dependência e critério de aceitação
• Execução do plano: pega o plano aprovado e escreve o código
• Design de front-end: tira o visual genérico de cima do projeto
• Skill própria de checagem de segurança: criada por prompt, em vez de instalar pacote de terceiro

Agora o que aconteceu em cada uma delas

Comecei de uma pasta vazia, com uma skill de brainstorm ativada junto do prompt do projeto (um app de controle de despesas pessoais, com cadastro por categoria, dashboard mensal e gráfico)

E a skill não saiu escrevendo código: ela conduziu uma entrevista

Perguntou se era uso pessoal ou vários usuários, qual autenticação, se as categorias eram fixas ou customizáveis, e ainda sugeriu uma lista de categorias pra eu aprovar

No meio do papo apareceu uma oferta de gerar mockups e diagramas no navegador, com aviso de que ia consumir mais token, e eu recusei pra ir direto pra implementação

Com o documento de design aprovado, usei uma segunda skill, de escrita de plano, pedindo pra transformar aquele design em plano de implementação com tarefas em ordem, dependências e critérios de aceitação

Saíram 14 tarefas

Aí uma dica que economiza dor de cabeça: mesmo com o plano já no contexto, referencie o arquivo do plano com @ na hora de mandar executar, pra garantir que o agente está usando o documento certo

A terceira skill foi a de executar o plano e escrever o código

Essa fase de criar arquivo e fazer setup pede MUITOS aceites seguidos, então vale considerar o modo de pular confirmações se você não quiser passar o dia clicando

Cronometrando por curiosidade: até a terceira tarefa do plano rodando, deu quase 10 minutos

No fim da execução o app subiu com erro no fluxo de criar conta e login

Copiei a mensagem, colei no agente e fui depurando até acessar o projeto

Erro no primeiro prompt eu trato como parte do processo, não como falha do fluxo, beleza? Depois de corrigido, cadastrei uma despesa de alimentação e o registro e a autenticação funcionaram normalmente

O problema que sobrou foi outro: arquitetura boa, clareza boa, e uma interface completamente genérica

Projeto sem alma

Aí entrou a quarta skill, de design de front-end, e aqui eu não pedi "faz um redesign"

Eu descrevi a intenção: visual clean e moderno que passe confiança financeira, modo escuro, sensação de controle sem sobrecarga

O agente devolveu o redesign explicando o que mudou (modo escuro, tipografia, cor de acento, cards, barra de navegação, animações) e o resultado veio com tipografia melhor, estilo mais sóbrio e elementos mais consistentes

Garantia? Nenhuma, isso depende MUITO do prompt

Boa parte das reclamações de "a IA fez uma porcaria" que eu vejo por aí é prompt mal escrito, não modelo ruim

E a quinta frente foi criar skill própria em vez de instalar pacote de terceiro, porque cada projeto usa uma tecnologia diferente

Criei por prompt uma skill de checagem de segurança que dá nota de 0 a 100, exigindo verificação mecânica (rodar comandos de verdade e contar problemas encontrados) e não achismo subjetivo

Descrevi o que eu queria auditar (segredos, entradas, autenticação, dependências, cabeçalhos) e pedi saída com nota total, detalhamento por categoria e lista de problemas

Depois de criada, abri o arquivo da skill e li antes de rodar

Skill gerada por IA é rascunho pra validar, não evangelho

Minha conclusão prática: o ganho não está numa skill isolada, está no encadeamento

brainstorm pra levantar requisito, plano com tarefas e critérios, execução, e depois o front-end pra tirar o visual genérico

Gasta mais tempo e mais token, sim, mas o prompt sai certeiro e cobre decisão que eu não teria pensado no começo

Veja as skills funcionando no vídeo

No vídeo abaixo eu mostro esse encadeamento na tela, da pasta vazia até o app rodando: a entrevista da skill de brainstorm, o plano com as tarefas, a execução com os aceites, o erro de login sendo depurado e o redesign do front-end

Por onde começar com skills

Skill é instrução repetida que virou arquivo, e o agente decide sozinho quando abrir esse arquivo com base na descrição que você escreveu

É menos mágica e mais organização, e é justamente por isso que funciona

Próximo passo, hoje mesmo: crie uma pasta com um SKILL.md dentro de .opencode/skills (ou dentro de .claude/skills, se quiser aproveitar o mesmo arquivo nos dois agentes), capriche na description e teste numa tarefa que você já repetiu essa semana

Se a skill for carregada sozinha na hora certa, tá valendo 😀

até o próximo post!