Skills na Prática

O que é uma skill, quando vale criar uma e como o agente a encontra.

Versão: 1.0.0

Tempo de leitura: cerca de 5 minutos

Uma skill é somente um “prompt” (um conjunto de instruções).

Não tem mágica nenhuma e criar uma skill é tão simples quanto escrever um prompt.

Como você reutiliza um prompt que você já escreveu? Copia e cola?

A skill resolve justamente esse processo de trabalho. É só isso.

Skill é um prompt que você refinou (versionou - mas a IA faz isso pra você) e deixou a um comando de distância. A única diferença entre uma skill e aquele prompt gigante que você cola no chat todo dia é que a skill fica em arquivo, com um nome específico, e que o agente de IA sabe que ela existe.

Mas então como criar uma skill?

Uma skill é uma pasta com um arquivo SKILL.md dentro. Esse arquivo tem um cabeçalho com nome e descrição e um corpo de texto que é, essencialmente, um prompt bem escrito sobre como executar uma tarefa (às vezes pode ter mais coisas como um scripts/, mas isso é coisa para o modelo de LLM não ter muito trabalho toda hora).

Um agente de IA razoável consegue montar o SKILL.md rapidamente.

Este apenas explica o que a pasta é e quando vale a pena ter uma. Não é um formulário para copiar.

Quando vale a pena criar uma skill?

Crie uma skill quando a mesma tarefa volta, com as mesmas fontes, etapas e checagens.

Repetir prompts extensos inteiros custa tempo e às vezes o resultado ainda pode oscilar. Inclusive, ao criar um prompt, você não sabe se ele vai funcionar bem ou não.

Se você está repetindo uma tarefa com regularidade e ela tem algumas etapas ou características que se repetem, talvez seja uma boa ideia criar uma skill.

O que vai no arquivo da skill?

O arquivo obrigatório é o SKILL.md. A forma básica é esta:

---
name: revisar-guia
description: Revisar um guia prático antes de publicar.
---

1. Identifique o público e o resultado.
2. Separe fato, decisão editorial e inferência.
3. Confira links, exemplos e o que pode ir ao repositório público.

O nome diz o que é. A descrição diz quando usar. O agente encontra a skill pela descrição.

A pasta pode ter mais coisas, mas elas são opcionais.

Onde a skill deve ser salva?

Na prática, uma skill pode ser salva em qualquer lugar.

Mas quais são os locais recomendados? São dois (ou três, se você considerar plugins - mas nem esquente com isso): 1. no repositório do projeto; 2. no diretório de skills do usuário;

No repositório do projeto:

meu-projeto/
└── .agents/
    └── skills/
        └── revisar-guia/
            └── SKILL.md

Com agentes de IA open source, as skills do projeto devem ficar dentro da pasta .agents/skills. É nessa pasta que o agente vai procurar.

No diretório de skills do usuário:

meu-usuario-do-computador/
└── .agents/
    └── skills/
        └── revisar-guia/
            └── SKILL.md

No Windows o meu-usuario-do-computador é C:\Users\<eu>\.

Se você quer que a skill seja encontrada em qualquer projeto, então ela precisa ser salva no diretório de skills do usuário.

No seu aplicativo de IA liste com /skills ou chame com /nome-da-skill.

Observação:

  • Ao configurar a skill você pode definir se ela pode ser ativada diretamente pelo agente de IA ou se ela precisa ser ativada por comando do usuário.
    • No caso de ativação direta, o agente vai avaliar se o pedido recebido combina com a descrição da skill e pode ativar a skill automaticamente.

Um procedimento de exemplo

A skill humanizer está em https://github.com/blader/humanizer. Ela reescreve texto que soa a chatbot sem mudar o que está dito, e sem inventar fato, nome, data ou citação.

O SKILL.md do repositório segue o formato da seção anterior. O cabeçalho nomeia a skill e descreve quando o agente deve acioná-la (revisão de prosa com marcas de texto de IA). O corpo é o procedimento:

  1. ler o texto inteiro e marcar os padrões, começando pelos mais fortes;
  2. reescrever guardando cada afirmação que o original sustenta;
  3. conferir se a nova versão acrescentou ou apagou fato;
  4. entregar o texto final.

Os padrões (o contraste “não X, mas Y”, a frase de encerramento que só repete o ponto, o travessão em toda frase) ficam listados no arquivo. O agente lê isso quando o pedido combina com a descrição.

Instalar uma skill a partir do GitHub

Para copiar essa skill para o seu computador (você vai precisar instalar o Node.js):

npx skills add blader/humanizer --global

O que esse comando faz? - blader/humanizer é o atalho para o repositório acima. - A flag --global grava no diretório do usuário; a skill vale em qualquer projeto. Sem a flag, ela fica só no repositório em que você rodou o comando.

Outras skills públicas podem ser instaladas com o mesmo comando trocando o blader/humanizer por dono/repositorio.

Depois de instalada no diretório do usuário, a pasta fica assim:

meu-usuario-do-computador/
└── .agents/
    └── skills/
        └── humanizer/
            └── SKILL.md

No Windows isso é C:\Users\<você>\.agents\skills\humanizer\SKILL.md. Abra o arquivo: é o prompt.

Alguns aplicativos copiam a mesma pasta para o diretório próprio (Claude Code: .claude\skills\humanizer). No aplicativo, liste com /skills ou chame com /humanizer.

Se preferir clonar o repositório e copiar a pasta para .agents/skills, o ciclo Git está em Git e GitHub na Prática.

Fontes e referências