# SVG Skill - Guida manutenzione e sviluppi futuri

Versione: 2026-04-24
Stato: guida operativa per evoluzione di `skills/svg/`

Questa guida definisce come evolvere `skills/svg/SKILL.md`, le reference locali
e il catalogo helper senza perdere progressive disclosure, compatibilita' e
verificabilita'.

## 1) Principi

- `SKILL.md` resta il router operativo: trigger, scope, routing, decisioni brevi.
- I dettagli procedurali vivono in `skills/svg/references/`, in particolare
  nei workflow dedicati sotto `skills/svg/references/workflows/`.
- Gli helper in `skills/svg/tools/` sono execution helper deterministici, non un
  framework grafico generale.
- Ogni evoluzione deve aggiornare insieme documentazione, smoke/eval e catalogo
  quando cambia la superficie esposta all'agente.

## 2) Regole per `SKILL.md`

Mantieni `SKILL.md` sotto circa 150-200 righe quando possibile. Se una nuova
sezione supera 20-30 righe o contiene dettagli di retry, tassonomie, esempi
estesi o checklist, spostala in `references/` e lascia nel file principale solo:

- quando leggere la reference;
- che decisione prendere;
- quali output minimi produrre.

Non inserire in `SKILL.md`:

- cataloghi lunghi di parametri CLI;
- runbook completi di tool esterni;
- procedure host-specific estese;
- note storiche di milestone.

Inserisci in `SKILL.md` solo se cambia:

- trigger o boundary della skill;
- routing verso workflow esistenti o nuovi;
- obblighi trasversali che l'agente deve vedere subito;
- link a una nuova reference necessaria.

## 3) Quando creare una nuova reference

Crea un file in `skills/svg/references/` quando una procedura e':

- riusabile in piu' workflow;
- troppo dettagliata per il router principale;
- dipendente da host/runtime;
- utile solo in alcuni task.

Naming consigliato:

- `helper-first.md` per policy helper e discovery;
- `visual-qa.md` per browser/render/fallback;
- `<feature>-policy.md` per policy trasversali future;
- `<feature>-troubleshooting.md` per errori frequenti.

Ogni reference deve iniziare con una frase "Usa questa reference quando..." e
deve evitare requisiti impliciti non citati da `SKILL.md`.

## 4) Catalogo helper

`skills/svg/tools/catalog.json` e' il punto di discovery machine-readable per gli
agenti. Ogni helper esposto deve avere una voce nel catalogo.

Campi richiesti per ogni tool:

- `name`: nome stabile e breve;
- `script`: path repo-relative allo script;
- `use_when`: una frase decisionale, non marketing;
- `keywords`: sinonimi e parole del prompt che aiutano il matching;
- `example`: comando minimo eseguibile;
- `primary_output`: campi principali attesi in stdout/artifact.

Regole:

- non rinominare `name` o `script` senza motivazione e aggiornamento smoke;
- mantieni esempi copiabili;
- usa keyword in italiano e inglese quando il prompt reale puo' essere bilingue;
- se uno script diventa deprecato, aggiungi prima `deprecated: true` e
  `replacement`, poi rimuovilo solo in una milestone successiva.

## 5) Aggiunta di un nuovo helper

Checklist minima:

1. conferma che il caso sia deterministico, locale e a perimetro stretto;
2. aggiungi lo script in `skills/svg/tools/`;
3. aggiorna `skills/svg/tools/catalog.json`;
4. aggiorna `skills/svg/tools/README.md`;
5. aggiorna `skills/svg/references/helper-first.md` se cambia la policy o la
   mappa tool;
6. aggiungi smoke happy-path + input invalido;
7. aggiungi check di determinismo se l'output e' geometria/path critico;
8. aggiorna `skills/svg/evals/evals.json` se cambia un comportamento atteso
   della skill, non solo il catalogo tecnico.

Un helper non deve:

- chiamare servizi remoti;
- introdurre dipendenze pesanti senza razionale in roadmap;
- decidere stile, palette o composizione completa;
- sostituire validazione, QA o workflow skill.

## 6) Test minimi

Per modifiche a `SKILL.md`, reference o catalogo helper:

```bash
node -e "JSON.parse(require('fs').readFileSync('skills/svg/tools/catalog.json','utf8'))"
node scripts/check-tool-schemas.js
node scripts/smoke-svg-superellipse.js
node scripts/smoke-svg-phase3-helpers.js
node scripts/check-svg-skill-smoke.js --profile phase3
```

Se lo smoke usa child process Node e la sandbox blocca `spawnSync` con `EPERM`,
riesegui fuori sandbox prima di classificare il fallimento come regressione.

## 7) Documentazione da aggiornare

Aggiorna questa guida quando cambiano:

- struttura del catalogo helper;
- regole di progressive disclosure di `SKILL.md`;
- checklist per nuovi helper;
- smoke minimi obbligatori.

Aggiorna `docs/svg/svg-framework-roadmap.md` quando cambia il perimetro di fase
o quando un helper anticipa funzionalita' previste per Fase 4/5.

Aggiorna `docs/svg/svg-skill-node-scripts-analysis.md` quando cambia la decisione
architetturale sugli script locali, non per ogni piccolo helper aggiunto.