---
name: mcp-skill-miner
description: >
  Mine local AI agent session histories (Codex CLI, Claude Code, Cursor,
  Antigravity, Copilot) together with the current skills/ inventory to find
  skill-worthy patterns: completed, repeatable use cases that justify creating a
  new skill or enhancing an existing one. Codex CLI and Claude Code typically have
  the richest, most directly readable local session data; Cursor (SQLite-backed),
  Antigravity, and Copilot may have little or no usable local history depending on
  the machine, so treat their coverage as best-effort, not guaranteed. Use when the
  user asks to scan chat/session history for skill candidates, audit which skills
  are underused or missing coverage, or wants a data-driven adopt/enhance/reference/backlog
  matrix instead of guessing. Do not use for day-to-day analytics usage queries
  (mcp-analytics-operator), for actually scaffolding/writing a brand-new skill once
  the decision is made (use the skill-creator flow), or for a single-session/single-source
  technical analysis (mcp-technical-analyst).
---

# MCP Skill Miner

Skill specialistico per formalizzare il processo di "mining" delle sessioni storiche degli agenti AI (Codex CLI, Claude Code, Cursor, Antigravity, Copilot) incrociate con l'inventario delle skill esistenti in `skills/`, per produrre una matrice di candidati "nuova skill / enhance skill esistente / reference-backlog / scarta", basata su evidenze verificabili e non su intuizioni. Nasce dall'esercizio reale eseguito il 2026-07-10 su S:\mcp-servers (questo repository).

## Quick Routing

Usa questa skill quando serve:

- scansionare le sessioni AI locali per trovare pattern skill-worthy (comportamenti ripetibili che giustificano una nuova skill o un enhancement);
- auditare quali skill sono sottoutilizzate o completamente mancanti nel repertorio;
- produrre una matrice decisionale data-driven (candidati, evidenze, classificazione) invece di affidarsi a intuizioni;
- verificare se un cluster di use case trovato e' gia' coperto da una skill esistente (anche parzialmente);
- gestire parallelizzazione di sub-agent su fonti multiple per volumi alti.

Non usarla per:

- interrogare analytics in uso quotidiano (query, conteggi, statistiche di utilizzo) -> `mcp-analytics-operator`;
- scrivere/scaffoldare il codice di una skill nuova una volta presa la decisione -> `skill-creator` flow;
- analisi tecnica approfondita di un singolo cluster, sessione o bug -> `mcp-technical-analyst`;
- coordinamento multi-fase cross-dominio -> `mcp-master-orchestrator`.

## Metodologia Operativa

### 1. Inventario skill esistenti (Passo 0 obbligatorio)

Prima di qualunque campionamento storico, leggere tutte le `SKILL.md` in `skills/` e annotare:
- **Scopo**: cosa dichiara di fare, trigger espliciti (es. "usa quando X"), cosa NON copre ("non usarla per Y");
- **MCP/Tool utilizzati**: quali MCP server o tool sono richiesti dal workflow;
- **Struttura**: presenza di `evals/evals.json`, cartella `references/`, checklist/playbook.

Questo inventario e' la base di confronto per ogni candidato trovato nei log. Senza aggiornarlo all'inizio, non si puo' giudicare se un cluster e' "nuovo" o "gia' coperto".

### 2. Diffidare dei conteggi aggregati (Regola Fondamentale)

Se esiste uno strumento tipo `analytics-mcp-server` o `mcp-analytics-operator` che da' conteggi di sessioni multi-fonte, usarlo SOLO come punto di partenza orientativo — mai come numero definitivo.

**Verificare sempre sul filesystem reale**:
- Codex CLI: file `session_index.jsonl` nel workspace — fonte ricca, indice titoli leggibile direttamente;
- Claude Code: cartelle `projects/*.jsonl` in profilo utente — fonte ricca, trascrizioni JSONL dirette (attenzione: molti file sono sub-agent, non thread utente, vedi sotto);
- Cursor: database SQLite locale, non JSONL semplice — accesso piu' oneroso (serve query SQL o esportazione), spesso poche sessioni sostanziali;
- Antigravity: spesso directory quasi vuota o assente sulla macchina — non dare per scontato che esista storico utile, verificare prima di pianificare tempo di campionamento su questa fonte;
- Copilot: dati locali tipicamente non organizzati per una lettura diretta equivalente alle altre fonti (possono richiedere ispezione di user data di un IDE) — trattare come fuori scope se non accessibile in tempi ragionevoli.

**Non pianificare un budget di campionamento uguale per tutte e 5 le fonti**: Codex CLI e Claude Code meritano la maggior parte del tempo (dati ricchi e diretti); su Cursor/Antigravity/Copilot verifica rapidamente se c'e' segnale reale prima di investire tempo, e se non c'e' dichiaralo esplicitamente nei limiti del campionamento invece di forzare una copertura simmetrica.

**Attenzione critica**: molte "sessioni" contate da tool aggregati sono in realta' trascrizioni di sub-agent lanciati da un orchestratore, non thread indipendenti dell'utente — vanno interpretate con cautela, non sommate ingenuamente.

### 3. Campionamento intelligente per fonti ad alto volume

Non leggere tutte le trascrizioni. Sequenza:

1. **Leggi gli indici prima** (economico): se esiste un indice con titoli leggibili (es. `thread_name` in Codex, `aiTitle`/titolo sessione in Claude Code), leggerlo per intero per raggruppare per tema/dominio.
2. **Campiona per cluster**: dopo aver identificato i cluster tematici dall'indice, aprire solo 2-4 trascrizioni reali per ogni cluster, preferendo le piu' recenti e dense di interazione.
3. **Leggi inizio + fine, non tutto**: primo messaggio (task/intenzione), ultimi messaggi (esito/conclusione). Non occorre leggere ogni turno di conversazione.
4. **Traccia fonti convergenti**: se due tool diversi (es. Codex + Claude Code) riportano lo stesso pattern, e' evidenza piu' forte di un pattern isolato.

Vedi `references/sampling-heuristics.md` per dettagli con esempi.

### 4. Criteri minimi per proporre una NUOVA skill

Non basta un singolo caso di uso. Per giustificare una nuova skill:

- **Minimo 2 casi indipendenti**: idealmente su progetti/date diverse, meglio se osservati da fonti/tool AI diversi che convergono sullo stesso pattern reale;
- **Workflow stabile e riconoscibile**: passaggi ripetibili, non un'eccezione;
- **Trigger distinguibile**: deve rispondere a una domanda/intenzione non gia' coperta;
- **Output ripetibile**: produce un artefatto o decisione riconoscibile;
- **Valore non gia' coperto**: cross-check esplicito contro skill esistenti (regola 5).

### 5. Cross-reference sistematico con inventario

Per ogni cluster trovato, prima di proporre "nuovo":

1. Verificare esplicitamente se una skill esistente lo copre gia', anche solo parzialmente;
2. Se parzialmente coperto, preferire un **enhancement mirato** a una skill duplicata;
3. Documentare se il trigger e' veramente distinguibile da skill vicine (es. "mining" vs "analytics operator").

### 6. Parallelizzazione con sub-agent read-only

Per volumi alti, usare un sub-agent dedicato per fonte (es. uno per Codex, uno per Claude Code, uno per Cursor/Antigravity/Copilot, uno per l'inventario skill), **tutti in sola lettura, nessuna modifica**.

La sintesi finale/incrocio deve essere fatta da chi ha visto TUTTE le fonti (l'orchestratore), mai delegata a un sub-agent parziale.

### 7. Controllare lavoro precedente

Prima di ripartire da zero, verificare se esiste gia' un'analisi/piano sullo stesso argomento (es. una sessione precedente con lo stesso obiettivo) per:
- **Evitare duplicazione**: non rifare lo stesso campionamento;
- **Validare risultati precedenti**: usarla come input aggiuntivo da verificare, non da accettare acriticamente.

Vedi `references/worked-example-2026-07-10.md`: contiene il caso reale di questa skill sul repository S:\mcp-servers.

### 8. Output finale della Skill

Matrice con colonne (esempio di formato, con placeholder generici — i valori reali vanno sempre presi dal campionamento effettivo, mai inventati):

| Candidato | Tipo | Evidenza (fonte/ID sessione) | Decisione | Motivazione |
|-----------|------|-----|----------|------------|
| Candidato A | Nuova skill | Fonte 1 + Fonte 2, N sessioni indipendenti convergenti | ADOTTA | Workflow stabile, trigger distinguibile, valore non coperto |
| Candidato B | Enhancement | Fonte X, overlap parziale con skill Y esistente | ENHANCE | Arricchisce skill Y invece di duplicarla |
| Candidato C | Candidato | 1 sola sessione/fonte | BACKLOG | Evidenza insufficiente (sotto soglia dei 2 casi indipendenti), rivisitare se ricorrente |
| Candidato D | Scarta | Gia' coperto integralmente da skill esistente | SCARTA | Overlap totale, non giustifica nulla di nuovo |

Per un caso reale con dati veri (non placeholder), vedi [references/worked-example-2026-07-10.md](references/worked-example-2026-07-10.md).

Aggiungere sempre una sezione esplicita: **Limiti del campionamento** (fonti controllate, volume, date, copertura % dello storico effettivo).

### 9. Privacy e Sensibilita'

Nel deliverable finale non riportare contenuti sensibili di prompt/risposte di sessioni cliente oltre quanto necessario a giustificare il pattern:
- **Sì**: nomi progetto, tema generale (es. "debugging React grid component");
- **No**: prompt specifici del cliente, valori config, dati riservati.

## Sinergie

- con **mcp-analytics-operator**: per i conteggi aggregati iniziali (solo orientativi, vedi regola 2). Una volta deciso di adottare una skill, passare a questo operatore per l'uso quotidiano;
- con **mcp-master-orchestrator**: per orchestrare i sub-agent paralleli su fonti multiple (Codex, Claude Code, Cursor, Antigravity, Copilot, inventario skill) quando il volume richiede parallelizzazione;
- con **skill-creator flow** (Anthropic): da usare DOPO questa analisi, quando si e' deciso di creare davvero una nuova skill, per lo scaffolding/validazione/eval. Non in competizione;
- con **mcp-technical-analyst**: se serve un'analisi tecnica approfondita su un singolo cluster oltre alla semplice classificazione (es. "verifica se il pattern X e' davvero nuovo o solo variante di Y tecnico").

## References

- [references/sampling-heuristics.md](references/sampling-heuristics.md)
- [references/worked-example-2026-07-10.md](references/worked-example-2026-07-10.md)