Skill Claude: dipendenze ricorsive o bundle portabili?

Le Agent Skills non dovrebbero essere considerate semplici cartelle di prompt. Appena una skill contiene istruzioni, script, template, riferimenti, policy e procedure operative, diventa un modulo software. E come ogni modulo software può avere dipendenze.

Il punto critico è questo: se una skill X dipende da una skill Y, e Y dipende da Z, il sistema agentico deve sapere come gestire quella catena. Altrimenti il rischio è che l'agente esegua una procedura incompleta, improvvisi una parte mancante o produca un output plausibile ma scorretto.

Il problema

Una skill può dipendere da tre categorie diverse di componenti:

1. altre skill
2. tool esterni
3. runtime o ambienti di esecuzione

Esempio:

audit-solidity
 ├── solidity-static-analysis
 ├── report-generator
 ├── forge
 ├── slither
 └── python>=3.11

Qui audit-solidity non è autonoma. Richiede altre skill, strumenti e runtime. Quindi non basta installare la cartella audit-solidity/: bisogna garantire che tutto ciò che serve sia presente, compatibile e autorizzato.

Opzione 1: dependency resolver

La prima soluzione è trattare le skill come pacchetti software con dipendenze esplicite. Ogni skill ha un manifest macchina, ad esempio skill.json, accanto a SKILL.md:

{
  "name": "audit-solidity",
  "version": "1.2.0",
  "dependencies": {
    "skills": [
      { "name": "solidity-static-analysis", "version": "^1.0.0" },
      { "name": "report-generator", "version": "^2.1.0" }
    ],
    "tools": ["forge", "slither", "solc"],
    "runtimes": ["python>=3.11"]
  },
  "capabilities": [
    "read-files",
    "write-files",
    "run-bash"
  ]
}

Il sistema deve leggere il manifest, costruire il grafo delle dipendenze e installare tutto in ordine corretto:

install(audit-solidity)
  → install(solidity-static-analysis)
  → install(report-generator)
  → check forge
  → check slither
  → check python>=3.11
  → register audit-solidity

Questo approccio richiede un'infrastruttura non banale:

Skill Registry
Dependency Resolver
Compatibility Checker
Capability Checker
Installer
Runtime Loader
Policy Engine

Vantaggi: aggiornamenti modulari, riuso delle skill comuni, minore duplicazione, modello elegante e scalabile, adatto ad ambienti di sviluppo.

Svantaggi: maggiore complessità, gestione dei conflitti di versione, rischio di dipendenze mancanti, necessità di un registry affidabile, installazione meno prevedibile. Il resolver deve inoltre rilevare cicli (A → B → C → A) e conflitti di versione (una skill richiede report-generator ^2.0.0, un'altra ^3.0.0).

Opzione 2: bundle portabile e autocontenuto

La seconda soluzione sposta la complessità dalla fase di installazione a quella di esportazione. Invece di installare X e poi risolvere ricorsivamente Y e Z, chi esporta X produce un bundle già completo:

audit-solidity.skillbundle/
├── bundle.json
├── lockfile.json
├── checksums.json
├── skills/
│   ├── audit-solidity/
│   ├── solidity-static-analysis/
│   └── report-generator/
├── assets/
├── policies/
└── tests/

Il file bundle.json dichiara cosa contiene e cosa resta esterno:

{
  "name": "audit-solidity-bundle",
  "version": "1.0.0",
  "root_skill": "audit-solidity",
  "contains": {
    "skills": [
      "audit-solidity@1.2.0",
      "solidity-static-analysis@1.0.4",
      "report-generator@2.1.3"
    ],
    "policies": [
      "audit-severity-policy@1.0.0"
    ],
    "assets": [
      "report-template-v3"
    ]
  },
  "requires_external": {
    "tools": ["forge", "slither", "solc"],
    "runtimes": ["python>=3.11"]
  }
}

Il lockfile.json blocca le versioni incluse; checksums.json permette di verificare che il bundle non sia stato modificato:

{
  "locked": [
    { "name": "audit-solidity", "version": "1.2.0", "hash": "sha256:..." },
    { "name": "report-generator", "version": "2.1.3", "hash": "sha256:..." }
  ]
}

Vantaggi: installazione prevedibile, riproducibilità, adatto ad ambienti enterprise o offline, minore dipendenza da registry remoti, meno rischio di skill mancanti al runtime.

Svantaggi: bundle più pesanti, duplicazione di skill comuni, aggiornamenti meno granulari, rischio di copie divergenti. Il bundle non deve includere runtime pesanti come Python, Docker o Foundry: può dichiararli come requisiti esterni. Ma dovrebbe includere tutte le dipendenze logiche tra skill.

Il modello migliore: ibrido

La soluzione più robusta usa entrambi i modelli in momenti diversi:

Sviluppo:    dependency resolver
Distribuzione: portable bundle
Esecuzione:  policy engine + capability checker

In sviluppo ha senso un registry che risolve le dipendenze in modo modulare: aggiornare skill comuni, testare versioni diverse, comporre workflow complessi. In produzione conviene esportare bundle portabili, versionati, verificabili e riproducibili. La regola è semplice:

Resolver per costruire.
Bundle per distribuire.
Policy engine per eseguire.

Conclusione

Le skill portano modularità nel mondo degli agenti AI. Ma la modularità senza gestione delle dipendenze diventa fragilità. Una piattaforma agentica matura deve scegliere una strategia chiara: risolvere ricorsivamente le dipendenze, esportare bundle autocontenuti, o combinare entrambi gli approcci. La prima opzione è più adatta allo sviluppo, la seconda alla produzione, la terza è il modello più solido.

Una skill non dovrebbe essere solo una cartella di prompt. Dovrebbe essere un pacchetto operativo per agenti: dichiarativo, versionato, verificabile, testabile e governabile.