Criar Seu Próprio Skill

Tutorial passo a passo para criar skills customizados no OpenClaw, desde a concepção até a publicação.

Criar Seu Próprio Skill

Este tutorial guia você na criação de um skill customizado do início ao fim. Vamos criar um skill de exemplo para gerenciar tarefas de um projeto.

Pré-requisitos
  • OpenClaw instalado e funcionando
  • Familiaridade básica com Markdown
  • (Opcional) Conhecimento de Python/Bash para scripts

Passo 1: Defina o Propósito

Antes de escrever código, responda:

  1. O que o skill faz?

    • Exemplo: “Gerencia tarefas de projeto com prioridades e deadlines”
  2. Quando deve ser ativado?

    • Exemplo: “Criar tarefa”, “listar tarefas”, “marcar como feito”
  3. Que recursos precisa?

    • Scripts para CRUD de tarefas?
    • Templates de relatório?
    • Schemas de dados?

Dica: Escreva 3-5 exemplos de uso antes de começar:

  • “Crie uma tarefa: Revisar PR do João, prioridade alta”
  • “Liste tarefas pendentes do projeto X”
  • “Marque tarefa #5 como concluída”

Passo 2: Crie a EstruturaOpção A: Usando o script init_skill.py
# Se disponível no seu setup
python scripts/init_skill.py project-tasks --path ~/clawd/skills --resources scripts,references
Opção B: Manualmente
# Criar diretório
mkdir -p ~/clawd/skills/project-tasks
cd ~/clawd/skills/project-tasks

# Criar estrutura
touch SKILL.md
mkdir scripts references

Estrutura resultante:

project-tasks/
├── SKILL.md
├── scripts/
└── references/

Passo 3: Escreva o SKILL.md3.1 Frontmatter
---
name: project-tasks
description: |
  Gerencia tarefas de projeto com prioridades, deadlines e status.
  Use quando o usuário pedir para criar, listar, atualizar ou concluir tarefas.
  Gatilhos: "criar tarefa", "listar tarefas", "marcar como feito", 
  "tarefas do projeto", "adicionar todo".
---

Importante: A descrição é CRÍTICA. O OpenClaw decide se ativa o skill baseado nela.

3.2 Corpo
# Project Tasks

Gerencia tarefas de projeto em formato JSON local.

## Arquivo de tarefas

Armazenado em `~/.tasks/tasks.json`:

\`\`\`json
{
  "tasks": [
    {
      "id": 1,
      "title": "Revisar PR",
      "priority": "high",
      "status": "pending",
      "deadline": "2026-02-05",
      "project": "openclaw"
    }
  ]
}
\`\`\`

## Criar tarefa

\`\`\`bash
python scripts/task_manager.py add "Título da tarefa" --priority high --deadline 2026-02-10 --project meu-projeto
\`\`\`

## Listar tarefas

\`\`\`bash
# Todas
python scripts/task_manager.py list

# Por projeto
python scripts/task_manager.py list --project openclaw

# Pendentes
python scripts/task_manager.py list --status pending
\`\`\`

## Concluir tarefa

\`\`\`bash
python scripts/task_manager.py complete 5
\`\`\`

## Prioridades

- `high`: Urgente, fazer hoje
- `medium`: Importante, fazer esta semana
- `low`: Pode esperar

## Status

- `pending`: A fazer
- `in_progress`: Em andamento
- `done`: Concluído

Passo 4: Crie os Scriptsscripts/task_manager.py
#!/usr/bin/env python3
"""
Gerenciador de tarefas para o skill project-tasks.
"""
import json
import argparse
from pathlib import Path
from datetime import datetime

TASKS_FILE = Path.home() / ".tasks" / "tasks.json"

def load_tasks():
    if not TASKS_FILE.exists():
        TASKS_FILE.parent.mkdir(parents=True, exist_ok=True)
        return {"tasks": [], "next_id": 1}
    return json.loads(TASKS_FILE.read_text())

def save_tasks(data):
    TASKS_FILE.write_text(json.dumps(data, indent=2))

def add_task(title, priority="medium", deadline=None, project=None):
    data = load_tasks()
    task = {
        "id": data["next_id"],
        "title": title,
        "priority": priority,
        "status": "pending",
        "deadline": deadline,
        "project": project,
        "created": datetime.now().isoformat()
    }
    data["tasks"].append(task)
    data["next_id"] += 1
    save_tasks(data)
    print(f"✅ Tarefa #{task['id']} criada: {title}")

def list_tasks(project=None, status=None):
    data = load_tasks()
    tasks = data["tasks"]
    
    if project:
        tasks = [t for t in tasks if t.get("project") == project]
    if status:
        tasks = [t for t in tasks if t["status"] == status]
    
    if not tasks:
        print("Nenhuma tarefa encontrada.")
        return
    
    for t in tasks:
        emoji = "✅" if t["status"] == "done" else "⏳" if t["status"] == "in_progress" else "📋"
        priority = {"high": "🔴", "medium": "🟡", "low": "🟢"}.get(t["priority"], "")
        print(f"{emoji} #{t['id']} {priority} {t['title']}")
        if t.get("deadline"):
            print(f"   📅 {t['deadline']}")

def complete_task(task_id):
    data = load_tasks()
    for t in data["tasks"]:
        if t["id"] == task_id:
            t["status"] = "done"
            save_tasks(data)
            print(f"✅ Tarefa #{task_id} concluída!")
            return
    print(f"❌ Tarefa #{task_id} não encontrada.")

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    subparsers = parser.add_subparsers(dest="command")
    
    # Add
    add_parser = subparsers.add_parser("add")
    add_parser.add_argument("title")
    add_parser.add_argument("--priority", default="medium")
    add_parser.add_argument("--deadline")
    add_parser.add_argument("--project")
    
    # List
    list_parser = subparsers.add_parser("list")
    list_parser.add_argument("--project")
    list_parser.add_argument("--status")
    
    # Complete
    complete_parser = subparsers.add_parser("complete")
    complete_parser.add_argument("id", type=int)
    
    args = parser.parse_args()
    
    if args.command == "add":
        add_task(args.title, args.priority, args.deadline, args.project)
    elif args.command == "list":
        list_tasks(args.project, args.status)
    elif args.command == "complete":
        complete_task(args.id)

Torne executável:

chmod +x scripts/task_manager.py

Passo 5: Teste o Skill5.1 Teste os scripts diretamente
cd ~/clawd/skills/project-tasks

# Adicionar tarefa
python scripts/task_manager.py add "Testar skill" --priority high --project teste

# Listar
python scripts/task_manager.py list

# Concluir
python scripts/task_manager.py complete 1
5.2 Teste via OpenClaw

Configure o skill no seu config.yaml:

skills:
  paths:
    - ~/clawd/skills

Reinicie o OpenClaw e teste:

  • “Crie uma tarefa: Revisar documentação, prioridade alta”
  • “Liste minhas tarefas”
  • “Marque tarefa 1 como concluída”

Passo 6: Itere e Melhore

Após usar o skill em cenários reais:

  1. Observe o que funciona mal - O skill entende os comandos?
  2. Melhore a descrição - Adicione mais gatilhos se necessário
  3. Refine instruções - Se algo é ambíguo, seja mais específico
  4. Adicione exemplos - Exemplos concretos ajudam o modelo

Passo 7: Empacote (Opcional)

Para distribuir seu skill:

# Se disponível
python scripts/package_skill.py ~/clawd/skills/project-tasks

# Resultado: project-tasks.skill

O arquivo .skill é um zip que pode ser compartilhado ou publicado no ClawHub.


Dicas AvançadasProgressive Disclosure

Para skills complexos, use referências externas:

# No SKILL.md
Para workflow avançado de sprints, veja [references/sprints.md](references/sprints.md).
Múltiplos Domínios

Organize por domínio para evitar carregar contexto irrelevante:

references/
├── sales.md      ← Workflows de vendas
├── support.md    ← Workflows de suporte
└── dev.md        ← Workflows de desenvolvimento
Dependências Externas

Declare no frontmatter:

metadata:
  openclaw:
    requires:
      bins: ["python3", "jq"]
    install:
      - id: pip
        kind: pip
        package: requests

Checklist Final

Antes de considerar o skill pronto:

  • name e description no frontmatter
  • Descrição inclui gatilhos claros
  • SKILL.md tem menos de 500 linhas
  • Scripts testados manualmente
  • Exemplos de uso documentados
  • Sem arquivos desnecessários (README, CHANGELOG, etc.)

Próximos Passos