Eu queria adicionar uma funcionalidade ao OpenClaw que não existia: um digest de Hacker News que resume as melhores histórias todas as manhãs e as publica no meu Slack. Nada parecido existia como uma skill. Então, eu construí uma.
Na primeira vez, levou quatro horas, sendo duas horas para ler mal a especificação da skill. A segunda skill que construí levou 45 minutos. Na quinta, eu podia realizar uma em 30 minutos. Aqui está o processo, livre de todos os erros que cometi pelo caminho.
O que realmente é uma skill
Uma skill é uma pasta com instruções e scripts opcionais. No mínimo, ela contém um arquivo SKILL.md — um documento em markdown que diz ao OpenClaw o que a skill faz, quando ativá-la e como usá-la.
Isso é realmente tudo. Sem compilação. Sem registro de pacotes. Sem sistema de construção. Uma skill é um documento que o OpenClaw lê quando precisa realizar uma tarefa específica.
A skill mais simples possível:
Uma pasta chamada daily-hn-digest contendo um único arquivo, SKILL.md, com instruções como: “Quando o usuário solicitar um digest de Hacker News, use a ferramenta web_search para encontrar as notícias mais importantes sobre Hacker News, resuma cada uma em 2-3 frases e formate o resultado como uma lista com marcadores.”
Funciona. O agente lê as instruções, as segue e produz um digest de Hacker News. Nenhum código necessário.
Adicionar complexidade quando necessário
A skill básica lida com casos simples. Para fluxos de trabalho mais complexos, você adiciona:
Arquivos de referência. Minha skill de Hacker News inclui uma pasta refs/ com exemplos de saídas — mostrando ao agente como é um bom digest. Isso melhora significativamente a consistência. Em vez de “resumir as histórias”, o agente vê “aqui está como um bom resumo se parece — siga este formato.”
Scripts. Algumas skills incluem scripts shell ou scripts Python para tarefas que a IA não pode fazer diretamente. Minha skill de digest inclui um script que recupera a API do Hacker News (mais rápida e confiável do que scraping web). As instruções da skill dizem ao agente para executar o script e processar sua saída.
Configuração. As skills podem ler a partir de arquivos de configuração. Minha skill de digest tem um config.yaml que especifica quantas histórias incluir (por padrão: 10), quais categorias priorizar e o formato de saída (Slack, email ou texto puro).
A estrutura que funciona
Depois de construir uma dúzia de skills, aqui está a estrutura de pasta em que parei:
my-skill/
├── SKILL.md — Instruções principais (obrigatório)
├── refs/ — Exemplos de entradas e saídas (opcional)
├── scripts/ — Scripts de assistência (opcional)
└── config.yaml — Configuração (opcional)
SKILL.md é o arquivo mais importante. Ele deve incluir:
1. Uma descrição clara do que a skill faz
2. Quando a skill deve ser ativada (condições de ativação)
3. Instruções passo a passo para o fluxo de trabalho
4. Guia de gerenciamento de erros
5. Exemplos de boa saída
A qualidade do seu SKILL.md determina diretamente a qualidade da skill. Um SKILL.md vago produz resultados inconsistentes. Um SKILL.md preciso produz resultados confiáveis.
Escrever boas instruções
A maior lição que aprendi: escreva o SKILL.md como se estivesse treinando um novo funcionário, não como se estivesse escrevendo documentação.
Ruim: “Recupere as histórias do Hacker News e resuma-as.”
Bom: “Recupere as 10 melhores histórias da API Hacker News usando o script em scripts/fetch-hn.sh. Para cada história, escreva um resumo de 2-3 frases que cubra: o que aconteceu, por que isso é importante e a reação da comunidade (se notável). Formate como uma lista numerada com o título da história como link.”
A versão boa elimina a ambiguidade. O agente sabe exatamente o que fazer, qual formato usar e quais informações incluir. Não há espaço para uma interpretação criativa onde você não deseja.
Incluir modos de falha. « Se a API do Hacker News estiver inacessível, use web_search como uma solução de backup. Se menos de 5 histórias estiverem disponíveis, anote isso na saída e prossiga com o que estiver disponível. Não crie histórias. »
Incluir limites. « Não faça comentários. Não adicione opiniões sobre as histórias. Não deixe de lado histórias que parecem menos importantes. Apresente todas as principais histórias de forma neutra. »
Testando sua habilidade
O processo de teste é simples: instale a habilidade, acione-a e verifique a saída.
Para minha habilidade do Hacker News :
1. Copie a pasta para o diretório de habilidades
2. Reinicie o OpenClaw (ou aguarde que ele detecte a nova habilidade)
3. Digite « Me dê um resumo do Hacker News »
4. Verifique a saída em relação às expectativas
5. Ajuste o SKILL.md conforme o que não funcionou
Geralmente, passo por 3-4 ciclos de revisões antes de ficar satisfeito. Problemas comuns: o agente pula etapas (adicione instruções mais explícitas), formatação inconsistente (adicione um exemplo de saída) ou inclua informações que você não queria (adicione limites explícitos).
Publicação e compartilhamento
Uma vez que sua habilidade funcione, você pode compartilhá-la via ClawHub — o mercado comunitário de habilidades. Carregue sua pasta de habilidades, adicione uma descrição, e outros usuários poderão instalá-la com um único comando.
Antes de publicar, limpe sua habilidade: remova qualquer configuração pessoal, adicione um README com instruções de configuração e teste-a em uma instalação nova do OpenClaw para garantir que não dependa do seu ambiente local.
As melhores habilidades comunitárias são focadas (elas fazem bem uma coisa), bem documentadas (SKILL.md claro) e sólidas (elas lidam com falhas com calma). As piores são vagas (« use a IA para fazer coisas »), mal documentadas ou frágeis.
Minhas habilidades personalizadas favoritas
Além do resumo do Hacker News, aqui estão as habilidades personalizadas que uso diariamente:
Preparação de reunião. Antes de uma reunião, digo « prepare minha reunião às 14h com [cliente]. » A habilidade recupera os emails recentes, as atualizações de projeto e os problemas em andamento relacionados a esse cliente e compila um briefing de uma página.
Assistente de revisão de código. Quando faço um push de código, a habilidade o revisa de acordo com os padrões de codificação de nossa equipe (documentados em um arquivo de referência) e publica comentários em nosso canal de equipe.
Gerador de retrospectiva semanal. Toda sexta-feira, a habilidade compila o que realizei nessa semana (a partir dos commits do GitHub, mensagens do Slack e tarefas concluídas) e redige um resumo semanal.
Cada uma dessas habilidades levou cerca de uma hora para ser construída. Cada uma economiza de 15 a 30 minutos por uso. O retorno sobre o investimento é evidente.
🕒 Published: