Skill e subagent

Il repo cliente porta il kit dell'agente: gli strumenti che insegnano a Claude Code a lavorare secondo le regole del core. pnpm exec etl agent sync li copia dal core installato in .claude/skills/noeva-etl-*, .claude/agents/noeva-etl-* e .claude/hooks/noeva-etl-*, scrive la voce dell'hook in .claude/settings.json e le regole del core nel blocco gestito di AGENTS.md. Quei file sono del core: si committano, non si modificano a mano, e un aggiornamento del core li riscrive. Il resto di .claude/ e di AGENTS.md è del cliente. Gli strumenti sono di due tipi:

• Skill — conoscenza e procedure che Claude carica quando servono, come si costruisce un grafo su questo framework con le sue regole. Quelle che guidano un'attività precisa, come lo scaffold di un processo, le invochi tu scrivendo /nome in Claude Code.
• Subagent — lavorano in un contesto separato e con strumenti limitati. Claude li usa da solo quando il compito corrisponde alla loro descrizione, oppure glieli chiedi per nome. Quasi tutti sono in sola lettura: rivedono, non modificano.

Accanto a loro il kit porta un hook, la guardia sui branch: blocca git commit e git push su dev, staging e main, perché si lavora sempre su un branch di attività con la sua PR.

I tre revisori hanno confini netti: graph-auditor guarda la struttura del grafo (e la qualità degli scopi dei nodi), etl-reviewer la correttezza del dato, schema-contract-auditor i contratti.

Cerca uno strumento

12 strumenti

• Skill
  /doc-sync

  Verifica che codice e documentazione siano allineati e segnala le derive

• Skill
  /etl-graph

  Costruisce, cabla e configura un grafo ETL sull'API pubblica di @noeva/etl-core — DSL graph(), gli undici tipi di nodo e il nodo pipeline delle sub-pipeline, porte e fan-out, edge di controllo (task,…

  Dettagli

  Costruisce, cabla e configura un grafo ETL sull'API pubblica di @noeva/etl-core — DSL graph(), gli undici tipi di nodo e il nodo pipeline delle sub-pipeline, porte e fan-out, edge di controllo (task, after), gestione errori (dead-letter, try/catch, fail-fast), scopo dei nodi (purpose), registrazione nel catalogo (etl.config.ts) e istanze connettore da variabili d'ambiente, metadati per la UI del DAG (descriptor, columns), version gate e i pattern dato (idempotenza, incrementale, streaming). Usare quando si progetta, implementa o rivede una pipeline, una sub-pipeline, un Source, un Sink o una Transform.

• Skill
  /etl-review

  Review specifica per pipeline dati — idempotenza, contratti, errori, performance

• Skill
  /new-connector <nome> [source|sink]

  Scaffold di un connettore (Source o Sink) verso un sistema reale, con contratto e test

• Skill
  /new-pipeline <nome-pipeline-kebab-case>

  Scaffold completo di una nuova pipeline ETL (schema, definizione, changelog, snapshot del piano, run, test, doc)

• Skill
  /new-transform <nome>

  Scaffold di una trasformazione ETL riusabile con test

• Subagentsola lettura
  doc-syncer

  Verifica l'allineamento tra codice e documentazione (schede di pipeline, sub-pipeline e connettori, ADR, .env.example, AGENTS.md, link) e segnala le derive.

  Dettagli

  Verifica l'allineamento tra codice e documentazione (schede di pipeline, sub-pipeline e connettori, ADR, .env.example, AGENTS.md, link) e segnala le derive. Usalo OBBLIGATORIAMENTE a fine lavoro ogni volta che una funzionalità è stata aggiunta, modificata o rimossa (pipeline, sub-pipeline, connettore, transform, variabile d'ambiente), e prima di una PR per garantire "doc e codice nello stesso commit". Read-only di default: applica correzioni solo se richiesto.

  Tool:ReadGrepGlobBash

• Subagentsola lettura
  etl-reviewer

  Esegue una review specifica ETL/dati sulle modifiche correnti (diff) in contesto isolato.

  Dettagli

  Esegue una review specifica ETL/dati sulle modifiche correnti (diff) in contesto isolato. Usalo PROATTIVAMENTE prima di aprire una PR o dopo aver completato una pipeline/connettore/transform, e ogni volta che serve un parere sulla correttezza dati senza saturare il contesto principale con diff lunghi. Read-only: non modifica file.

  Tool:ReadGrepGlobBash

• Subagentsola lettura
  graph-auditor

  Audita la struttura di un grafo ETL e il suo cablaggio: topologia (nodi, porte, guard, fan-out, task ed edge di controllo), registrazione nel catalogo (etl.config.ts), coerenza getSpec() ↔…

  Dettagli

  Audita la struttura di un grafo ETL e il suo cablaggio: topologia (nodi, porte, guard, fan-out, task ed edge di controllo), registrazione nel catalogo (etl.config.ts), coerenza getSpec() ↔ run(), metadati per la UI del DAG (descriptor, columns) e qualità degli scopi dei nodi (purpose). Usalo dopo aver scritto o modificato una pipeline a grafo, prima di una PR, o quando una pipeline "non si vede" in CLI/UI o il DAG mostrato non corrisponde a quello eseguito. Read-only: non modifica file.

  Tool:ReadGrepGlobBash

• Subagentscrive file
  graph-builder

  Scaffolda una pipeline a grafo completa e cablata: schema.ts (contratti Zod), pipeline.ts (DSL graph()), changelog.ts (la v1), run.ts (RunnablePipeline), registrazione nel catalogo…

  Dettagli

  Scaffolda una pipeline a grafo completa e cablata: schema.ts (contratti Zod), pipeline.ts (DSL graph()), changelog.ts (la v1), run.ts (RunnablePipeline), registrazione nel catalogo (etl.config.ts), snapshot del piano della v1, test colocati e scheda doc. Usalo quando la forma della pipeline è già decisa (sorgenti, destinazioni, regole, strategia di errore) e serve materializzarla secondo le convenzioni del repo cliente. SCRIVE file, solo dentro il perimetro dichiarato. Se una scelta di dominio non è specificata, si ferma e la chiede invece di inventarla.

  Tool:ReadGrepGlobEditWriteBash

• Subagentsola lettura
  schema-contract-auditor

  Audita i contratti dati del progetto: ogni Source/Sink/Pipeline deve avere uno schema Zod su input e output, e ogni record invalido un percorso esplicito (dead-letter o fail-fast), mai uno scarto…

  Dettagli

  Audita i contratti dati del progetto: ogni Source/Sink/Pipeline deve avere uno schema Zod su input e output, e ogni record invalido un percorso esplicito (dead-letter o fail-fast), mai uno scarto silenzioso. Usalo quando aggiungi o modifichi connettori, schema o pipeline e vuoi garantire la correttezza dati al confine. Read-only: non modifica file.

  Tool:ReadGrepGlobBash

• Subagentscrive file
  test-author

  Scrive o completa i test vitest per una Transform, Source, Sink o Pipeline secondo le regole del progetto (colocazione, casi di errore, dead-letter, metriche, test-first sui bug).

  Dettagli

  Scrive o completa i test vitest per una Transform, Source, Sink o Pipeline secondo le regole del progetto (colocazione, casi di errore, dead-letter, metriche, test-first sui bug). Usalo quando aggiungi/modifichi logica in src/ e mancano i test, o quando un bug fix richiede prima un test rosso. È l'unico agente che SCRIVE file (solo test).

  Tool:ReadGrepGlobEditWriteBash

Da dove viene questo catalogo

L'elenco è generato a ogni build della guida dai file del kit: uno strumento nuovo, o una descrizione cambiata, compare qui con la versione del core che lo porta.

Quale usare, quando

Momento	Strumento
Parti da un bisogno	/new-pipeline <nome>, con la skill etl-graph
La forma del processo è già decisa	il subagent graph-builder
Serve un sistema che non è ancora supportato	/new-connector <nome>
Serve una trasformazione riusabile	/new-transform <nome>
Mancano test, o un bug va riprodotto	il subagent test-author
Prima della Pull Request	/etl-review, graph-auditor, schema-contract-auditor
Hai aggiunto, cambiato o tolto una funzionalità	/doc-sync o il subagent doc-syncer