claude-plugins/core-tools/skills/_core/instrumentation-protocol.md

Protocolo de Instrumentação Automática v1.0

Data: 2026-02-03 Propósito: Auto-registar métricas de execução de skills para análise PDCA

---

Visão Geral

Toda skill instrumentada deve gravar automaticamente métricas de execução na tabela tblskill_agent_metrics do Desk CRM.

Quando Instrumentar

Skills que:

• Têm baseline definido em _knowledge-map.json
• São frequentemente usadas (>5x/semana)
• Estão em processo de optimização

Estrutura de Instrumentação

1. Início de Execução

Ao iniciar a skill, registar:

const SKILL_START = Date.now();
const SESSION_ID = crypto.randomUUID(); // ou usar session_id existente

2. Rastreio de Consultas KB

Se a skill consultar Dify KB:

let KB_CONSULTED = false;
let KB_HITS = 0;
let KB_MISS = 0;

// Após cada consulta Dify bem sucedida
KB_CONSULTED = true;
KB_HITS++;

// Se consulta falhou ou sem resultados
KB_MISS++;

3. Contagem de Tool Calls

let TOOL_CALLS = 0;

// Incrementar a cada tool call
TOOL_CALLS++;

4. Fim de Execução - Gravar Métrica

Via SQL directo (fallback robusto):

INSERT INTO tblskill_agent_metrics (
  type, name, duration_ms, status,
  session_id, task_id, project_id, staff_id,
  kb_consulted, kb_hits, kb_miss, tool_calls,
  error_type, error_message, context_tokens, output_tokens,
  model_used, created_at
) VALUES (
  'skill', '/nome-skill', {DURATION_MS}, '{STATUS}',
  '{SESSION_ID}', {TASK_ID}, {PROJECT_ID}, 25,
  {KB_CONSULTED}, {KB_HITS}, {KB_MISS}, {TOOL_CALLS},
  NULL, NULL, NULL, NULL,
  'opus-4.5', NOW()
);

Via MCP tool (quando disponível):

mcp__desk-crm-v3__log_skill_metric({
  type: 'skill',
  name: '/nome-skill',
  duration_ms: Date.now() - SKILL_START,
  status: 'success', // ou 'error', 'partial'
  session_id: SESSION_ID,
  task_id: CURRENT_TASK_ID,
  project_id: CURRENT_PROJECT_ID,
  staff_id: 25, // AikTop
  kb_consulted: KB_CONSULTED,
  kb_hits: KB_HITS,
  kb_miss: KB_MISS,
  tool_calls: TOOL_CALLS
});

Status Possíveis

Status	Quando Usar
success	Skill completou com sucesso
error	Skill falhou com erro
partial	Skill completou parcialmente
cancelled	Utilizador cancelou

Campos Opcionais

Campo	Quando Preencher
task_id	Se executando dentro de tarefa Desk
project_id	Se contexto de projecto conhecido
error_type	Se status = 'error'
error_message	Se status = 'error'
context_tokens	Se disponível via API
output_tokens	Se disponível via API

Template para Skills

Adicionar esta secção no final de cada SKILL.md instrumentada:

---

## Instrumentação Automática

Esta skill grava métricas automaticamente para análise PDCA.

### Ao Executar Esta Skill

1. **Início:** Registar timestamp inicial
2. **Consultas KB:** Rastrear hits/miss do Dify
3. **Fim:** Gravar métrica via SQL ou MCP

### Query para Gravar (executar no final)

\`\`\`sql
INSERT INTO tblskill_agent_metrics (type, name, duration_ms, status, staff_id, kb_consulted, created_at)
VALUES ('skill', '/nome-skill', {DURACAO_MS}, '{STATUS}', 25, {KB_CONSULTADO}, NOW());
\`\`\`

### Ver Métricas

\`\`\`bash
/metrics /nome-skill
\`\`\`

Integração com /reflect

Se degradação detectada (performance >15% pior que baseline):

1. /metrics mostra alerta
2. Sugerir /reflect para investigação
3. /reflect analisa padrões e propõe melhorias
4. Registar ciclo PDCA em tblskill_agent_pdca_cycles

---

Protocolo v1.0 | 2026-02-03