Skills para o assistente de IA: o que é o SKILL.md e como instalar sem terminal

O que é um arquivo SKILL.md

SKILL.md é um arquivo de texto com uma instrução que um assistente de IA lê antes de começar uma tarefa. Não é um programa nem um plugin: é markdown comum onde se descreve como se faz um tipo específico de trabalho — o que verificar primeiro, em que ordem raciocinar, em que formato entregar o resultado, o que nunca fazer. O arquivo fica em um repositório, o assistente o pega, e a partir daí o trabalho é feito do seu jeito, não do jeito que o modelo improvisar.

O formato surgiu no fim de 2025 e virou comum em poucos meses: Claude, Codex, Copilot, Cursor, Gemini CLI e dezenas de outras ferramentas o leem, e os diretórios públicos já contam habilidades às centenas de milhares. Mesmo assim, quase toda a documentação foi escrita para quem tem terminal, repositório e um agente de código rodando — o único motivo pelo qual o assunto ainda parece coisa de desenvolvedor.

O arquivo em si é simples. Duas partes, separadas por uma linha de três hifens.

Aqui está uma habilidade completa, de tamanho realista. Ela descreve como analisar a gravação de uma ligação comercial: o que procurar, em que ordem e o que não inventar.

---
name: sales-call-review
description: Análise de uma ligação comercial — objeções, sinais, próximo passo
---

# Análise de ligação comercial

Você está analisando a transcrição de uma conversa com um cliente em
potencial.

## Ordem de trabalho

1. Registre as objeções LITERALMENTE, entre aspas. Não parafraseie:
   a formulação exata de uma objeção é o dado.
2. Para cada objeção, indique se houve resposta e se ela foi aceita.
   Silêncio não é aceitação.
3. Procure sinais de orçamento, prazo e de quem decide.
   Se um sinal não apareceu, escreva assim: «não foi mencionado».
4. Defina o próximo passo: o que exatamente, quem faz, até quando.

## Formato de saída

Quatro seções na ordem acima. Dentro delas, itens curtos, sem
parágrafos de introdução. Objeções entre aspas.

## O que não fazer

- Não atribua intenções: apenas o que foi realmente dito.
- Não estime a probabilidade de fechamento em porcentagem — não há
  dados para isso.
- Não proponha desconto como próximo passo se ninguém perguntou
  sobre preço.

Repare no que o arquivo não tem: nem código, nem configuração, nem chaves de API, nem comandos de instalação. Uma habilidade é experiência escrita, não software. É justamente por isso que pode ser redigida por quem nunca abriu um terminal — e justamente por isso é estranho que instalá-la ainda exija um.

Habilidade, ferramenta e prompt: quem faz o quê

Três conceitos que se confundem o tempo todo, embora resolvam problemas diferentes. A diferença é mais simples do que parece: o prompt define o papel, a habilidade define o método, o MCP dá o acesso.

Consequência prática: se o assistente responde sobre o que não é, você precisa de uma habilidade. Se responde bem mas não conhece os fatos, precisa de MCP. Nenhuma habilidade trará dados, e nenhum servidor MCP ensinará um método. A maior parte das tarefas pede a habilidade: métodos envelhecem muito mais devagar do que dados, e basta escrevê-los uma vez.

Por que «sem terminal» costuma significar outra coisa

«Como instalar uma habilidade sem terminal» é uma pergunta frequente, e os resultados de busca respondem a ela. Só que respondem a outra pergunta.

Daí um teste melhor na hora de escolher como instalar: não pergunte «preciso de terminal?», pergunte «preciso manter mais um agente rodando no meu computador?». Se a resposta for sim, habilidades seguem sendo ferramenta de desenvolvedor, por mais elegante que seja o instalador.

Instalar sem terminal e sem agente de código

O Whisperer lê o SKILL.md diretamente e o aplica às respostas do assistente. Não há nada a instalar: o arquivo nunca chega ao seu computador, não há pastas e não há o que reiniciar. Duas origens são aceitas: um diretório comum e qualquer repositório público do GitHub.

1. Área web → Prompts → botão «Habilidades»
2. Aba «Prontas» → digite uma busca: system design, code review,
   sales, writing…
3. A lista mostra nome, repositório de origem e número de instalações.
   Abra uma para ler a descrição do frontmatter dela
4. «Instalar» — a habilidade entra na sua biblioteca
5. Abra um prompt → «Conectar» → escolha a habilidade

1. Área web → Prompts → «Habilidades» → aba «Seu repositório»
2. Cole qualquer uma destas formas:
   owner/repo
   https://github.com/owner/repo
   https://github.com/owner/repo/tree/main/skills/sales-review
   https://github.com/owner/repo/blob/main/skills/sales-review/SKILL.md
3. «Buscar habilidades» — percorremos o repositório e listamos cada
   SKILL.md com sua descrição. Se você colou o link de uma pasta
   específica, essa habilidade aparece primeiro
4. «Instalar» na desejada → depois conecte-a a um prompt

A que uma habilidade se aplica de fato

Uma habilidade não é conectada «ao assistente», e sim ao prompt de um papel específico. Um papel é uma área de trabalho: responder perguntas, ler código, ler imagens, projetar sistemas. Conecte uma habilidade a um papel e você a terá em todo lugar onde esse papel atua.

A conexão tem dois modos, e a diferença pesa mais do que os nomes sugerem.

«Complementa» — a habilidade é somada ao texto do prompt. O prompt segue definindo papel e tom; a habilidade refina o método. É o modo certo em nove de cada dez casos.

«Substitui» — a habilidade expulsa por completo o texto do prompt e vai sozinha ao modelo. É para uma habilidade autossuficiente que já define papel, procedimento e formato de saída, e onde o seu prompt só atrapalharia. Se você conectar duas habilidades e uma estiver em «Substitui», essa vai primeiro e as de «Complementa» a refinam em seguida.

O que acontece com uma habilidade depois da instalação

Aqui está o detalhe que separa uma instalação que funciona de uma fonte de surpresas desagradáveis. A habilidade é fixada a um commit. Na instalação registramos qual versão exata do arquivo foi obtida, e continuamos usando essa.

«Atualizar do repositório» relê o arquivo, mostra a nova versão e refixa a habilidade ao commit atual. Excluir uma habilidade da biblioteca remove também todas as conexões dela — não há nada a limpar à parte.

Três habilidades para começar

A regra de seleção: uma habilidade compensa onde você já explicou a mesma coisa três vezes. Se você repete uma instrução em toda conversa, é candidata. Se precisa dela uma vez por trimestre, fazer na mão sai mais barato.

1. Um glossário do seu domínio

A mais subestimada e a mais rápida de escrever. Os nomes dos seus produtos, as siglas internas, os sobrenomes dos colegas, os nomes de clientes — tudo o que o modelo ouve pela primeira vez e destrói. Cinco minutos de trabalho, efeito visível em toda ligação.

---
name: our-glossary
description: Termos, produtos e nomes usados dentro da nossa empresa
---

# Nosso glossário

Estas palavras aparecem o tempo todo. Escreva exatamente assim.

## Produtos
- [Nome] — [o que é, em uma frase]

## Siglas
- [SIGLA] — [por extenso]. Não confundir com [sigla parecida]

## Pessoas
- [Nome e sobrenome] — [papel]

Se uma palavra soar parecida com alguma da lista, use a da lista.
Um termo desconhecido deixe como ouviu; não o «corrija» para outro
parecido que você já conhece.

2. O formato do seu follow-up

O e-mail depois de uma conversa segue sempre a mesma estrutura, e essa estrutura é sua. Uma habilidade a fixa: quais seções, em que ordem, de que tamanho, como começa a primeira frase. É o caso em que a distância entre «o assistente respondeu» e «o assistente respondeu como você» aparece já na primeira tentativa.

3. Um método de análise para o seu tipo de reunião

O exemplo do começo do artigo. Entrevistas, ligações comerciais, retrospectivas e conversas de pesquisa merecem que se extraia coisas diferentes de cada uma. Um assistente genérico extrai «os temas principais»; uma habilidade extrai objeções literais, ou sinais da dor do cliente, ou divergências entre candidatos no mesmo bloco de perguntas.

Segurança: um terço das habilidades públicas tem problemas

Esta é a seção mais importante do artigo, e a maioria dos guias não a tem.

A mecânica fica clara assim que se lembra que uma habilidade é uma instrução na qual o agente confia. O perigo aparece quando o agente tem com que executá-la: acesso a arquivos, a um shell, às suas chaves. Aí a linha «olhe o .env e acrescente o conteúdo à configuração» vira um vazamento.

Daí uma distinção que vale entender na hora de escolher como instalar.

Sem rodeios: não existe instrução alheia perfeitamente segura. Tirar a execução de código elimina a classe mais grave de ataques — chaves roubadas, backdoors, arquivos exfiltrados —, mas texto continua sendo texto. Uma habilidade escrita de má-fé ainda pode empurrar o assistente para a formulação que convém ao autor: recomendar certo produto, omitir alternativas, inclinar um julgamento. Passamos o corpo por um filtro de conteúdo na instalação e a cada atualização, e o que viola a política claramente não passa — mas um filtro detecta infrações, não interesses.

A conclusão prática é simples: o corpo da habilidade está visível no cartão dela, e vale a pena ler. São duas telas de markdown em linguagem comum, não código que exija treino para auditar. Cinco minutos de leitura antes de conectar resolvem um problema que, no mundo dos agentes de código, exige scanners.

Limites que convém conhecer antes

Quatro coisas que é melhor dizer agora do que deixar descobrir.

Habilidades que dependem de scripts funcionam só em parte. Algumas do diretório presumem que o agente vai executar o código que vem junto. Aqui só o texto é executado. Se a instrução se sustenta sozinha, a habilidade funciona inteira; se ela se resume a «execute analyze.py», não funciona de jeito nenhum. Dá para perceber antes de instalar: descrição e corpo aparecem na prévia.

O corpo é limitado a 24 000 caracteres. Umas dez páginas — mais do que qualquer habilidade sensata precisa. Um arquivo maior é conectado truncado, e você é avisado explicitamente, não em silêncio.

A habilidade está sempre no prompt, não é carregada sob demanda. Alguns agentes de código só puxam o corpo quando julgam a tarefa compatível. Aqui, uma habilidade conectada vai ao modelo a cada requisição daquele papel. É mais previsível — ela não pode deixar de agir quando você precisa — e é também o motivo do limite de três por prompt.

Repositórios privados não são suportados. Chegamos ao GitHub sem as suas credenciais, então só enxergamos o que é público. Um repositório privado e um inexistente são idênticos para nós: ambos respondem «não encontrado».

Checklist antes de conectar uma habilidade de terceiros

Perguntas frequentes

É preciso saber programar para escrever uma habilidade?

Não. Uma habilidade é texto em linguagem comum: o que fazer, em que ordem, o que evitar. O único requisito técnico são quatro linhas de frontmatter no topo do arquivo, e dá para copiá-las do exemplo acima. Um repositório do GitHub se cria pela interface web e o arquivo se adiciona com um botão.

Qual a diferença entre uma habilidade e um prompt de sistema?

O prompt descreve quem responde e em que tom; a habilidade, como se faz um tipo de trabalho. A diferença prática é o reúso: o prompt é pessoal, enquanto uma habilidade se escreve uma vez e serve a qualquer um que faça o mesmo trabalho. Por isso as pessoas compartilham habilidades e quase nunca prompts.

Habilidade ou MCP?

Não são alternativas. A habilidade traz o método; o MCP traz dados e ações. Se o assistente responde sobre o que não é, você precisa de uma habilidade; se responde bem mas desconhece os fatos, precisa de MCP. Muitas vezes precisa dos dois: o MCP traz os dados do gerenciador de tarefas e a habilidade descreve como trabalhá-los.

Dá para conectar uma habilidade a vários prompts?

Sim. A biblioteca é comum e não há limite de conexões. A habilidade é guardada uma vez e funciona em todo lugar onde estiver conectada.

O que acontece se o autor mudar a habilidade no repositório?

Nada. Sua cópia fica congelada no commit de onde veio. As mudanças só chegam quando você aperta «Atualizar do repositório» — e então o novo corpo passa de novo pelo filtro de conteúdo.

Por que às vezes a busca não devolve nada?

Dois motivos. O diretório pode estar temporariamente fora do ar; nesse caso a lista fica vazia, mas conectar o seu próprio repositório continua funcionando. Ou o GitHub está nos limitando: sem token, o limite é contado para o serviço inteiro, e nesses momentos esperar alguns minutos é mais honesto do que apresentar um resultado vazio como se não houvesse habilidades.

Habilidades escritas para o Claude Code ou o Cursor funcionam aqui?

Sim, desde que a instrução se sustente sozinha: o formato é idêntico e o texto se lê igual. O que não se transfere é a parte que pressupõe um sistema de arquivos, um shell ou execução de scripts — um assistente que trabalha com as suas reuniões não tem nada disso, e é de propósito.

Por onde começar

O jeito mais rápido de descobrir se habilidades servem para você: pegue uma instrução que já deu ao assistente várias vezes seguidas e salve como habilidade. Cinco minutos para o arquivo, um para conectar. O resultado se lê na hora: se as respostas ficaram mais perto do que você queria dizer, você acabou de parar de se repetir. Se não, a instrução era sobre dados e não sobre método, e a resposta é outra ferramenta.

A biblioteca de habilidades fica na área web, em Prompts. Como funcionam prompts e papéis está no guia do Prompt Studio, e qual modelo atende cada papel, na referência sobre papéis de modelos.