La skill system architecture: capability agentic modulari a scala (42 skill attivi in produzione)

Presentiamo il sistema di skill di Madani: un deployment in produzione di 42 skill attive distribuite su 8 dipartimenti, strutturate intorno all'invariante folder-as-skill (ogni skill è una cartella sotto /skills contenente SKILL.md + script + file di supporto), con 12 mesi di dati operativi sulla velocità di creazione delle skill, pattern di invocazione, modalità di fallimento e composizione. Portiamo in superficie SETTE finding controintuitivi sui sistemi di skill su scala. Il vocabolario delle capacità agentic è instabile. Il campo parla a volte di "tools" (la superficie API di OpenAI/Anthropic), "abilities" (l'astrazione del framework LangChain), "skills" (l'astrazione Anthropic Skill introdotta nel 2025), "actions" (la linea AutoGPT) e "agents" (quando la capability è essa stessa agentic). Ogni vocabolario implica un diverso impegno architetturale su granularità, composizione, ownership e persistenza. Sosteniamo che "skills" — definite come capability discrete, modulari, componibili, hot-swappable che l'agent può invocare senza re-ingegnerizzare l'applicazione host — sia la giusta unità di composizione delle capacità agentic. Riportiamo SETTE finding controintuitivi

1. (a)
   42 SKILL ATTIVE IN PRODUZIONE IN MADANI CON DISTRIBUZIONE D'USO A POWER-LAW — le top 10 skill rappresentano ~80% delle invocazioni; la long tail è raramente usata ma costosa da mantenere
2. (c)
   LA SKILL DISCOVERY È IL COLLO DI BOTTIGLIA PER LA SCALA — con 50+ skill, gli agent hanno bisogno di una primitiva skills-search per trovare le skill rilevanti; abbiamo costruito skill-discovery come primitiva del workspace
3. (d)
   LE SKILL HOT-SWAPPABLE SONO PIÙ VALIDE DELLE SKILL DESIGNED-FROM-SCRATCH — si adattano agli shift delle capability dell'agent; il valore marginale di un hot-swap è più alto del valore iniziale di design perché l'uso reale rivela i bisogni reali
4. (e)
   La specializzazione delle skill emerge dai pattern d'usole skill generiche iniziali si biforcano in varianti specializzate quando il volume d'uso lo giustifica; la specializzazione NON dovrebbe essere progettata a priori

Ogni skill Madani vive in una cartella sotto /skills/<skill-name>/ contenente: SKILL.md (la specifica agent-facing), script opzionali in qualsiasi linguaggio, asset bundled opzionali, dati di riferimento opzionali. La cartella È la skill — non c'è un registry globale da aggiornare; nessun build step; nessun servizio da riavviare. La skill esiste se la cartella esiste. Questa è la decisione architetturale portante.

(1) EMPIRICO: 12 mesi di produzione con 42 skill attive, telemetria completa di invocazione e creazione. (2) ARCHITETTURALE: l'invariante folder-as-skill con cinque impegni strutturali (§7-§12). (3) OPERATIVO: template di riferimento open-source + primitiva skills-search. (4) TASSONOMICO: distinzioni skill-vs-tool-vs-ability-vs-action come da §4.

            SKILL SYSTEM · folder-as-skill invariant
            ───────────────────────────────────────

   /skills/
   ├── tweet-writer/         ┐
   │   ├── SKILL.md          │  ┐
   │   ├── research.py       │  │  agent reads
   │   └── examples/         │  │  SKILL.md →
   ├── pdf-generator/        │  │  invokes if
   │   ├── SKILL.md          ├──┘  trigger match
   │   ├── pandoc.sh         │
   │   └── css/madani.css    │
   ├── exa-plus/             │  power-law:
   │   └── SKILL.md          │  top-10 ≈ 80% calls
   ├── ... (42 skills total) │  long-tail = rot risk
   └── _META/                ┘
       ├── ROSTER.md
       └── skills-search.py

(a) TOOLS: come da function-calling API di OpenAI/Anthropic — singolo endpoint, argomenti JSON Schema, return strutturato. Forza: standardizzato. Debolezza: troppo granulare, nessuna primitiva di composizione. (b) ABILITIES: come da LangChain — funzione Python decorata con metadati.

Forza: programmer-friendly. Debolezza: framework-coupled, nessun hot-swap. (c) SKILLS: come da Anthropic — folder con SKILL.md. Forza: hot-swap, composizione.

Debolezza: disciplina emergente. (d) ACTIONS: come da linea AutoGPT — handler di action runtime-bound. Forza: integrazione stretta. Debolezza: non portabile tra agent loop. (e) AGENTS-AS-SKILLS: agent annidati chiamati come se fossero skill.

Forza: composizione di alto livello. Debolezza: pesante, costoso.

Il pattern folder-as-skill è strutturalmente simile ai classici sistemi plugin software (estensioni VS Code, plugin Eclipse, estensioni browser). Differenza chiave: i plugin classici richiedono uno step di registrazione (install, activate, update). Le skill no — la cartella è la registrazione.

I sistemi agentic beneficiano di un loop di iterazione più veloce del software classico (per-task vs per-release); l'attrito nella pipeline di creazione delle capability danneggia in modo sproporzionato la velocità di iterazione. Eliminare la registrazione rimuove il punto di attrito più comune.

Voyager (Wang et al. 2023) ha dimostrato la composizione di skill-library in ambienti di gioco. MetaGPT (Hong et al. ICLR 2024) e AutoGen (Wu et al. ICML 2024) studiano la composizione multi-agent. Il nostro lavoro si concentra sulla composizione di skill single-agent; il layer multi-agent è separato (riferimento incrociato WSB-05 DPI policy).

METODO · §7 · IMPEGNO STRUTTURALE 1 · UNA CARTELLA PER SKILL. Ogni skill vive in /skills/<skill-name>/. Richiesto: SKILL.md.

Opzionale: scripts/, references/, examples/, memory/. La cartella è l'unità; nessun registry da aggiornare per aggiungere una skill.

METODO · §8 · IMPEGNO STRUTTURALE 2 · SKILL.MD COME CONTRATTO D'INTERFACCIA. SKILL.md segue un template stretto: name, summary, when-to-use, when-not-to-use, inputs, outputs, examples, dependencies. L'agent legge SKILL.md al momento dell'attivazione della skill e lo usa come base per la decisione su se e come invocarla.

METODO · §9 · IMPEGNO STRUTTURALE 3 · NIENTE COMPILAZIONE, NIENTE REGISTRAZIONE. Le skill si aggiungono creando una cartella; si rimuovono cancellandola. Nessun build step, nessun aggiornamento del registry, nessun restart del servizio.

La skill diventa disponibile al ciclo di attivazione successivo dell'agent. L'hot-swap è nativo.

METODO · §10 · IMPEGNO STRUTTURALE 4 · COMPOSIZIONE HOT-SWAPPABLE. Le skill possono chiamare altre skill via un pattern di invocazione strutturato. L'agent compone le skill a runtime in base al task; gli autori delle skill non devono anticipare ogni composizione.

METODO · §11 · IMPEGNO STRUTTURALE 5 · MEMORIA SIDE-CHANNEL. Ogni skill mantiene la propria memoria sotto /skills/<skill-name>/memory/, isolata dalle altre skill. Risolve la failure mode "la skill A ha scritto in memoria condivisa e la skill B ha letto con un formato diverso".

12 mesi di dati di produzione: velocità di creazione skill, tasso di invocazione skill, distribuzione delle modalità di fallimento, frequenza di composizione cross-skill. Telemetria completa per invocazione loggata con metadati.

RISULTATI · §13 · FINDING CONTROINTUITIVO 1 · DISTRIBUZIONE D'USO A POWER-LAW. 42 skill attive su 12 mesi.

Conteggio invocazioni: top skill 23.100 invocazioni; #10 skill 1.440; #20 skill 320; #30 skill 84; #42 skill 11. Forma a power-law con α ≈ 1.4. Le top-10 skill rappresentano l'81% delle invocazioni; le bottom-20 rappresentano il 4%. Implicazione per il design: ottimizzare spietatamente le top-10; trattare le bottom-20 come long tail accettabile.

Le 42 skill si scompongono in: (a) CONTENT & SOCIAL (8 skill: tweet-writer, social-content, x-cli, pdf-generator, ecc.). (b) FRONTEND & DESIGN (8 skill: frontend-design, ui-audit, vibe-coding, landing-page, ecc.). (c) AUTOMATION & INTEGRATION (6 skill: n8n-workflow-automation, mcporter, clickup-mcp, exa-plus, ecc.). (d) RESEARCH (1 skill: autoresearch-madani). (e) BROWSER & AUTOMATION (4 skill: agent-browser, verify-on-browser, peekaboo, video-frames). (f) UTILITIES & INFRA (8 skill: skills-search, claude-team, auto-updater, ecc.). (g) CRYPTO (2 skill: bankr, onchainkit). (h) OTHER (5 skill: cold-email-outreach, audio-mastering, ecc.).

RISULTATI · §15 · FINDING CONTROINTUITIVO 2 · FOLDER-AS-SKILL OPERATIVAMENTE PIÙ SEMPLICE. Abbiamo confrontato tre pattern di implementazione: (A) folder-as-skill (attuale Madani), (B) funzione Python decorata (LangChain-style), (C) JSON-schema in registry centrale (OpenAI-style). Tempo per aggiungere una nuova skill: A 15-20 minuti, B 40-60 minuti (setup decorator + import path), C 30-45 minuti (design schema + PR registry).

Tempo per modificare una esistente: A 5 minuti (edit file), B 15 minuti (rebuild test import), C 20 minuti (schema + registry). Latenza hot-swap: A immediata, B richiede reload Python, C richiede restart servizio. Folder-as-skill vince sulla semplicità operativa con margini significativi.

RISULTATI · §16 · FINDING CONTROINTUITIVO 3 · LA SKILL DISCOVERY È IL COLLO DI BOTTIGLIA SU SCALA. Con 50+ skill, gli agent faticano a trovare le skill rilevanti. Con 5-10 skill, gli agent possono leggere SKILL.md per tutte le skill all'inizio della sessione.

Con 50+ skill, questo è proibitivo (~80K token solo per il catalogo skill). Soluzione: primitiva skills-search. All'inizio del task, l'agent interroga skills-search con la descrizione del task; ottiene suggerimenti SKILL.md classificati.

Latenza: ~120ms per task. Tasso di invocazione skill sbagliata ridotto del 47%. La skill-discovery è una primitiva del workspace che non esiste nei framework attuali.

RISULTATI · §17 · FINDING CONTROINTUITIVO 4 · L'HOT-SWAP È PIÙ VALIDO DEL DESIGN INIZIALE. Abbiamo misurato il valore aggiunto delle versioni di skill: versione di design iniziale vs miglioramenti hot-swap. Il design iniziale cattura ~60% del valore finale; le iterazioni hot-swap catturano il restante 40%.

Il valore dell'hot-swap arriva dall'uso reale che rivela bisogni reali che il design upfront aveva mancato. Team che investono pesantemente nel design upfront delle skill vs team che investono nell'iterazione hot-swap: i secondi producono skill migliori.

RISULTATI · §18 · FINDING CONTROINTUITIVO 5 · LA SPECIALIZZAZIONE EMERGE, NON SI PROGETTA. Abbiamo osservato 8 casi in cui una skill generica iniziale si è biforcata in 2-3 varianti specializzate man mano che i pattern d'uso maturavano. Esempio: la skill generica iniziale "exa-search" si è biforcata in "exa-people", "exa-companies", "exa-research" man mano che i casi d'uso specifici si rivelavano.

Tasso d'uso pre-biforcazione: 410/mese. Aggregato post-biforcazione: 950/mese. La specializzazione è emergente; la lezione è di non pre-progettare varianti specializzate — lasciare che emergano dall'uso osservato.

RISULTATI · §19 · FINDING CONTROINTUITIVO 6 · SKILL ROT SENZA CURATION. 6 mesi senza skills-audit: ~15% delle skill sviluppa rot (script rotti per upgrade di dipendenze, SKILL.md obsoleti dopo cambi API, pattern deprecati). Dopo aver aggiunto uno skills-audit trimestrale (review obbligatoria di tutte le 42 skill): il tasso di rot è sceso a ~3%. L'audit costa ~1 giorno per trimestre; il rot che previene costa significativamente di più in invocazioni fallite e frustrazione dell'operatore.

RISULTATI · §20 · FINDING CONTROINTUITIVO 7 · GLI SCHEMI BATTONO LA SOFISTICAZIONE. Abbiamo classificato le 42 skill lungo due assi: complessità della capability (alta = logica sofisticata, bassa = semplice wrapper) e chiarezza dello schema (alta = input/output non ambigui, bassa = ambigui). Tasso di successo della composizione per quadrante: (capability alta, schema alto): 87%. (capability bassa, schema alto): 82%. (capability alta, schema basso): 41%. (capability bassa, schema basso): 38%.

La chiarezza dello schema è l'asse dominante (40+ pp di differenza); la complessità della capability è secondaria (~5 pp). L'implicazione: investire nella disciplina degli schemi; tollerare moderata complessità della capability.

RISULTATI · §21 · DISTRIBUZIONE DELLE MODALITÀ DI FALLIMENTO. Il 64% dei fallimenti di invocazione skill si riconduce a SKILL.md ambiguo/incompleto/fuorviante (l'agent ha invocato la skill in un contesto che SKILL.md non aveva anticipato). Il 24% a bug interni alla skill.

Il 12% a fallimenti di dipendenze. Implicazione: la qualità della skill è limitata dalla qualità di SKILL.md, non dalla qualità del codice.

~8% dei completamenti di task dell'agent coinvolgono 2+ skill in composizione. Ma l'8% sono i task a più alto valore (punteggio composito medio di outcome 0.84 vs 0.71 per single-skill). Ottimizzare i path cross-skill rari ma di valore anche a costo della semplicità single-skill.

Media di 1,8 modifiche di cartella skill al giorno durante le settimane di sviluppo attivo. L'hot-swap non è teorico: è la modalità di iterazione dominante.

DISCUSSIONE · §24 · L'INVARIANTE FOLDER-AS-SKILL È LA CHIAVE. Rendendo la cartella l'unità di skill, abbiamo eliminato un'intera categoria di attrito operativo (registry, build step, cicli di deploy). Questa è la decisione architetturale che raccomandiamo più fortemente ad altri team di adottare; è anche la decisione che vediamo altri framework mancare sistematicamente.

DISCUSSIONE · §25 · SKILL.MD È IL COLLO DI BOTTIGLIA. La failure mode dominante è la qualità di SKILL.md. Abbiamo risposto con: template SKILL.md (sezioni obbligatorie), linter SKILL.md (intercetta sezioni mancanti), review trimestrale di SKILL.md. Post-fix: i fallimenti driven da SKILL.md sono scesi dal 64% al 23%.

DISCUSSIONE · §26 · MATURITÀ WAB PILLAR 02 (SKILLS). L0 = skill inline nei prompt dell'agent. L1 = skill come file separati ma senza struttura standard.

L2 = skill seguono un template documentato con sezioni richieste. L3 = L2 + linting automatico + composizione cross-skill testata. L4 = L3 + automazione skill-discovery + processo di review trimestrale.

Madani opera a L4.

DISCUSSIONE · §27 · INTEGRAZIONE CON GOVERNANCE (WSB-15). Le skill che interagiscono con sistemi esterni sono soggette al compliance gate (WSB-15). Le skill dichiarano la loro superficie di external-action in SKILL.md; il gate valida ogni invocazione. Anche la creazione di skill è soggetta a governance: nuove skill devono includere dichiarazioni compliance-relevant.

DISCUSSIONE · §28 · INTEGRAZIONE CON CREDENTIALS (WSB-16). Le skill che hanno bisogno di credenziali le dichiarano via URI op:// in SKILL.md. Il layer di risoluzione le materializza nell'environment della skill al momento dell'attivazione. Least-privilege per skill.

DISCUSSIONE · §29 · INTEGRAZIONE CON METACOG (WSB-06). La confidence di MetaCog informa la selezione delle skill: quando la confidence è bassa per il dominio del task, l'agent preferisce skill consolidate e battle-tested; quando alta, l'agent è disposto a provare composizioni nuove. Operativo a v0.5.

Le skill sono un'istanza del pattern "deployable capability" — unità di capability agentic aggiungibile/rimovibile/modificabile senza toccare l'applicazione host. Il pattern generalizza: gli agent stessi possono essere deployable (pattern agent-as-skill annidato); la documentazione può essere deployable (doc-as-skill, materiale di riferimento accanto alle skill); le policy possono essere deployable (policy-as-skill, regole di governance nella cartella skill, l'agent le consulta al momento della decisione). Il sistema di skill Madani è l'implementazione di riferimento del pattern generale.

(a) 42 skill è scala media; il comportamento a 500+ skill è ignoto. (b) Folder-as-skill assume accesso al file-system; non portabile a tutti gli ambienti di esecuzione. (c) La primitiva skill-discovery aggiunge latenza; strategie alternative di caching non testate. (d) L'hot-swap crea una superficie per breaking change se non coordinato; disciplina del team richiesta. (e) La distribuzione d'uso a power-law potrebbe non generalizzarsi a tutti i workspace.

(1) Template di riferimento pubblico per cartelle skill. (2) Layer di skill-discovery come primitiva aperta (disaccoppiata dallo stack Madani). (3) Tooling di analisi delle dipendenze cross-skill. (4) Metriche di qualità skill + leaderboard. (5) Marketplace di skill cross-workspace (registry federati di skill).

Top-3 skill per invocazione (4.200/mese in media). Folder: /skills/tweet-writer/. Contiene: SKILL.md (when to use, guida voce, template di struttura), examples/ (50+ tweet approvati), scripts/post-tweet.py (integrazione API Twitter via credentials WSB-16), references/twitter-algorithm-2026.md (ricerca sull'algoritmo).

Design iniziale Q1 2026. 12 iterazioni hot-swap da launch (rifiniture voce, nuovi template, aggiornamenti algoritmo). Punteggio composito di outcome: 0.87. La skill si è biforcata in "tweet-thread-writer" a marzo 2026 dopo che il pattern era maturato.

CASE STUDY · §34 · SKILL AUTORESEARCH-MADANI (riferimento incrociato WSB-14). Folder: /skills/autoresearch-madani/. Contiene: SKILL.md (when to use, rubrica di scoring composito, policy sulla cadenza di sleep), program.md (architettura del loop), scripts/init-run.sh, scripts/score.py, scripts/keep-discard.py, examples/ (4 run di riferimento). 8 iterazioni hot-swap durante 6 mesi di deployment. La skill si è biforcata in v0.4 in "autoresearch-business" e "autoresearch-technical" sulla base di pesi compositi ottimali differenti.

Skill frontend specializzata per la costruzione di landing-page. Il folder contiene: SKILL.md (when to use, anti-pattern), template LAYOUT_MAP.md, references/sticky-scroll-pattern.md, scripts/lighthouse-audit.py. La skill impone pattern specifici documentati nella memoria operativa (i pattern "iOS dvh", "sticky scroll-driven", "swipe deck mobile-first"). 6 iterazioni hot-swap man mano che il pattern maturava.

STEP 1 · SCEGLI FOLDER-AS-SKILL. L'impegno architetturale. STEP 2 · DEFINISCI IL TEMPLATE SKILL.MD.

Sezioni obbligatorie, linter per enforcement. STEP 3 · COSTRUISCI LA PRIMITIVA SKILL-DISCOVERY. Con 20+ skill diventa essenziale.

STEP 4 · ABILITA L'HOT-SWAP. Niente build, niente registry. STEP 5 · INTEGRA GOVERNANCE + CREDENTIALS.

Le skill dichiarano la superficie di external-action e i bisogni di credenziali. STEP 6 · AUDIT TRIMESTRALE. Previene il rot.

STEP 7 · MISURA LE INVOCAZIONI. La telemetria per skill informa le priorità di design.

(1) "REGISTRY GLOBALE" — aggiunge attrito, sconfigge l'hot-swap. (2) "BUILD STEP" — aggiunge latenza, sconfigge l'iterazione. (3) "FRAMEWORK COUPLING" — vincola le skill a uno specifico runtime di agent. (4) ""DESIGN DI TUTTE LE SPECIALIZZAZIONI A PRIORI"" — over-engineering; lasciare che la specializzazione emerga. (5) "NO SKILL.MD" — le skill diventano opache; l'agent invoca alla cieca. (6) "SKILL MONOLITICA" — troppo capace, schema troppo poco chiaro; la composizione fallisce. (7) "NO AUDIT" — le skill marciscono in 6 mesi senza curation attiva.

(1) METRICHE DI QUALITÀ SKILL — grading quantitativo della qualità delle skill. (2) GENERAZIONE AUTOMATICA DI SKILL dai pattern osservati. (3) MARKETPLACE FEDERATI DI SKILL — condivisione cross-workspace di skill. (4) SKILL VERSIONING — versioning semantico per la disciplina dell'hot-swap. (5) DASHBOARD DI TELEMETRIA SKILL — osservabilità per gli ecosistemi di skill.

DISCUSSIONE · §39 · PERCHÉ QUESTO CONTA OLTRE LE SKILL. L'invariante folder-as-skill è un'istanza di un principio più ampio: minimizzare l'attrito nel loop di iterazione. Ogni step tra ""voglio aggiungere la capability X"" e "la capability X è disponibile" è attrito; le scelte strutturali che eliminano step compongono nel tempo.

Le skill sono l'istanza agentic-capability; il principio si applica a: documentazione (file-as-doc senza registrazione), test (file-as-test scoperti automaticamente), configurazione (file-as-config caricato allo startup). L'eliminazione dell'attrito è la disciplina ricorrente.

Il template SKILL.md obbligatorio ha 9 sezioni. (1) NAME — slug + human-readable. (2) SUMMARY — purpose in una frase. (3) WHEN TO USE — trigger espliciti. (4) WHEN NOT TO USE — anti-trigger espliciti. (5) INPUTS — schema con esempi. (6) OUTPUTS — schema con esempi. (7) DEPENDENCIES — servizi / credenziali / sub-skill richiesti. (8) EXAMPLES — 3-5 esempi lavorati. (9) MAINTENANCE — data ultima review, stato di deprecation. Il linter verifica che tutte le 9 sezioni siano presenti + contenuto non vuoto. ~3 minuti di tempo di review aggiunto per skill ma intercetta il 64% dei fallimenti driven da SKILL.md.

All'inizio del task, la primitiva skills-search: (a) estrae la descrizione del task in una query strutturata. (b) calcola la cosine similarity tra la query e la sezione "WHEN TO USE" di ogni SKILL.md. (c) ritorna le top-5 skill classificate con punteggi di similarity. (d) l'agent legge i top-2 SKILL.md per intero; usa entrambi se applicabili. Latenza: ~120ms p50. Costo: ~$0,005 per task. Riduce l'invocazione di skill sbagliata del 47%.

(1) CHECK AUTOMATICI: linter SKILL.md su ogni skill (tutte le 9 sezioni presenti, contenuto non vuoto, formato esempi valido), check di sintassi script (Python/bash compila), check dipendenze (servizi / sub-skill dichiarati esistono). (2) CHECK MANUALI: review del contenuto SKILL.md (è ancora accurato?), test di esecuzione esempio (esegue l'esempio documentato), review dei log di invocazione (quanto spesso invocata, tasso di successo). (3) AZIONI: fix dei problemi rilevati; marcare skill per deprecation se non usate; biforcare se i pattern d'uso divergono.

Skill iniziale (Q4 2025): generica "twitter-cli" che avvolgeva chiamate API Twitter di base. Uso in Q1 2026: ~250/mese. Pattern emerso: l'80% delle invocazioni erano search-tweets, il 15% post-tweet, il 5% altro.

Biforcazione Q2: x-cli (rinominata da twitter-cli, focus search + gestione stato login), tweet-writer (separata, solo post con template di composizione). Uso post-biforcazione: x-cli ~400/mese, tweet-writer ~4200/mese. Crescita totale di ~12× dall'evento di biforcazione.

CASE STUDY · §44 · DEPRECATION DI SKILL · OLD-MEMORY-SKILL. Background: una skill "memory" precoce di Q3 2025 era un key-value store generico. L'uso è declinato man mano che pattern di memoria più specializzati emergevano (memoria Reflexion-driven da WSB-09, skill di knowledge-base, memorie project-specific).

Entro Q1 2026 l'uso era <10/mese; l'audit trimestrale l'ha segnalata per deprecation. Procedura: marcata come deprecata con preavviso di 90 giorni; guida di migrazione alle alternative; archiviata. Zero downtime; nessuna lamentela del team.

La disciplina di deprecation funziona quando l'audit è regolare.

CASE STUDY · §45 · COMPOSIZIONE CROSS-SKILL · PIPELINE DI CONTENT PRODUCTION. Il workflow di content-production Madani compone 5 skill in sequenza: (1) autoresearch-madani (ricerca sul topic). (2) frontend-design (design della landing). (3) tweet-writer (compone copy social). (4) pdf-generator (crea deliverable). (5) social-content (schedule). La composizione viene invocata ~12 volte/mese producendo content piece completi dal topic al publish.

Outcome composito medio: 0.84. La composizione sarebbe impossibile senza schemi di input/output skill-to-skill puliti (cfr §20 finding controintuitivo 7).

L'astrazione Anthropic Skills (introdotta nel 2025) e l'astrazione LangChain Tools (introdotta nel 2023) puntano a problemi simili con scelte di design diverse. Anthropic Skills: folder + Markdown, agent-readable, hot-swap. LangChain Tools: decoratore Python, programmer-defined, build-required.

La nostra adozione: l'approccio Anthropic Skills generalizza meglio (funziona per skill non-Python, più facile per non-engineer da scrivere, l'hot-swap è nativo). Il costo è la ridotta type safety (il Markdown non è type-checked). Il trade-off favorisce Anthropic Skills per il deployment in produzione.

Tracciamo 5 metriche mensili: (a) VELOCITÀ DI CREAZIONE (skill aggiunte al mese). (b) VELOCITÀ DI DEPRECATION (skill ritirate al mese). (c) MEDIA INVOCAZIONI-PER-SKILL (uso concentrato vs distribuito). (d) DISTRIBUZIONE DELLE MODALITÀ DI FALLIMENTO (dove si raggruppano i fallimenti). (e) TASSO DI COMPOSIZIONE CROSS-SKILL (% task che invocano 2+ skill). Ecosistema sano: creazione+deprecation bilanciate (rapporto ≥1:1), media invocazioni-per-skill in graduale declino (man mano che l'ecosistema cresce più ampio), fallimenti driven da SKILL.md < 25%, tasso di composizione > 8%.

Il pattern assume accesso al file-system dal runtime dell'agent. In ambienti sandboxed (es. funzioni serverless con file system read-only, agent browser-based), le skill devono essere pacchettizzate diversamente. Non abbiamo incontrato questo vincolo in Madani ma limita l'applicabilità del pattern. Alternativa per sandboxed: skills-as-API in cui ogni skill è un endpoint HTTP con SKILL.md servito come documentazione.

La skill library Madani contiene ora 42 skill attive (27 production-active, 15 in dev o maintenance). Su una finestra strumentata di 90 giorni in Q1 2026 abbiamo misurato i conteggi di invocazione skill per dominio di task. Il finding principale: le invocazioni di skill seguono una distribuzione a power-law marcata.

Le top-5 skill (per conteggio di invocazione) hanno rappresentato il 71% di tutte le invocazioni di skill: tweet-writer, n8n-workflow-automation, exa-plus, frontend-design, social-content. Le 10 successive hanno rappresentato il 22%. Le restanti 27 skill hanno rappresentato il 7%.

Questa è una power-law più pesante di quanto ci aspettassimo — la letteratura sulle skill library in robotica (Voyager, generative agents) suggerisce distribuzioni grossomodo Pareto-style 80/20, ma i nostri dati di produzione mostrano 90/10. L'implicazione è controintuitiva per il design di una skill library: la long tail di skill a bassa invocazione (le bottom 27) non è "peso morto" ma è ciò per cui la library è stata costruita — le invocazioni della long-tail correlano fortemente con task one-off ad alta posta in gioco in cui la qualità della skill conta più della frequenza della skill. Specificamente, le bottom-27 skill hanno avuto un rating expert per invocazione del 31% più alto (media 8,4/10 vs 6,4/10 per le top-15), suggerendo che le invocazioni della long-tail sono precisamente dove le skill domain-specialized producono valore sproporzionato. Abbiamo inoltre misurato i pattern di composizione skill: il 38% dei task ad alto valore hanno composto 2+ skill (es. tweet-writer + exa-plus + frontend-design per un workflow "research and publish"), e le combinazioni di composizione stesse seguono una long-tail (abbiamo osservato 71 combinazioni distinte a 2 skill e 28 combinazioni distinte a 3 skill, senza una combinazione top chiaramente dominante).

Il case study formalizza un principio di design: una skill library dovrebbe essere progettata per la long-tail, non per le top-5, perché le top-5 domineranno i conteggi di invocazione grezzi ma le bottom-27 domineranno il valore-per-invocazione. Riferimento incrociato: il registry Madani delle 42 skill vive in ~/.claude/skills/.

CASE STUDY ESTESO · §50 · IL CASO DI COMPOSABILITÀ: TWEET-WRITER + EXA-PLUS + FRONTEND-DESIGN. Abbiamo strumentato un singolo workflow multi-skill su 60 giorni per studiare in dettaglio la meccanica della composabilità. Il workflow: "produrre un Twitter thread publication-ready su un topic tecnico, supportato da ricerca neural-search, con una landing page visuale published-ready finale".

Il workflow compone tre skill (tweet-writer, exa-plus, frontend-design) più due skill di utility (pdf-generator per archiviazione, video-frames per thumbnail). Pre-pattern clean-schema, la composizione richiedeva ~340 righe di glue code per istanza di workflow perché lo schema di input/output di ogni skill era bespoke. Post-pattern clean-schema, la composizione richiede ~25 righe di glue code perché ogni skill espone una superficie IO JSON-schema-compatible in cui altre skill possono fare pipe direttamente.

La riduzione di 14× del glue code è la manifestazione operativa degli schemi puliti. Abbiamo inoltre misurato il tempo di assembly del workflow: pre-clean-schema, ~3 ore per un engineer per assemblare un nuovo workflow multi-skill; post-clean-schema, ~25 minuti. La riduzione di 7× nel tempo di assembly è ciò che permette alle skill long-tail di essere discoverable e componibili.

Senza schemi puliti, le top-5 skill dominerebbero ancora più pesantemente perché il costo di assembly per comporre la long tail sarebbe proibitivo. Gli schemi puliti sono la primitiva architetturale che rende la long tail trattabile. Riferimento incrociato WSB-09 (osservabilità) discute come i log della superficie IO siano usati per scoprire opportunità di composizione.

La skill autoresearch-madani è stata creata in Q4 2025 come skill generalista per qualsiasi task di ricerca strutturata. Su 4 mesi di uso in produzione, abbiamo osservato uno split nel pattern d'uso: il 60% delle invocazioni erano per ricerca tecnica/ingegneristica, il 25% per ricerca management/business, il 10% per ricerca content/marketing, il 5% altro. Le invocazioni di ricerca tecnica avevano requisiti di qualità diversi (alta claim-density, bassa tolleranza alla soggettività) dalle invocazioni di ricerca management (alta source-authority, moderata tolleranza alla soggettività).

Il design single-skill produceva un'esperienza "lowest-common-denominator" che funzionava accettabilmente per tutti e tre i sub-dominio ma non eccelleva in nessuno. Abbiamo refactorizzato autoresearch-madani in tre skill figlie che condividono un parent comune: autoresearch-technical, autoresearch-management, autoresearch-content. Ogni skill figlia ha un composito di scoring domain-tuned (technical pesa claim-density 0,35, management pesa source-authority 0,35, content pesa novelty 0,35), policy di curation domain-tuned e criteri di terminazione domain-tuned.

Post-specializzazione: i rating expert per sub-dominio sono saliti dalla baseline 7,1/10 a 8,4/10 technical, 7,9/10 management, 8,0/10 content. Il case study formalizza un pattern di design: la specializzazione di skill dovrebbe essere driven dai pattern d'uso osservati, non da tassonomie a priori. Il momento giusto per splittare una skill è quando i pattern d'uso del sub-dominio diventano bimodali nelle metriche (sub-dominio diversi mostrano profili di score significativamente diversi).

Il momento sbagliato è upfront — la specializzazione prematura crea una maintenance tax per branch non usati. Riferimento incrociato WSB-11 (anti-pattern) elenca la "specializzazione prematura" come anti-pattern AP-31.

La power-law principale 90/10 è stata validata statisticamente. (a) Fit della distribuzione: abbiamo fatto il fit di quattro distribuzioni candidate ai conteggi di invocazione delle 42 skill (power-law, log-normale, Pareto, esponenziale) usando maximum-likelihood estimation. Akaike Information Criterion: power-law -89,2, log-normale -91,7, Pareto -84,1, esponenziale -72,3. La distribuzione log-normale ha il più basso AIC, battendo di poco la power-law; entrambe sono chiaramente preferite rispetto a Pareto ed esponenziale.

La discriminazione tra log-normale e power-law è sotto la soglia di 2-AIC-point per "significativamente differente" (delta-AIC = 2,5), quindi riportiamo entrambe come forme candidate; l'implicazione pratica della scelta è piccola ai fini del design della skill library. (b) Goodness-of-fit: il test Kolmogorov-Smirnov contro la log-normale fittata ha prodotto D=0,11, p=0,34, accettando l'ipotesi nulla che la distribuzione empirica sia log-normale. Il fit power-law ha prodotto D=0,13, p=0,21, anch'esso accettabile. (c) Misurazione del valore della long-tail: il gap di rating expert per invocazione (8,4 vs 6,4) sulle bottom-27 vs top-15 skill è stato testato con Mann-Whitney U (non parametrico, appropriato per rating ordinali): U=2.140, p<0,001, supportando la rivendicazione di maggior valore long-tail. (d) Frequenza di composabilità: il tasso del 38% di workflow multi-skill ha CI di Wilson al 95% [34%, 42%] su n=820 workflow; il tasso è significativamente sopra il 25% con alta confidence. (e) Robustezza nel tempo: abbiamo rieseguito l'analisi su tre finestre non sovrapposte di 30 giorni e abbiamo trovato la quota delle top-5 skill stabile in [68%, 74%], il gap di valore long-tail stabile in [1,7, 2,3] punti di rating. La distribuzione è empiricamente stabile sull'orizzonte di 90 giorni.

ANTI-PATTERN DI IMPLEMENTAZIONE · §53 · CINQUE MODALITÀ DI FALLIMENTO NELLE ADOZIONI DI SKILL-LIBRARY. Sui 7 team che Madani Lab ha consigliato sull'architettura di skill library tra Q3 2025 e Q1 2026, cinque anti-pattern ricorrono. (1) ""Skill library come deliverable one-time"": i team producono una skill library, la dichiarano completa e non la rivisitano mai. La library decade man mano che i tool sottostanti evolvono e le skill diventano stale.

Remediation: audit skill trimestrale, ritirare skill stale, aggiornare le descrizioni skill per matchare il comportamento attuale dei tool. La cadenza di audit Madani è 90 giorni. (2) ""Skill senza owner"": i team aggiungono skill alla library senza nominare un owner; quando una skill si rompe, nessuno è responsabile di sistemarla. Remediation: ogni skill deve avere un owner nominato (un engineer o un team) responsabile della sua manutenzione. (3) ""Nessun layer di skill discovery"": i team accumulano skill senza un meccanismo di discovery, quindi gli engineer non possono trovare skill esistenti e le re-implementano.

Remediation: un tool di skill-search (ricerca semantica sulle descrizioni skill) e un file di indice del registry che elenca tutte le skill con riassunti di una riga. (4) ""Specializzazione prematura"": i team splittano le skill in varianti specializzate prima che i pattern d'uso osservati giustifichino lo split, creando una maintenance tax per varianti poco usate. Come illustra il §51, il momento giusto per splittare è quando i pattern d'uso diventano bimodali. (5) ""Skill senza schemi IO"": i team scrivono skill con descrizioni in prosa di input/output piuttosto che schemi formali; la composabilità soffre, il glue code si moltiplica. Remediation: ogni skill espone una superficie IO JSON-schema-compatible.

INTEGRAZIONE CROSS-PILLAR · §54 · DOVE LE SKILL INCONTRANO GLI ALTRI WAB PILLAR. Integrazione complementare con P01 Context: le skill sono esse stesse una forma di contesto — invocare una skill porta la documentazione, le convenzioni e la superficie IO della skill nel contesto di lavoro dell'agent. Un workflow con 5 skill invocate ha un contesto misurabilmente più ricco di un workflow con 1 skill.

Integrazione complementare con P02 Skills (in sé): non è una tautologia — le meta-skill (skill che operano sulla skill library, come skill-search e skill-audit) sono esse stesse skill, e la loro maturità L4 dipende dalla maturità L4 della skill library su cui operano. Integrazione complementare con P11 Auto-Improvement: le invocazioni skill a basso rating alimentano lo stage PROPOSE del ciclo Dreams — rating cronicamente bassi su una specifica skill propongono o (a) migliorare la skill, (b) splittare la skill, (c) ritirare la skill. Integrazione complementare con P03 Memory: ogni skill può avere il proprio namespace di memoria, permettendo learning skill-specific (es. tweet-writer ricorda quali hook hanno funzionato nei tweet passati) senza inquinare la memoria globale.

Tensione strutturale con P10 Portability: una skill library con assunzioni framework-specific (es. assumere sintassi tool-call Claude-specific) è meno portabile di una con superfici IO framework-neutral. La mitigazione è specificare le skill contro uno schema portabile e lasciare che l'adapter harness-specific viva fuori dalla definizione della skill.

DISCUSSIONE · §55 · COMPONIBILITÀ DELLE SKILL COME ASIMMETRIA STRUTTURALE DELL'ECOSISTEMA DI SKILL. La scelta architetturale tra "skill profonde" (poche, grandi, skill complesse che gestiscono interi workflow) e "skill superficiali" (molte, piccole, skill single-purpose composte al momento del workflow) è la decisione di design dominante nell'architettura di skill library. La library Madani è strutturalmente sbilanciata verso skill superficiali: delle 42 skill, la descrizione skill mediana sta in circa 4-6 KB di prosa, e la superficie IO skill mediana definisce 3-5 campi di input e 2-3 campi di output.

La profondità di composizione media (numero di skill per workflow multi-skill) è 2,4, con massimo osservato 7. Tre pezzi di evidenza supportano la propensione skill-superficiali. Primo, il case study di composabilità del §50 dimostra che la riduzione di 14× del glue code era raggiungibile solo perché le skill costituenti avevano superfici IO piccole e pulite; skill più profonde avrebbero avuto superfici IO troppo complesse per essere composte meccanicamente.

Secondo, il case study di specializzazione del §51 ha mostrato che splittare una skill generalista produce guadagni di qualità misurabili perché i sub-dominio hanno requisiti di qualità distinti; un'alternativa "go deep" (una grande skill autoresearch con branching sub-dominio interno) avrebbe intrecciato i sub-dominio e reso ciascuno più difficile da mantenere. Terzo, i dati di power-law del §49 mostrano che la long-tail di skill a bassa invocazione produce valore sproporzionato per invocazione; questa proprietà richiede che la long tail sia economica da scrivere ed economica da mantenere, il che richiede skill superficiali. La propensione skill-superficiali è una scelta di design controintuitiva in un ambiente in cui lo sforzo di engineering tende a fluire verso capability profonde.

La disciplina è resistere alla profondità in favore della componibilità.

(Q1) IPOTESI: La power-law 90/10 nei conteggi di invocazione skill tiene tra organizzazioni con dimensioni di skill library sopra ~30 skill; sotto quella scala, la distribuzione è più uniforme perché le library più piccole non hanno ancora la massa long-tail. TEST DI FALSIFICAZIONE: studio cross-organization di conteggi di invocazione skill con 20 organizzazioni stratificate per dimensione library. (Q2) IPOTESI: Il gap di valore long-tail (rating per invocazione long-tail più alto della testa) generalizza tra organizzazioni ed è strutturale piuttosto che Madani-specifico; il gap riflette il trade-off valore-volume nel design di skill library. TEST DI FALSIFICAZIONE: audit cross-organization di expert rating su 15 library. (Q3) IPOTESI: La componibilità di skill via schemi puliti produce una riduzione di 5-10× del glue code per workflow; la riduzione è indipendente dalla complessità del workflow.

TEST DI FALSIFICAZIONE: implementazione appaiata di 20 workflow multi-skill con e senza schemi puliti, misura conteggi di righe glue code. (Q4) IPOTESI: La specializzazione-da-uso (§51) supera la specializzazione-upfront sul costo di maintenance su 12+ mesi perché evita la dead-branch tax. TEST DI FALSIFICAZIONE: studio di coorte di 24 mesi che confronta le due strategie di specializzazione in team appaiati. (Q5) IPOTESI: Una primitiva di skill-discovery (ricerca semantica sulle descrizioni skill) aumenta il tasso di invocazione long-tail di >50% abbassando il costo di discovery; senza discovery, la long-tail rimane sotto-utilizzata. TEST DI FALSIFICAZIONE: studio A/B di skill-discovery vs no-discovery su team appaiati. (Q6) IPOTESI: Gli ecosistemi di skill convergono nel tempo verso skill condivise cross-organization (es. tweet-writer, exa-plus, n8n-workflow) — queste diventano skill "lingua franca" che qualsiasi organizzazione che adotta il pattern WAB avrebbe.

TEST DI FALSIFICAZIONE: studio longitudinale di ecosistemi di skill su più organizzazioni, misura overlap di skill inter-organization.

[1] Anthropic (2025), Claude Skills Documentation. [2] Wang G., Xie Y., Jiang Y., Mandlekar A., Xiao C., Zhu Y., Fan L., Anandkumar A. (2023), Voyager: An Open-Ended Embodied Agent with Large Language Models, arXiv:2305.16291. [3] Hong S., Zheng X., Chen J., Cheng Y., Wang J., Zhang C., Wang Z., Yau S.K.S., Lin Z., Zhou L. et al. (2024), MetaGPT: Meta Programming for Multi-Agent Collaboration, ICLR. [4] Park J.S., O'Brien J.C., Cai C.J., Morris M.R., Liang P., Bernstein M.S. (2023), Generative Agents: Interactive Simulacra of Human Behavior, UIST. [5] Schick T., Dwivedi-Yu J., Dessì R., Raileanu R., Lomeli M., Zettlemoyer L., Cancedda N., Scialom T. (2023), Toolformer: Language Models Can Teach Themselves to Use Tools, NeurIPS. [6] Hwang J. et al. (2024), Tool Learning with Foundation Models. [7] Wu Q. et al. (2024), AutoGen: Enabling Next-Gen LLM Applications via Multi-Agent Conversation, ICML. [8] LangChain (2024), LangChain Tools Documentation. [9] OpenAI (2024), Function Calling Documentation. [10] Anthropic (2024), Tool Use Documentation. [11] Significant Gravitas (2023), AutoGPT GitHub Repository. [12] Cemri M., Pan M.Z., Yang S., Agrawal L.A., Chopra B., Tiwari R., Keutzer K., Parameswaran A., Klein D., Ramchandran K., Zaharia M., Gonzalez J.E., Stoica I. (2025), Why Do Multi-Agent LLM Systems Fail?, arXiv:2503.13657v3, NeurIPS 2025. [13] Tran D. & Kiela D. (2026), Single-Agent LLMs Outperform Multi-Agent Systems on Multi-Hop Reasoning, arXiv:2604.02460. [14] Wang C. & Shu Y. (2026), MetaCogAgent, arXiv:2605.17292v1. [15] Es S., James J., Espinosa-Anke L., Schockaert S. (2024), RAGAS, EACL 2024, arXiv:2309.15217. [16] Anthropic (2022), Constitutional AI. [17] Anthropic (2025), Claude Sonnet 4.5 Technical Report. [18] Madani Lab (2026), Skill System Reference Implementation v1.0 (42 skills, MIT-licensed). [19] Madani Lab (2026), skill-template.md v1.2. [20] Madani Lab (2026), skills-search primitive v0.4. [21] Gamma E., Helm R., Johnson R., Vlissides J. (1994), Design Patterns: Elements of Reusable Object-Oriented Software, Addison-Wesley. [22] Karpathy A. (2024), various personal-blog reflections on agentic system design.

Il sistema di skill Madani ha i seguenti impegni strutturali:

(1) UNA CARTELLA PER SKILL. Ogni skill vive in una cartella sotto '/skills/<skill-name>/' contenente un 'SKILL.md' (la specifica agent-facing), script opzionali in qualsiasi linguaggio, asset bundled opzionali e dati di riferimento opzionali. La cartella è l'unità di skill — non c'è un registry globale che debba essere aggiornato per aggiungere una skill; la skill esiste se la sua cartella esiste.

(2) SKILL.md COME CONTRATTO D'INTERFACCIA. Il file SKILL.md segue un template stretto: name, summary, when-to-use, when-not-to-use, inputs, outputs, examples, dependencies. L'agent legge questo file al momento dell'attivazione della skill e lo usa come base per la decisione su se e come invocare la skill.

(3) NIENTE COMPILAZIONE, NIENTE REGISTRAZIONE. Le skill si aggiungono creando una cartella; si rimuovono cancellandola. Non c'è build step, nessun registry da aggiornare, nessun servizio da riavviare. La skill diventa disponibile all'agent al suo ciclo di attivazione successivo.

(4) COMPOSIZIONE HOT-SWAPPABLE. Le skill possono chiamare altre skill via un pattern di invocazione strutturato. L'agent può comporre skill a runtime in base al task corrente; gli autori delle skill non devono anticipare ogni composizione.

(5) MEMORIA SIDE-CHANNEL. Ogni skill può mantenere la propria memoria sotto '/skills/<skill-name>/memory/', isolata dalla memoria delle altre skill. Questo risolve la failure mode "la skill A ha scritto in una memoria condivisa e la skill B l'ha letta aspettandosi un formato diverso".

Cinque osservazioni empiriche.

(1) LA VELOCITÀ DI CREAZIONE SKILL È UN LEADING INDICATOR DELLA SALUTE DEL WORKSPACE. Madani ha creato 42 skill attive su 12 mesi (mediana 3,5 skill al mese). Periodi di bassa velocità di skill-creation (< 1/mese) hanno preceduto periodi di stagnazione operativa; periodi di alta velocità (> 5/mese) hanno preceduto periodi di scaling operativo. Ipotizziamo ma non abbiamo testato formalmente che la velocità di creazione skill sia un leading indicator della maturazione del workspace (il team sta imparando a esternalizzare pattern appresi in skill riutilizzabili).

(2) L'INVOCAZIONE DI SKILL SEGUE UNA POWER LAW. Le top-5 skill rappresentano ~70% di tutte le invocazioni; le bottom-20 skill sono ciascuna invocata < 1% del tempo. Questo è coerente con un ecosistema di skill sano (task comuni hanno skill comuni) ma suggerisce opportunità di consolidamento skill nella long tail.

(3) LE MODALITÀ DI FALLIMENTO SONO DOMINATE DALLA QUALITÀ DI SKILL.md. Il 64% dei fallimenti di invocazione skill si riconduce a contenuto SKILL.md ambiguo, incompleto o fuorviante (l'agent ha invocato la skill in un contesto che SKILL.md non aveva anticipato). Il 24% si riconduce a bug interni alla skill (lo script ha fallito).

Il 12% si riconduce a fallimenti di dipendenze (un servizio upstream era non disponibile). L'implicazione: la qualità della skill è limitata dalla qualità di SKILL.md, non dalla qualità del codice.

(4) LA COMPOSIZIONE CROSS-SKILL È RARA MA DI VALORE. Solo ~8% dei completamenti di task dell'agent coinvolgono l'invocazione di 2+ skill in composizione. Ma l'8% che lo fa sono i task a più alto valore (punteggio composito medio di outcome 0,84 vs 0,71 per task single-skill). La lezione architetturale: ottimizzare i path cross-skill rari ma di valore anche a costo della semplicità single-skill.

(5) LA CAPABILITY DI HOT-SWAP È USATA IN PRATICA. Abbiamo osservato una media di 1,8 modifiche di cartella skill al giorno durante le settimane di sviluppo attivo. La capability di hot-swap (no build, no registration, no restart) non è teorica: è il modo dominante in cui il team itera sulle skill.

Tre implicazioni.

(i) L'INVARIANTE FOLDER-AS-SKILL È LA DECISIONE DI DESIGN CHIAVE. Rendendo la cartella l'unità di skill, abbiamo eliminato un'intera categoria di attrito operativo (registry, build step, cicli di deploy). Questa è la decisione architetturale che raccomandiamo più fortemente ad altri team di adottare; è anche la decisione che vediamo altri framework agentic mancare sistematicamente (la maggior parte dei framework introduce un registry, un file di config o un build step).

(ii) SKILL.md È IL COLLO DI BOTTIGLIA. La failure mode dominante è la qualità di SKILL.md. Abbiamo risposto con un template SKILL.md (sezioni obbligatorie), un linter SKILL.md (intercetta sezioni mancanti) e un processo di review SKILL.md trimestrale. Post-fix, i fallimenti driven da SKILL.md sono scesi dal 64% dei fallimenti di skill al 23%.

(iii) I CRITERI DI MATURITÀ WAB PILLAR 02 (SKILLS). Abbiamo codificato le lezioni operative come criteri L0-L4 per il Pillar Skills: L0 = le skill sono inline nei prompt dell'agent; L1 = le skill esistono come file separati ma senza struttura standard; L2 = le skill seguono un template documentato con sezioni richieste; L3 = L2 + linting automatico + composizione cross-skill testata; L4 = L3 + automazione skill-discovery + processo di review trimestrale. Il workspace Madani opera a L4 per il sistema di skill.

Chiudiamo riflettendo sul pattern architetturale più ampio. Le skill sono un'istanza del pattern più generale "deployable capability" — un'unità di capability agentic che può essere aggiunta, rimossa o modificata senza toccare l'applicazione host. Il pattern generalizza: gli agent stessi possono essere deployable nello stesso senso (il pattern agent-as-skill annidato); la documentazione può essere deployable (il pattern doc-as-skill, in cui materiale di riferimento vive accanto alle skill); anche le policy possono essere deployable (il pattern policy-as-skill, in cui le regole di governance vivono in una cartella skill e l'agent le consulta al momento della decisione). Il sistema di skill Madani è la nostra implementazione di riferimento di questo pattern generale; stiamo estraendo il pattern generale nella specifica WAB v0.4.

DISCUSSIONE · CONFRONTO CON SISTEMI PLUGIN/EXTENSION. Il pattern skill-as-folder è strutturalmente simile ai classici sistemi plugin software (estensioni VS Code, plugin Eclipse, estensioni browser). La differenza chiave: i plugin classici tipicamente richiedono uno step di registrazione (install · activate · update).

Le skill no — la cartella è la registrazione. Sosteniamo che questo conti perché i sistemi agentic beneficiano di un loop di iterazione più veloce del software classico (iterazione per-task vs iterazione per-release), e qualsiasi attrito nella pipeline di creazione delle capability danneggia in modo sproporzionato la velocità di iterazione. Eliminare lo step di registrazione rimuove uno dei punti di attrito più comuni.

DISCUSSIONE · SKILL DISCOVERY. Con 42 skill attive e una distribuzione di invocazione a power-law, la domanda "quale skill dovrebbe invocare l'agent?" diventa non triviale. Abbiamo implementato un layer di skill-discovery che gira all'inizio del task: una chiamata LLM esamina la descrizione del task contro il catalogo dei file SKILL.md e ritorna suggerimenti di skill classificati.

Il layer di skill-discovery aggiunge ~120ms di latenza per task ma riduce l'invocazione skill sbagliata del 47%. Stiamo studiando se la decisione di skill-discovery possa essere cachata (skill selezionate per task simili nel passato) per ridurre il costo di latenza.

(1) Template di riferimento pubblico per cartelle skill. (2) Layer di skill-discovery come primitiva aperta (disaccoppiata dallo stack specifico di Madani). (3) Tooling di analisi delle dipendenze cross-skill (quali skill dipendono da quali · cosa si rompe se rimuovo la skill X).

Anthropic (2025), Claude Skills Documentation; Wang G. et al. (2023), Voyager: An Open-Ended Embodied Agent with Large Language Models; Hong S. et al. (2024), MetaGPT: Meta Programming; Park J. et al. (2023), Generative Agents; Schick T. et al. (2023), Toolformer; Hwang J. et al. (2024), Tool Learning with Foundation Models; Madani Lab (2026), Skill System Reference Implementation v1.0 (42 skills, MIT-licensed).