claude-plugins/core-tools/skills/metrics/SKILL.md

name, description

name	description
metrics	Dashboard de metricas de performance de skills e agentes com telemetria quantitativa, trending temporal, alertas de degradacao e calculo de ROI.

SKILL: Performance Metrics Dashboard

Proposito

Dashboard interactivo de performance de skills e agents com metricas quantitativas automaticas gravadas em Desk DB.

Complementa /reflect (qualitativo) com dados quantitativos, /worklog com metricas objectivas, e PDCA com decisoes data-driven.

---

Quando Usar

• Ver performance de skills/agents
• Identificar degradacoes de performance
• Validar melhorias PDCA
• Analise ROI de optimizacoes
• Dashboard executivo de automacao

---

Comandos

Comando	Funcao
/metrics	Overview geral (30 dias)
/metrics <skill-name>	Detalhes de skill especifica
/metrics --project <id>	Metricas por projecto
/metrics --trend	Trending temporal
/metrics --compare	Comparacao vs baseline
/metrics --kb	Metricas Dify KB
/metrics --roi	ROI por cliente/projecto
/metrics --export	Exportar JSON/CSV
/metrics --alerts	Listar alertas activos
/metrics --tools	Telemetria local de tool calls (ver secção Local Tool Telemetry)

---

Local Tool Telemetry (G3.1-B)

Desde 08-04-2026 há captura universal de todas as tool calls do Claude Code via hook PostToolUse (~/.claude/hooks/telemetry-posttool-hook.sh). Complementa a telemetria Desk CRM com dados locais imediatos.

Ficheiro: ~/.claude-work/tool-invocations.jsonl (1 linha por tool call: ts, session, tool_use_id, tool_name, success, error)

Agregador: /media/ealmeida/Dados/Dev/ClaudeDev/tool-metrics.py

# Overview últimas 24h
python3 /media/ealmeida/Dados/Dev/ClaudeDev/tool-metrics.py

# Só hoje
python3 /media/ealmeida/Dados/Dev/ClaudeDev/tool-metrics.py --today

# Últimos 7 dias
python3 /media/ealmeida/Dados/Dev/ClaudeDev/tool-metrics.py --last 7d

# Filtrar por sessão
python3 /media/ealmeida/Dados/Dev/ClaudeDev/tool-metrics.py --session <session_id>

# Output JSON (para pipeline/grafos)
python3 /media/ealmeida/Dados/Dev/ClaudeDev/tool-metrics.py --json

Output: total de invocations, sessões únicas, top 20 tools (contagem + %), falhas por tool com amostras de erro, top 5 sessões por volume.

Limitações conhecidas:

• Duration não é capturada (harness não entrega duration no hook payload). Apenas contagem e success/failure.
• Tokens não capturáveis via hooks (não estão no payload).
• Só captura tool calls que chegam ao PostToolUse — tool calls bloqueados por hooks PreToolUse não aparecem.

Ver 04-Stack/CHANGELOG.md bloco 08-04-2026 sessão 2 para contexto do gap e decisão de scope.

Agregacoes Disponiveis

1. avg - Medias de performance (padrao)
2. count - Contagens por status
3. trend - Evolucao temporal (semanal)
4. compare - Comparacao com baseline
5. detailed - Listagem detalhada

---

Execucao

1. Verificar Tools MCP

// Tools necessarios (MCP desk-crm-v3)
const REQUIRED_TOOLS = [
  'mcp__desk-crm-v3__log_skill_metric',
  'mcp__desk-crm-v3__get_skill_metrics'
];
// Se tools nao disponiveis -> query SQL directa como fallback

2. Query Metricas

Via MCP (preferencial):

const metrics = await mcp__desk_crm_v3__get_skill_metrics({
  days: 30,
  aggregate: 'avg',
  limit: 10
});

Fallback SQL: Ver references/sql-queries.md

3. Formatar Output

Performance Overview (ultimos {days} dias)

Top Skills/Agents:
| Nome           | Usos | Avg Time | Trend | Status |
|----------------|------|----------|-------|--------|
| /orcamento     | 45   | 18min    | -12%  | OK     |
| /lead-approach | 38   | 22min    | +5%   | Alerta |
| wp-plugin-dev  | 32   | 47min    | -8%   | OK     |

4. Analise Especifica

const details = await get_skill_metrics({
  name: skill_name,
  days: 30,
  aggregate: 'detailed'
});

const baseline = await query(
  "SELECT baseline_duration_ms FROM tblskill_agent_baselines WHERE name = ?",
  [skill_name]
);
const improvement = ((baseline - current_avg) / baseline * 100);

---

Alertas Automaticos

const degraded = await get_skill_metrics({
  aggregate: 'compare',
  days: 7
});

const alerts = degraded.results.filter(r =>
  r.performance_status === 'DEGRADED'
);

if (alerts.length > 0) {
  // Output alertas e sugerir /reflect para investigar
}

Trigger Reflect se Degradacao

if (degradation_pct > 15) {
  // AUTO: Invocar reflect-agent em background
  Task({
    subagent_type: 'reflect-agent',
    background: true,
    model: 'sonnet',
    prompt: `PERFORMANCE DEGRADATION: ${name} +${degradation_pct}%`
  });
}

---

Integracao com Outros Sistemas

Comando	Foco	Quando Usar
/taskforce kb-health	Saude sistema KB	Visao arquitectural
/metrics --kb	Performance queries KB	Analise operacional
/metrics --roi	Valor economico gerado	Justificacao investimento

Workflow recomendado:

1. /taskforce kb-health - Verificar gaps e coverage
2. /metrics --kb - Analisar performance queries
3. /metrics --roi - Calcular ROI para stakeholders

Link Desk CRM: https://desk.descomplicar.pt/admin/projects/view/65

---

Notas Tecnicas

Tabelas DB: tblskill_agent_metrics (telemetria), tblskill_agent_baselines (baselines), tblskill_agent_pdca_cycles (PDCA historico)

Tools: Implementados em /opt/desk-crm-v3/src/tools/core/metrics.ts

Fallback: Se tools MCP nao disponiveis, usar queries SQL directas via sql_direct.

---

Conteudo Detalhado

Referencia	Conteudo
references/sql-queries.md	Queries SQL completas (top 10, ROI, trending)
references/dashboards-templates.md	Templates visuais KB, ROI, alertas, export, ASCII charts

---

Desk CRM: Projecto #65, Task #1637

---

Healing Log

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

{"date":"","issue":"","fix":"","source":"user|auto"}

Adicionar nova linha após cada erro corrigido.