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

name, description, context, layer

name	description	context	layer
clip-agent	Gerir agente Paperclip individual — estado, config, AGENTS.md, histórico runs, issues. Aceita nome como argumento. Usar quando "clip agent", "agente clip", "ver agente", "estado do CTO".	fork	wiki

/clip-agent — Gerir Agente Paperclip

Aceita argumento: nome do agente (ex: /clip-agent CTO).

Constantes

BD: PGPASSWORD="paperclip" psql -h localhost -p 54329 -U paperclip -d paperclip
COMPANY_ID: ebe10308-efd7-453f-86ab-13e6fe84004f
AGENTS_PATH: /media/ealmeida/Dados/Hub/04-Stack/02.06-Clip/agents/

Procedimento

Passo 1: Contexto completo do agente

Invocar tool MCP: mcp__paperclip__diag_agent_full_context(agent_name="{{NOME}}")

Esta tool retorna config, últimas runs, membership, permissões e tokens — cobre os Passos 1, 3, 6, 7 e 7b de uma só vez. Se multiplos resultados, mostrar lista e pedir clarificacao.

Passo 2: Hierarquia

Quem lhe reporta:

SELECT name, role, status FROM agents
WHERE reports_to = '{{AGENT_ID}}'
AND company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
ORDER BY role, name;

A quem reporta:

SELECT name, role FROM agents WHERE id = '{{REPORTS_TO_ID}}';

Passo 3: Ultimas 5 runs

SELECT hr.status, hr.started_at, hr.finished_at, LEFT(hr.error, 80) as erro
FROM heartbeat_runs hr
WHERE hr.agent_id = '{{AGENT_ID}}'
ORDER BY hr.started_at DESC LIMIT 5;

Passo 4: Issues atribuidas

SELECT title, status, priority FROM issues
WHERE assignee_agent_id = '{{AGENT_ID}}'
AND status NOT IN ('done','cancelled')
ORDER BY priority, status;

Passo 4b: Verificar falsos blockers (INC-07)

Se o agente tem issues blocked, invocar tool MCP: mcp__paperclip__diag_false_blockers e filtrar pelo agente. TODO: criar diag_* tool per-agent se uso recorrente.

Se sub_activas > 0 e o agente está operacional → falso blocker. Alertar: "Issue {{ID}} marcada como blocked mas tem sub-tasks activas — deveria ser in_progress."

Passo 5: AGENTS.md

Procurar em AGENTS_PATH:

find /media/ealmeida/Dados/Hub/04-Stack/02.06-Clip/agents/ -name "AGENTS.md" -exec grep -l "{{NOME}}" {} \;

Se encontrado, ler e apresentar resumo (primeiras 30 linhas).

Formato de output

## Agente: {{NOME}}

**Role:** {{role}} | **Status:** {{status}} | **Ultimo heartbeat:** {{last_heartbeat_at}}
**Reporta a:** {{reports_to_name}} | **Budget:** {{spent}}/{{budget}} ({{pct}}%)
**Tokens cached:** {{tokens_M}}M | **CWD:** {{cwd}} | **Model:** {{model}}

### Equipa (reportam a este agente)
| Nome | Role | Status |
...

### Ultimas 5 runs
| Status | Início | Fim | Erro |
...

### Issues atribuidas
| Titulo | Status | Prioridade |
...

### Skills atribuidas
[lista de desiredSkills ou "Sem skills (apenas built-in paperclip)"]

### AGENTS.md
[resumo ou path]

Passo 6: Skills do agente

SELECT
  adapter_config->'paperclipSkillSync'->'desiredSkills' as desired_skills
FROM agents
WHERE id = '{{AGENT_ID}}';

Se nao NULL, listar as skills. Se NULL, indicar "Sem skills atribuidas (apenas built-in paperclip)".

Para ver detalhes das skills disponiveis na empresa:

SELECT name, slug, key, source_type FROM company_skills
WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
ORDER BY name;

Skills atribuídas ao agente

-- Ver skills desejadas (configuradas via API)
SELECT
  a.name as agente,
  a.adapter_config->'paperclipSkillSync'->'desiredSkills' as desired_skills
FROM agents a
WHERE a.id = '{{AGENT_ID}}';

Acções disponíveis:

• Ver skills da empresa: SELECT name, slug FROM company_skills WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
• Atribuir skills via API (fetch no browser): POST /api/agents/{{AGENT_ID}}/skills/sync com { "desiredSkills": ["slug1", "slug2"] }

Membership (OBRIGATÓRIO — sem isto, permissões não funcionam)

A função hasPermission() verifica primeiro se o agente tem membership activa em company_memberships. Sem membership → permissão negada mesmo com grants correctos.

-- Verificar membership
SELECT status, membership_role FROM company_memberships
WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
AND principal_id = '{{AGENT_ID}}';

Se 0 rows → agente não tem membership. Criar:

INSERT INTO company_memberships (id, company_id, principal_type, principal_id, status, membership_role, created_at, updated_at)
VALUES (gen_random_uuid(), 'ebe10308-efd7-453f-86ab-13e6fe84004f', 'agent', '{{AGENT_ID}}', 'active', 'member', NOW(), NOW());

Nota: Agentes criados via SQL directo NÃO recebem membership automaticamente — apenas os onboarded via fluxo OpenClaw/hiring. Sempre criar membership ao adicionar agentes manualmente.

Permissões do agente

SELECT permission_key FROM principal_permission_grants
WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
AND principal_id = '{{AGENT_ID}}';

Para adicionar tasks:assign (necessário para delegação):

INSERT INTO principal_permissi