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

---
name: clip-skill
description: Gerir company skills no Paperclip — listar, instalar, atribuir a agentes, auditar cobertura. Usar quando "clip skill", "skills clip", "instalar skill", "atribuir skill", "skills paperclip".
context: fork
---

# /clip-skill — Gerir Company Skills Paperclip

Gerir skills instaladas na empresa Descomplicar no Paperclip. Instalar, atribuir, remover e auditar.

## Constantes

```
BD: PGPASSWORD="paperclip" psql -h localhost -p 54329 -U paperclip -d paperclip
COMPANY_ID: ebe10308-efd7-453f-86ab-13e6fe84004f
API: http://localhost:3100/api
SKILLS_CC: ~/.claude/plugins/marketplaces/descomplicar-plugins/
```

## Contexto técnico

Skills no Paperclip funcionam como **injecção de contexto em runtime**:
- O conteúdo do SKILL.md é injectado como contexto adicional ao agente a cada heartbeat
- Não há instalação permanente — a skill é lida do ficheiro a cada execução
- Atribuição é por agente via `adapter_config.paperclipSkillSync.desiredSkills` (array de slugs)
- Skills instaladas na empresa ficam em `company_skills` — só as atribuídas ao agente são injectadas

**Distribuição actual de adapters:**
- 1 agente (CEO): `gemini_local` com `gemini-2.5-pro`
- 50 agentes: `gemini_local` com `gemini-2.5-flash`
- 13 agentes: `opencode_local` com `openrouter/x-ai/grok-4.1-fast`
- Agentes analyst/passive (ex: Reality Checker): `process` com `claude-sonnet-4-6` (sem heartbeat, sem skills)

O adapter `claude_local` já não é usado para agentes heartbeat.

## Modo lista (sem argumentos)

### Skills instaladas na empresa

```sql
SELECT name, slug, key, source_type, trust_level, compatibility,
  created_at::date as instalada
FROM company_skills
WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
ORDER BY name;
```

### Agentes com skills atribuidas

```sql
SELECT name, role, status,
  adapter_config->'paperclipSkillSync'->'desiredSkills' as skills
FROM agents
WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
AND adapter_config::text LIKE '%paperclipSkillSync%'
ORDER BY name;
```

### Resumo

Apresentar:
```
## Skills Clip — [data]

**Empresa:** N skills instaladas (N locais, N built-in)
**Agentes:** N com skills atribuidas / 62 total

### Skills instaladas
| Nome | Key | Fonte | Trust | Compativel |
...

### Agentes com skills
| Agente | Role | Skills |
...

### Agentes sem skills (top 10 por relevancia)
[listar agentes com routines activas mas sem skills]
```

## Modo instalar (com path ou key)

### Instalar skill de path local

Argumento: path absoluto para pasta com SKILL.md.

Verificar primeiro que existe SKILL.md:
```bash
ls {{PATH}}/SKILL.md 2>/dev/null && head -5 {{PATH}}/SKILL.md
```

Instalar via API:
```bash
curl -s -X POST "http://localhost:3100/api/companies/ebe10308-efd7-453f-86ab-13e6fe84004f/skills/import" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -d '{"source": "{{PATH}}"}'
```

Se API falha (auth), inserir directamente na BD:
```sql
-- Ler frontmatter do SKILL.md para obter name e description
-- Depois inserir:
INSERT INTO company_skills (id, company_id, key, slug, name, description, markdown, source_type, source_locator, trust_level, compatibility, file_inventory, created_at, updated_at)
VALUES (
  gen_random_uuid(),
  'ebe10308-efd7-453f-86ab-13e6fe84004f',
  'descomplicar/{{PLUGIN}}/{{SKILL_NAME}}',
  '{{SKILL_NAME}}',
  '{{NAME_FROM_FRONTMATTER}}',
  '{{DESCRIPTION_FROM_FRONTMATTER}}',
  '{{FULL_SKILL_MD_CONTENT}}',
  'local_path',
  '{{PATH}}',
  'markdown_only',
  'compatible',
  '[]'::jsonb,
  NOW(), NOW()
)
RETURNING id, name, slug;
```

Confirmar com o utilizador antes de instalar. Mostrar name e description do SKILL.md.

### Instalar skill do marketplace CC

Argumento: nome da skill no formato `plugin/skill` (ex: `crm-ops/crm`).

Resolver path:
```bash
SKILL_PATH="$HOME/.claude/plugins/marketplaces/descomplicar-plugins/{{PLUGIN}}/skills/{{SKILL}}"
ls "$SKILL_PATH/SKILL.md" 2>/dev/null && head -10 "$SKILL_PATH/SKILL.md"
```

Depois seguir o fluxo de instalacao por path local.

### Instalar em massa (com filtro de plugin)

Argumento: nome do plugin (ex: `crm-ops`).

```bash
find "$HOME/.claude/plugins/marketplaces/descomplicar-plugins/{{PLUGIN}}/skills/" -name "SKILL.md" -exec dirname {} \;
```

Listar todas as skills encontradas com name e description. Pedir confirmacao antes de instalar cada uma.

## Modo atribuir (skill a agente)

### Atribuir via API

```bash
curl -s -X POST "http://localhost:3100/api/agents/{{AGENT_ID}}/skills/sync" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -d '{"desiredSkills": [{{SKILLS_ARRAY}}]}'
```

### Atribuir via BD (fallback)

```sql
UPDATE agents SET adapter_config = jsonb_set(
  COALESCE(adapter_config, '{}'::jsonb),
  '{paperclipSkillSync}',
  jsonb_build_object('desiredSkills', '{{SKILLS_JSON_ARRAY}}'::jsonb)
)
WHERE id = '{{AGENT_ID}}'
AND company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
RETURNING name, adapter_config->'paperclipSkillSync'->'desiredSkills';
```

Confirmar sempre:
- Nome do agente
- Skills a atribuir (mostrar name de cada)
- Se vai substituir ou adicionar a skills existentes

### Atribuir por departamento (batch)

Argumento: nome do C-Level ou Director.

1. Obter agentes subordinados:
```sql
SELECT id, name, role FROM agents
WHERE reports_to = '{{MANAGER_ID}}'
AND company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f';
```

2. Listar skills recomendadas para o departamento
3. Confirmar com utilizador
4. Aplicar a cada agente

## Modo remover

### Remover skill de agente

Ler skills actuais, filtrar a removida, escrever de volta:

```sql
-- Ler
SELECT adapter_config->'paperclipSkillSync'->'desiredSkills' as skills
FROM agents WHERE id = '{{AGENT_ID}}';

-- Actualizar (remover skill especifica)
-- Construir novo array sem a skill removida e usar o UPDATE do modo atribuir
```

### Desinstalar skill da empresa

```sql
DELETE FROM company_skills
WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
AND slug = '{{SLUG}}'
RETURNING name, slug;
```

Avisar: isto remove a skill de todos os agentes que a referenciam. Confirmar sempre.

## Modo auditar

### Cobertura de skills

```sql
-- Agentes com routines activas mas sem skills
SELECT a.name, a.role, r.title as routine
FROM agents a
JOIN routines r ON r.assignee_agent_id = a.id
WHERE a.company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f'
AND r.status = 'active'
AND (a.adapter_config->'paperclipSkillSync' IS NULL
     OR a.adapter_config::text NOT LIKE '%paperclipSkillSync%')
ORDER BY a.name;
```

### Mapeamento recomendado (plugin CC → departamento Clip)

| Plugin CC | Agentes-alvo | Skills prioritarias |
|-----------|-------------|-------------------|
| core-tools | Todos | _core, quality-validator |
| crm-ops | CRO, Dir. Comercial, Sales Manager, Lead Qualifier | crm, desk, lead-approach, orcamento |
| gestao | COO, Dir. Operacoes, Project Manager | today, worklog, knowledge, tasks-overview |
| infraestrutura | CTO, Dir. Infraestrutura, Infra Check, Backup Specialist | gateway-check, backup, easypanel, cwp-server |
| marketing | CMO, Dir. SEO, Dir. Publicidade | seo-audit, seo-technical, ppc |
| wordpress | Dir. Web, WP Update | wp-dev, wp-performance, wp-cli |
| dev-tools | Dir. Desenvolvimento, Development Lead | dev-helper, pdf, docx |
| automacao | Dir. Automacao | n8n, automation-lead |
| negocio | CFO, CGO, Finance Manager | finance, research, saas |
| perfex-dev | Dir. Desenvolvimento | perfex-module |

### Comparacao CC vs Clip

```sql
-- Skills CC disponiveis (contar no filesystem)
-- vs skills instaladas no Clip
SELECT
  (SELECT COUNT(*) FROM company_skills WHERE company_id = 'ebe10308-efd7-453f-86ab-13e6fe84004f') as instaladas_clip;
```

```bash
find ~/.claude/plugins/marketplaces/descomplicar-plugins/ -name "SKILL.md" | wc -l
```

Apresentar:
```
### Auditoria Skills — [data]

**CC:** N skills disponiveis em 15 plugins
**Clip:** N instaladas (N%)
**Agentes com skills:** N/62 (N%)
**Agentes com routines sem skills:** N (ATENCAO)

### Gaps por departamento
| Departamento | Agentes | Com skills | Sem skills | Skills recomendadas |
...
```

## Referencias

- Mecanismo runtime injection: conteúdo SKILL.md injectado como contexto adicional a cada heartbeat
- API skills: `skills/paperclip/references/company-skills.md`
- Schema BD: tabela `company_skills` (16 colunas)
- Auditoria compatibilidade: `04-Stack/02.06-Clip/auditoria-skills-compatibilidade.md`
- Manual: `06-Operacoes/Documentacao/Manuais/Paperclip/06-skills-e-plugins.md`

---

## Healing Log

Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.

```jsonl
{"date":"2026-04-07","issue":"API /skills/import e /skills/sync sem Authorization header — rejeitadas com 401","fix":"Adicionar -H 'Authorization: Bearer $PAPERCLIP_API_KEY' a todos os curl da skill","source":"auto"}
```

*Adicionar nova linha após cada erro corrigido.*