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

name, description, context

name	description	context
clip-skill	Gerir company skills no Paperclip — listar, instalar, atribuir a agentes, auditar cobertura. Usar quando "clip skill", "skills clip", "instalar skill", "atribuir skill", "skills paperclip".	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

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

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:

ls {{PATH}}/SKILL.md 2>/dev/null && head -5 {{PATH}}/SKILL.md

Instalar via API:

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:

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

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).

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

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)

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:

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:

-- 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

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

-- 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

-- 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;

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.

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