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:
O que o skill faz?
- Exemplo: “Gerencia tarefas de projeto com prioridades e deadlines”
Quando deve ser ativado?
- Exemplo: “Criar tarefa”, “listar tarefas”, “marcar como feito”
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 Estrutura
Opçã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.md
3.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 Scripts
scripts/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 Skill
5.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:
- Observe o que funciona mal - O skill entende os comandos?
- Melhore a descrição - Adicione mais gatilhos se necessário
- Refine instruções - Se algo é ambíguo, seja mais específico
- 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çadas
Progressive 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:
-
nameedescriptionno 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.)