claude-plugins/gestao/skills/clip-instructions/SKILL.md

name, description, context, version, created

name	description	context	version	created
clip-instructions	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".	fork	1.0.0	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

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

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:

ls "{{instructions_path}}" 2>/dev/null || echo "NAO_EXISTE"

Criar directório se necessário:

mkdir -p "{{instructions_root}}"

Template mínimo para novo AGENTS.md:

# {{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:

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:

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)

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

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

{"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"}