Eu queria adicionar um recurso ao OpenClaw que não existia: um resumo do Hacker News que resume as principais histórias todas as manhãs e as publica no meu Slack. Nada parecido existia como uma habilidade. Então eu construí uma.
Levou quatro horas da primeira vez, incluindo duas horas de leitura errada da especificação da habilidade. A segunda habilidade que construí levou 45 minutos. Na quinta, eu conseguia fazer uma em 30 minutos. Aqui está o processo, livre de todos os erros que cometi ao longo do caminho.
O Que Uma Habilidade Realmente É
Uma habilidade é uma pasta com instruções e scripts opcionais. No mínimo, contém um arquivo SKILL.md — um documento em markdown que diz ao OpenClaw o que a habilidade faz, quando ativá-la e como utilizá-la.
É basicamente isso. Sem compilação. Sem registro de pacotes. Sem sistema de construção. Uma habilidade é um documento que o OpenClaw lê quando precisa realizar uma tarefa específica.
A habilidade mais simples possível:
Uma pasta chamada daily-hn-digest contendo um único arquivo, SKILL.md, com instruções como: “Quando o usuário pede um resumo do Hacker News, use a ferramenta web_search para encontrar as histórias atuais mais importantes do Hacker News, resuma cada uma em 2-3 frases e formate o resultado como uma lista com marcadores.”
Isso funciona. O agente lê as instruções, segui-las e produz um resumo do Hacker News. Nenhum código necessário.
Adicionando Complexidade Quando Necessário
A habilidade básica lida com casos simples. Para fluxos de trabalho mais complexos, você adiciona:
Arquivos de referência. Minha habilidade do Hacker News inclui uma pasta refs/ com saídas de exemplo — mostrando ao agente como é um bom resumo. Isso melhora dramaticamente a consistência. Em vez de “resumir histórias,” o agente vê “aqui está como um bom resumo se parece — siga este formato.”
Scripts. Algumas habilidades incluem scripts de shell ou scripts em Python para tarefas que a IA não pode fazer diretamente. Minha habilidade de resumo inclui um script que busca a API do Hacker News (mais rápida e confiável do que a extração da web). As instruções da habilidade dizem ao agente para executar o script e processar sua saída.
Configuração. As habilidades podem ler a partir de arquivos de config. Minha habilidade de resumo tem um config.yaml que especifica quantas histórias incluir (padrão: 10), quais categorias priorizar e o formato de saída (Slack, email ou texto simples).
A Estrutura Que Funciona
Depois de construir cerca de uma dúzia de habilidades, aqui está a estrutura de pasta na qual me estabeleci:
my-skill/
├── SKILL.md — Instruções principais (obrigatórias)
├── refs/ — Entradas e saídas de exemplo (opcionais)
├── scripts/ — Scripts de ajuda (opcionais)
└── config.yaml — Configuração (opcional)
SKILL.md é o arquivo mais importante. Ele deve incluir:
1. Uma descrição clara do que a habilidade faz
2. Quando a habilidade deve ser ativada (condições de disparo)
3. Instruções passo a passo para o fluxo de trabalho
4. Orientações para tratamento de erros
5. Exemplos de boa saída
A qualidade do seu SKILL.md determina diretamente a qualidade da habilidade. Um SKILL.md vago produz resultados inconsistentes. Um SKILL.md preciso produz resultados confiáveis.
Escrevendo Boas Instruções
A maior lição que aprendi: escreva o SKILL.md como se você estivesse treinando um novo funcionário, não como se estivesse escrevendo documentação.
Ruim: “Busque as histórias do Hacker News e resuma-as.”
Bom: “Busque as 10 principais histórias da API do 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 importa e a reação da comunidade (se notável). Formate como uma lista numerada com o título da história como um link.”
A versão boa elimina ambiguidade. O agente sabe exatamente o que fazer, qual formato usar e quais informações incluir. Não há espaço para interpretação criativa onde você não quer.
Inclua modos de falha. “Se a API do Hacker News não estiver acessível, use web_search como uma alternativa. Se houver menos de 5 histórias disponíveis, anote isso na saída e prossiga com o que estiver disponível. Não fabrique histórias.”
Inclua limites. “Não faça editorialização. Não adicione opiniões sobre as histórias. Não pule histórias porque parecem irrelevantes. Apresente todas as principais histórias de forma neutra.”
Testando Sua Habilidade
O processo de teste é simples: instale a habilidade, ative-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 até que ele detecte a nova habilidade)
3. Digite “Give me a Hacker News digest”
4. Verifique a saída em relação às expectativas
5. Ajuste o SKILL.md com base no que deu errado
Normalmente, passo por 3-4 ciclos de revisão antes de ficar satisfeito. Problemas comuns: o agente pulando etapas (adicione instruções mais explícitas), formatação inconsistente (adicione um exemplo de saída) ou incluindo 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 por meio do ClawHub — o marketplace de habilidades da comunidade. Faça o upload da sua pasta de habilidade, adicione uma descrição e outros usuários podem instalá-la com um único comando.
Antes de publicar, limpe sua habilidade: remova quaisquer configurações pessoais, adicione um README com instruções de configuração e teste em uma nova instalação do OpenClaw para garantir que não dependa do seu ambiente local.
As melhores habilidades da comunidade são focadas (elas fazem uma coisa bem), bem documentadas (SKILL.md claro) e sólidas (elas lidam com falhas de forma elegante). As piores são vagas (“use AI to do stuff”), 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ões. Antes de uma reunião, digo “prep for my 2pm with [client].” A habilidade puxa e-mails recentes, atualizações de projetos e problemas em aberto relacionados a esse cliente e compila um resumo de uma página.
Assistente de revisão de código. Quando faço push de código, a habilidade o revisa de acordo com os padrões de codificação da nossa equipe (documentados em um arquivo de referência) e publica comentários em nosso canal de equipe.
Gerador de retro semanal. Toda sexta-feira, a habilidade compila o que realizei naquela semana (a partir de commits do GitHub, mensagens do Slack e conclusões de tarefas) e elabora um resumo semanal.
Cada uma delas levou cerca de uma hora para ser construída. Cada uma economiza de 15 a 30 minutos por uso. O ROI é óbvio.
🕒 Published: