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,292 @@
|
||||
---
|
||||
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.*
|
||||
Reference in New Issue
Block a user