feat(gestao): adicionar 9 skills /clip-* + migrar 5 para diag tools MCP
Skills clip-* nunca tinham sido committed. Adicionadas todas (9): clip, clip-agent, clip-health, clip-instructions, clip-issue, clip-org, clip-routine, clip-skill, clip-vision. Migração para mcp__paperclip__diag_* (17 substituições em 5 skills): - clip: 5 substituições (agents_by_status, false_blockers, token burn, stuck routines, company_skills_summary) - clip-agent: 2 (agent_full_context consolida 4 passos, false_blockers) - clip-health: 8 (budget_orphans, missing_permissions, missing_heartbeat, routine_triggers_broken, false_blockers, heartbeat_token_usage, prompt_too_long_errors, stuck_routines, zombie_parents) - clip-org: 1 (agent_hierarchy) - clip-routine: 1 (routine_triggers_broken) Sem substituições (CRUD-específico sem diag_* equivalente): clip-instructions, clip-issue, clip-skill — mantêm psql. Refs: Desk #2041, mcp-paperclip feature/diagnostics-db Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,184 @@
|
||||
---
|
||||
name: clip-instructions
|
||||
description: Editar e gerir AGENTS.md de agentes Paperclip — ver, editar, rever histórico de versões. O AGENTS.md é o "cérebro" do agente. Usar quando "clip instructions", "editar agente", "atualizar AGENTS.md", "mudar comportamento agente", "instruções agente".
|
||||
context: fork
|
||||
version: "1.0.0"
|
||||
created: 2026-04-07
|
||||
---
|
||||
|
||||
# /clip-instructions — Gerir AGENTS.md dos Agentes
|
||||
|
||||
O `AGENTS.md` é o ficheiro de instruções que define identidade, missão, comportamento e regras de cada agente. É injectado a cada heartbeat — editar o ficheiro tem efeito imediato no próximo run.
|
||||
|
||||
Aceita argumento: nome do agente (ex: `/clip-instructions CTO`).
|
||||
|
||||
## Constantes
|
||||
|
||||
```
|
||||
BD: PGPASSWORD="paperclip" psql -h localhost -p 54329 -U paperclip -d paperclip
|
||||
COMPANY_ID: ebe10308-efd7-453f-86ab-13e6fe84004f
|
||||
```
|
||||
|
||||
## Passo 1: Encontrar agente e localizar AGENTS.md
|
||||
|
||||
```sql
|
||||
SELECT id, name, role, title,
|
||||
adapter_config->>'instructionsFilePath' as instructions_path,
|
||||
adapter_config->>'instructionsRootPath' as instructions_root
|
||||
FROM agents
|
||||
WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
|
||||
AND LOWER(name) LIKE LOWER('%{{NOME}}%');
|
||||
```
|
||||
|
||||
Se `instructions_path` é NULL ou não começa com `/` → CRITICO (AGENTS.md não está a ser carregado).
|
||||
|
||||
## Passo 2: Ler ficheiro actual
|
||||
|
||||
```bash
|
||||
cat "{{instructions_path}}"
|
||||
```
|
||||
|
||||
Apresentar conteúdo completo. Identificar secções:
|
||||
- `## Identidade` — nome, papel, tipo, modelo, budget
|
||||
- `## Missão` — objectivo principal
|
||||
- `## Comportamento` — regras de actuação
|
||||
- `## Skills` / `## MCPs` — ferramentas
|
||||
- `## Heartbeat` — intervalo, checklist
|
||||
- `## Equipa` — quem reporta a quem
|
||||
|
||||
## Passo 3: Modo de actuação
|
||||
|
||||
### Ver (sem edições pedidas)
|
||||
Apresentar resumo estruturado das secções principais.
|
||||
|
||||
### Editar (utilizador pede alteração específica)
|
||||
|
||||
1. Ler ficheiro completo com Read
|
||||
2. Identificar a secção a alterar
|
||||
3. Propor a alteração ao utilizador ("Vou mudar X para Y — confirmas?")
|
||||
4. Executar com Edit após confirmação
|
||||
5. Verificar que o ficheiro ficou correcto
|
||||
|
||||
**Regras de edição segura:**
|
||||
- Nunca reescrever o ficheiro completo — usar Edit para alterações cirúrgicas
|
||||
- Preservar frontmatter YAML se existir
|
||||
- Manter estrutura de secções existente
|
||||
- Após editar, mostrar diff resumido das alterações
|
||||
|
||||
### Criar novo AGENTS.md (agente sem instruções)
|
||||
|
||||
Se `instructions_path` está definido mas o ficheiro não existe:
|
||||
|
||||
```bash
|
||||
ls "{{instructions_path}}" 2>/dev/null || echo "NAO_EXISTE"
|
||||
```
|
||||
|
||||
Criar directório se necessário:
|
||||
```bash
|
||||
mkdir -p "{{instructions_root}}"
|
||||
```
|
||||
|
||||
Template mínimo para novo AGENTS.md:
|
||||
```markdown
|
||||
# {{NOME}}
|
||||
|
||||
## Identidade
|
||||
|
||||
- **Nome:** {{NOME}}
|
||||
- **Papel:** {{ROLE}} — reporta ao {{SUPERVISOR}}
|
||||
- **Tipo:** {{TIPO}} (executor/analyst/manager)
|
||||
- **Modelo:** {{MODELO}}
|
||||
- **Budget:** {{BUDGET}} cents/mês
|
||||
|
||||
## Missão
|
||||
|
||||
{{DESCRICAO_MISSAO}}
|
||||
|
||||
## Comportamento
|
||||
|
||||
### Regras
|
||||
|
||||
- **Foco** — executar apenas tarefas dentro do scope definido
|
||||
- **Escalação** — problemas fora de scope → reportar ao supervisor
|
||||
- **PT-PT** — sempre com acentuação correcta
|
||||
|
||||
## Heartbeat
|
||||
|
||||
- **Intervalo:** {{INTERVALO}}s
|
||||
- **Checklist:** ver issues atribuídas, executar, reportar
|
||||
|
||||
## Equipa
|
||||
|
||||
- Reporta ao: {{SUPERVISOR}}
|
||||
```
|
||||
|
||||
## Passo 4: Verificar após edição
|
||||
|
||||
Confirmar que o Paperclip reconhece o ficheiro actualizado:
|
||||
```bash
|
||||
curl -s "http://localhost:3100/api/agents/{{AGENT_ID}}/instructions-bundle" \
|
||||
-H "Authorization: Bearer $PAPERCLIP_API_KEY" | python3 -c "import sys,json; d=json.load(sys.stdin); print('OK' if d.get('content') else 'VAZIO')"
|
||||
```
|
||||
|
||||
- OK = AGENTS.md carregado pelo servidor
|
||||
- VAZIO / erro = path errado ou ficheiro não encontrado
|
||||
|
||||
## Casos especiais
|
||||
|
||||
### Actualizar model no AGENTS.md
|
||||
|
||||
Se o agente mudou de modelo (ex: gemini → claude), actualizar tanto o AGENTS.md como o `adapter_config`:
|
||||
```sql
|
||||
UPDATE agents
|
||||
SET adapter_config = jsonb_set(adapter_config, '{model}', '"{{NOVO_MODELO}}"'::jsonb)
|
||||
WHERE id = '{{AGENT_ID}}'
|
||||
AND company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f';
|
||||
```
|
||||
|
||||
### Rever historial de versões (config_revisions)
|
||||
|
||||
```sql
|
||||
SELECT cr.id, cr.created_at::timestamp(0), a.name as criado_por
|
||||
FROM agent_config_revisions cr
|
||||
LEFT JOIN agents a ON cr.created_by_agent_id = a.id
|
||||
WHERE cr.agent_id = '{{AGENT_ID}}'
|
||||
ORDER BY cr.created_at DESC
|
||||
LIMIT 10;
|
||||
```
|
||||
|
||||
### Rollback via API
|
||||
|
||||
```bash
|
||||
curl -s -X POST "http://localhost:3100/api/agents/{{AGENT_ID}}/config-revisions/{{REVISION_ID}}/rollback" \
|
||||
-H "Authorization: Bearer $PAPERCLIP_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Formato de output
|
||||
|
||||
```
|
||||
## Instruções — {{NOME}} ({{role}})
|
||||
|
||||
**Ficheiro:** {{instructions_path}}
|
||||
**Estado:** carregado / não encontrado / path inválido
|
||||
|
||||
### Resumo actual
|
||||
**Missão:** [1 linha]
|
||||
**Modelo:** {{model}} | **Budget:** {{budget}} cents | **Heartbeat:** {{intervalo}}s
|
||||
**Regras principais:** [lista]
|
||||
**Skills:** [lista ou "nenhuma"]
|
||||
|
||||
### Alterações efectuadas (se editou)
|
||||
[diff resumido]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Healing Log
|
||||
|
||||
```jsonl
|
||||
{"date":"2026-04-07","issue":"instructionsFilePath relativo — AGENTS.md não carregava após criação via SQL","fix":"Path deve ser sempre absoluto. Verificar com query adapter_config->>'instructionsFilePath' NOT LIKE '/%'","source":"auto"}
|
||||
```
|
||||
Reference in New Issue
Block a user