Skill mining: da 3.500 candidate a 466 capacità

I numeri in questo articolo riflettono il sistema al momento della pubblicazione (gennaio 2026). Consulta la nostra pagina del team per le cifre attuali.

Il problema delle 3.500 skill

Quando abbiamo iniziato a costruire un sistema di orchestrazione di agenti, abbiamo affrontato una sfida interessante: ci sono migliaia di skill potenziali sparse per l’ecosistema AI. Repository GitHub, documentazione dei vendor, progetti della community, pattern interni - le skill esistono ovunque. Ma quali contano? Quali funzionano? E come mantieni una libreria di skill coerente che gli agenti possano davvero usare?

La nostra risposta: un loop sistematico di mining e ingestione.

I numeri di oggi

Poco più di tre mesi dopo che Anthropic ha lanciato Agent Skills il 16 ottobre 2025, ecco dove stavamo quando questo articolo è stato pubblicato il 27 gennaio 2026:

Metrica	Conteggio
Candidati identificati	3.500+
Skill adottate	466
Skill dei vendor	373
Skill interne	93
Vendor attivi	25+
Token medi per skill	2.834
Strumenti referenziati	89
Tag unici	635

Abbiamo esaminato oltre 3.500 skill candidate. Ne abbiamo adottate 466. È un tasso di adozione del 13% - e quella selettività è voluta.

Il sistema a livelli di conoscenza

Non tutte le skill sono uguali. Le organizziamo in cinque livelli di conoscenza (K0-K4), ciascuno che rappresenta un ambito di applicabilità diverso:

K0: Fondamenta (universale)

Skill che ogni agente dovrebbe avere. Rappresentano capacità da “buon pensatore” che funzionano ovunque.

foundations/
├── test-first-discipline       # TDD: Red-Green-Refactor
├── evidence-based-completion   # Verify before claiming done
├── systematic-debugging        # Root cause methodology
├── structured-planning         # Break work into tasks
└── context-budget-awareness    # Manage token consumption

Le skill K0 sono portabili in qualsiasi progetto, qualsiasi dominio, qualsiasi stack. Codificano pattern cognitivi universali.

K1: Identità (disciplina)

Skill da “buon ingegnere” o “buon ricercatore” che si applicano tra progetti all’interno di una disciplina.

identities/
├── research-workflows          # Multi-source research
├── web-extraction-playbook     # Content extraction
├── code-review                 # PR review patterns
└── cli-interface-standards     # CLI design patterns

K2: Domini (competenza sulla materia)

Skill da “buon esperto di database” o “buon ingegnere della sicurezza” portabili all’interno di un campo.

domains/
├── schema-migration-workflow   # Safe migration patterns
├── rpc-validation-checklist    # RPC health checks
├── auth-validation-checklist   # JWT/OAuth patterns
└── secrets-audit-checklist     # Credential scanning

K3: Stack (tecnologia)

Skill da “buon utente Supabase” o “buon sviluppatore Cloudflare” per stack tecnologici specifici.

stacks/
├── maguyva-quickstart          # Our semantic search patterns
├── cloudflare-deployment       # Workers/Pages deployment
└── mcp-tool-best-practices     # MCP tool selection

K4: Progetto (organizzazione)

Skill specifiche della nostra organizzazione e dei nostri workflow.

project/
├── agent-creation-workflow     # How we build agents
├── skill-authoring-workflow    # How we write skills
├── mining-session-workflow     # This very process
└── vendor-skill-evaluation     # Evaluation rubrics

Il loop di mining

Fase 1: scoperta

Le skill arrivano da ovunque:

Repository dei vendor: AWS, Anthropic, Cloudflare, Supabase, e collaboratori della community pubblicano collezioni di skill. Tracciamo oltre 25 vendor root.

Progetti della community: GitHub è pieno di template per Claude Code, pattern di agenti, e definizioni di workflow.

Pattern interni: man mano che il nostro team risolve problemi, emergono pattern. Questi vengono formalizzati in skill.

Mining della documentazione: la documentazione tecnica spesso contiene skill implicite - procedure, checklist, alberi decisionali.

La scoperta è continua. Usiamo un backlog di skill per tracciare i candidati prima della valutazione formale.

Fase 2: valutazione

Ogni candidato passa attraverso la stessa rubrica:

adoption_criteria:
  - fills_real_gap: true      # We lack this capability
  - well_structured: true     # Progressive disclosure
  - actively_maintained: true # Commits in last 6 months
  - portable: true            # Not hyper-specific
  - tested: true              # Evidence of usage

Tutti e cinque i criteri di prodotto devono passare. Ecco perché l’87% dei candidati viene respinto.

Poi ogni candidato passa attraverso una revisione di fiducia separata. Non trattiamo un repository ufficiale di un vendor, un maintainer noto della community, e un repository GitHub casuale come fonti di verità equivalenti.

trust_review:
  vendor_credibility:
    - ownership_verified       # Official vendor, known maintainer, or internal source
    - maintenance_signal       # Recent commits, issue response, release history
    - adoption_signal          # Evidence of real use, stars alone are not enough
    - provenance_clear         # We can trace where the skill came from
  prompt_injection_scan:
    - hidden_instruction_check # Buried "ignore previous instructions" patterns
    - exfiltration_check       # Prompts that try to leak files, secrets, or context
    - authority_check          # Claims of priority over system or developer rules
  script_audit:
    - inspect_scripts          # Read shell/python/js helpers before adoption
    - network_and_exec_review  # curl|bash, remote downloads, subprocess execution
    - file_and_secret_review   # Env vars, credential access, broad file writes
    - destructive_action_check # rm, reset, overwrite, or unsafe automation

I vendor fidati ottengono una revisione di provenienza più leggera, ma non un lasciapassare gratuito. Le fonti non fidate o sconosciute ottengono un audit manuale più approfondito, e non eseguiamo script inclusi finché non sono stati letti, delimitati nell’ambito, e classificati come sicuri.

Analisi delle lacune: prima di adottare, cerchiamo nel nostro registro:

uv run orkestra skills search "<capability>"

Se ce l’abbiamo già, non ci serve. Se abbiamo qualcosa di simile, potremmo unire invece di adottare.

Punteggio di profondità e standard: valutiamo anche quanto pienamente un candidato usa il modello agent-skill. Un singolo SKILL.md può comunque essere utile, ma le skill più profonde hanno più valore quando separano istruzioni da riferimenti, script, e asset nel modo in cui agentskills.io incoraggia.

skill_depth:
  - level_1: SKILL.md only                     # Single instruction file
  - level_2: SKILL.md + strong description     # Clear triggers and scope
  - level_3: adds references/                  # Load docs only when needed
  - level_4: adds atomic scripts/              # Small, reviewable helpers
  - level_5: adds assets/examples/templates    # Full progressive disclosure
depth_signals:
  - standards_adherence        # Structure aligns with agentskills.io conventions
  - reference_quality          # Curated references, not giant context dumps
  - script_atomicity           # Focused helpers, not opaque monoliths
  - tool_boundary_clarity      # Clear limits on what the skill can execute
  - community_signal           # Stars/forks/users help, but only as a weak boost

Le stelle GitHub possono alzare un po’ un punteggio di credibilità, ma non salvano mai una skill superficiale o non sicura. Un repository con molte stelle e un SKILL.md vago e script opachi ottiene un punteggio inferiore a un repository più piccolo con una descrizione precisa, references/ curati, e helper atomici che sfruttano davvero la piena capacità della skill.

Analisi strutturale: controlliamo la qualità della skill:

wc -l vendor/<repo>/<skill>/SKILL.md  # Size check
ls vendor/<repo>/<skill>/scripts/     # Supporting files
ls vendor/<repo>/<skill>/references/  # Bundled docs

Se un candidato include script, quella revisione diventa più stringente. Una buona skill non è solo utile; deve essere leggibile, delimitata, e sicura da affidare a un agente. Solo quel filtro di sicurezza squalifica una fetta significativa di candidati altrimenti interessanti.

Fase 3: ingestione

Quando una skill supera la valutazione, entra nel registro. Ma le skill non vengono mai adottate senza modifiche. Vengono adattate al nostro sistema.

Modifiche all’adozione:

1. Normalizzazione dei metadati: ogni skill ottiene il nostro schema di frontmatter
2. Assegnazione del livello K: le skill vengono collocate nel livello di conoscenza appropriato
3. Arricchimento dei tag: vengono aggiunti tag per la scopribilità
4. Dichiarazione degli strumenti: gli strumenti consentiti vengono dichiarati esplicitamente
5. Allineamento delle sezioni: il contenuto viene ristrutturato per corrispondere al nostro template

Una tipica skill YAML dopo l’ingestione:

metadata:
  identifier: vendor-skill-evaluation
  name: vendor-skill-evaluation
  description: Systematic evaluation of vendor skills for adoption.
  type: workflow
  layer: K4
  semantic_folder: project
  source: core
  last_updated: '2026-01-17'

frontmatter:
  tags:
    - agents
    - meta
    - skill-adoption
    - vendor
  allowed_tools:
    - Bash
    - Read
    - Write
    - Edit
    - Grep
    - Glob
    - Task

Fase 4: assegnazione dell’ambito

Le skill vengono assegnate ad ambiti - categorie che determinano quali agenti caricano quali skill:

scopes:
  database:
    primary_skills:
      - domains/schema-migration-workflow
      - domains/rpc-validation-checklist
      - vendor/supabase/supabase-database
      - vendor/supabase/supabase-auth

  research:
    primary_skills:
      - identities/research-workflows
      - identities/web-extraction-playbook
      - identities/dataset-discovery-quickstart

Gli agenti dichiarano i propri ambiti, e le skill vengono assegnate automaticamente:

# Agent definition
scopes: [database, research]
# Gets: all database skills + all research skills + universal skills

Fase 5: materializzazione

Le skill non vivono come YAML in produzione. Vengono renderizzate in file SKILL.md che Claude Code può caricare:

uv run orkestra sync

Questo comando:

1. Legge tutte le definizioni YAML delle skill
2. Le renderizza attraverso template Jinja
3. Scrive i file SKILL.md in .claude/skills/
4. Organizza per livello K (foundations/, identities/, domains/, stacks/, project/)

La struttura di output finale:

.claude/skills/
├── foundations/     # K0: Universal
├── identities/      # K1: Discipline
├── domains/         # K2: Subject
├── stacks/          # K3: Technology
├── project/         # K4: Organization
└── vendor/          # External skills

Il pattern dell’ambito dormiente

Uno dei nostri pattern più potenti sono le skill “adottate ma non caricate”. Le chiamiamo ambiti dormienti.

Considera le skill di calcolo scientifico dal repository k-dense-scientific. Abbiamo adottato oltre 120 skill che coprono bioinformatica, chimica, calcolo quantistico, e informatica clinica. Ma la maggior parte dei nostri agenti non ha bisogno di docking molecolare o analisi dell’espressione genica.

Invece di caricare tutte le 120 skill in ogni agente (gonfiando le finestre di contesto), noi:

1. Adottiamo le skill con un ambito specifico (es. bioinformatics)
2. Le manteniamo dormienti - registrate ma non caricate
3. Le attiviamo solo quando un agente dichiara quell’ambito

# In scopes.yaml - dormant scope
bioinformatics:
  description: "Bioinformatics and genomics"
  primary_skills: []  # Empty - skills exist but aren't loaded

# When an agent needs bioinformatics:
# Agent YAML
scopes: [research, bioinformatics]  # Now loads bioinformatics skills

Questo pattern ci permette di avere 466 skill nel registro mentre gli agenti tipici ne caricano solo 40-60 rilevanti.

Tipi di skill

Le skill si presentano in tre pattern cognitivi:

Workflow

Passi procedurali ordinati: “1. Fai X, 2. Poi Y, 3. Infine Z”

type: workflow
# Examples: schema-migration-workflow, mining-session-workflow

Disciplina

Guardrail comportamentali: “Fai sempre X”, “Non fare mai Y”, “Preferisci Z”

type: discipline
# Examples: test-first-discipline, evidence-based-completion

Checklist

Criteri di verifica: “Conferma X”, “Verifica Y”, “Controlla Z”

type: checklist
# Examples: auth-validation-checklist, secrets-audit-checklist

Gate di qualità

Ogni skill deve superare la validazione prima di essere rilasciata:

validation:
  file_exists: true           # Skill file at declared path
  frontmatter_valid: true     # Frontmatter parses correctly
  sections_complete: true     # Expected sections present
  tools_registered: true      # Declared tools exist in registry

Le descrizioni devono essere lunghe 50-400 caratteri con frasi di attivazione (“Usa quando…”, “Quando hai bisogno di…”) così che Claude Code sappia quando suggerirle.

Validiamo continuamente:

uv run orkestra validate --show-warnings

L’ecosistema dei vendor

Le nostre 373 skill di vendor arrivano da:

Provider	Skill	Dominio
AWS Agent	19	Servizi cloud
Anthropic	12	Generazione documenti
Cloudflare	8	Edge computing
Supabase	5	Database
k-dense	100+	Calcolo scientifico
silvainfm	4	Data science
Java Developer Kit	45+	Spring/Java
Vercel	1	Automazione browser

Ogni vendor root è dichiarato in metadata.yaml:

vendor_roots:
  - path: vendor/aws-agent-skills
    provider: aws
  - path: vendor/k-dense-scientific/scientific-skills
    provider: k-dense
  - path: vendor/supabase-skills
    provider: supabase

Quando orkestra sync viene eseguito, le skill dei vendor vengono collegate con symlink in .claude/skills/vendor/ con il proprio namespace del provider.

Cosa abbiamo imparato

La selettività ripaga. È allettante adottare tutto ciò che sembra utile. Ma ogni skill costa token. Con 2.834 token medi per skill, il gonfiore fa male in fretta. Il nostro tasso di adozione del 13% mantiene gli agenti snelli.

La struttura abilita la scopribilità. Il sistema a livelli K non è solo organizzazione - riguarda la portabilità. Le skill K0 possono essere riutilizzate ovunque. Le skill K4 sono intenzionalmente specifiche del progetto. Questa chiarezza aiuta sia gli esseri umani che gli agenti a trovare ciò di cui hanno bisogno.

Gli ambiti dormienti scalano. Puoi adottare centinaia di skill senza caricarle tutte. Gli ambiti ti permettono di costruire un registro completo mantenendo gestibili le finestre di contesto dei singoli agenti.

La modifica all’adozione è essenziale. Le skill grezze dei vendor raramente si adattano al tuo sistema. Il processo di ingestione - aggiungere metadati, assegnare livelli, arricchire i tag - fa funzionare internamente le skill esterne.

Il mining è continuo. Il numero 3.500 continua a crescere. Compaiono nuovi repository di vendor. Emergono pattern della community. I workflow interni si consolidano. Il loop non si ferma mai.

Cosa viene dopo

Stiamo lavorando su diversi miglioramenti:

1. Rilevamento automatico delle lacune: avvisa quando fallimenti comuni degli agenti potrebbero essere risolti da una skill non ancora adottata
2. Workflow di deprecazione delle skill: processo formale per ritirare skill superate o non utilizzate
3. Dipendenze tra skill: dichiarazione esplicita dei prerequisiti delle skill
4. Analisi di utilizzo: traccia quali skill gli agenti invocano davvero rispetto a quelle che si limitano a caricare

Il loop di mining delle skill è infrastruttura. Non è affascinante. Ma è ciò che fa funzionare 41 agenti in modo coerente con 466 capacità pur restando entro i limiti di contesto.

Questa è la storia di come 3.500 diventano 466. Non ignorandone 3.000 - valutandoli sistematicamente e adottando solo ciò che funziona.

---

Vuoi vedere il sistema di skill in azione? Dai un’occhiata a uv run orkestra skills list per esplorare il nostro registro attuale.