Il tuo agente AI sa seguire istruzioni. Ma sa anche scriverne di nuove? Il SkillToolset dell’Agent Development Kit (ADK) permette agli agenti di caricare competenze specifiche quando servono davvero. Con la configurazione giusta, il tuo agente può generare expertise completamente nuove a runtime. Che ti serva una checklist di security review, un audit di compliance o un validator per pipeline dati, il flusso è diretto: generala, caricala, usala.
Il problema dei prompt monolitici
La maggior parte degli agenti AI prende tutta la conoscenza dal system prompt. Gli sviluppatori concatenano regole di compliance, style guide, reference API e procedure di troubleshooting in un’unica stringa di istruzioni gigantesca.
Funziona quando l’agente ha due o tre capacità. Quando scali a dieci task o più? Stai sprecando migliaia di token a ogni chiamata LLM. Che la query specifica dell’utente richieda quella conoscenza o meno.
La Agent Skills specification risolve questo tramite progressive disclosure. Spezza il caricamento della conoscenza in tre livelli distinti:
- L1 Metadata (~100 token per skill): Solo nome e descrizione. Caricato all’avvio per tutte le skill. È il menu che l’agente scansiona per decidere cosa è rilevante.
- L2 Instructions (<5.000 token): Il corpo completo della skill. Caricato via API solo quando l’agente attiva esplicitamente quella skill.
- L3 Resources (quando serve): File di riferimento esterni tipo style guide o spec API. Caricati solo quando le istruzioni della skill li richiedono.
Con questa architettura, un agente con 10 skill parte ogni chiamata con circa 1.000 token di metadata L1 invece di 10.000 token in un prompt monolitico. Tradotto: circa 90% di riduzione nell’uso del contesto base.
ADK implementa tutto questo tramite la classe SkillToolset, che auto-genera tre strumenti: list_skills (L1), load_skill (L2) e load_skill_resource (L3).
Pattern 1: Skill inline (il post-it)
Il pattern più semplice: un oggetto Python con name, description e instructions, definito direttamente nel codice dell’agente. Perfetto per regole piccole e stabili che cambiano raramente.
seo_skill = models.Skill(
frontmatter=models.Frontmatter(
name="seo-checklist",
description="SEO optimization checklist for blog posts.",
),
instructions=(
"When optimizing a blog post for SEO, check each item:\n"
"1. Title: 50-60 chars, primary keyword near the start\n"
"2. Meta description: 150-160 chars, includes a call-to-action\n"
"3. Headings: H2/H3 hierarchy, keywords in 2-3 headings\n"
"4. First paragraph: Primary keyword in first 100 words\n"
"5. Images: Alt text with keywords, compressed, descriptive names\n"
"Review the content against each item and suggest improvements."
),
)I campi frontmatter diventano metadata L1, che l’LLM vede in ogni chiamata. Le instructions diventano L2, caricate solo quando l’agente decide che questa skill è rilevante.
Pattern 2: Skill basate su file (il raccoglitore di riferimenti)
Le skill inline funzionano per checklist semplici. Ma se la tua skill ha bisogno di documenti di riferimento – una style guide, una spec API – ti serve una directory.
Una skill basata su file vive in una sua directory con un file SKILL.md e sottodirectory opzionali per riferimenti, asset e script. Il SKILL.md inizia con frontmatter YAML, seguito da istruzioni Markdown.
skills/blog-writer/
├── SKILL.md # L2: Istruzioni
└── references/
└── style-guide.md # L3: Caricato on demandQuesto design divide la conoscenza su due layer. Le istruzioni SKILL.md (L2) dicono all’agente quali step seguire. Il file references/style-guide.md (L3) fornisce la conoscenza di dominio dettagliata per ogni step. L’agente carica il riferimento solo quando le sue istruzioni lo richiedono via tool load_skill_resource.
Pattern 3: Skill esterne (l’import)
Le skill esterne funzionano esattamente come quelle basate su file. L’unica differenza è da dove viene la directory. Invece di scrivere il tuo SKILL.md, ne scarichi uno da un repository community tipo awesome-claude-skills e lo carichi con la stessa chiamata load_skill_from_dir.
Il codice è identico al Pattern 2. La spec agentskills.io definisce un formato directory universale, quindi load_skill_from_dir non si preoccupa se hai scritto tu il SKILL.md o l’hai scaricato.
Pattern 4: La skill factory – Meta skill che si scrivono da sole
Qui diventa interessante. Una meta skill è una skill il cui scopo è generare nuovi file SKILL.md. Un agente equipaggiato con una meta skill diventa auto-estensibile. Può espandere le proprie capacità senza intervento umano scrivendo e caricando nuove definizioni di skill a runtime.
Lo skill creator è una skill inline le cui istruzioni spiegano come scrivere file SKILL.md validi. La chiave è il campo resources. Embedded la specifica agentskills.io stessa e un esempio funzionante come riferimenti L3. Quando chiedi di creare una nuova skill, l’agente legge questi riferimenti e genera un SKILL.md conforme alla spec.
skill_creator = models.Skill(
frontmatter=models.Frontmatter(
name="skill-creator",
description="Creates new ADK-compatible skill definitions from requirements.",
),
instructions=(
"When asked to create a new skill, generate a complete SKILL.md file.\n\n"
"Read `references/skill-spec.md` for the format specification.\n"
"Read `references/example-skill.md` for a working example.\n\n"
"Follow these rules:\n"
"1. Name must be kebab-case, max 64 characters\n"
"2. Description must be under 1024 characters\n"
"3. Instructions should be clear, step-by-step\n"
),
resources=models.Resources(
references={
"skill-spec.md": "# Agent Skills Specification...",
"example-skill.md": "# Example: Code Review Skill...",
}
),
)Il campo resources è dove la classe models.Resources diventa essenziale. I riferimenti incorporano la spec agentskills.io come skill-spec.md e una skill di code-review funzionante come example-skill.md. Quando l’agente chiama load_skill_resource("skill-creator", "references/skill-spec.md"), ottiene la specifica completa che governa come le skill valide sono strutturate.
La skill factory in azione
Chiedi all’agente: “Mi serve una nuova skill per revieware codice Python per vulnerabilità di sicurezza.”
L’agente carica lo skill creator, legge spec ed esempio via load_skill_resource, e genera una skill completa di Python security review con naming kebab-case valido, istruzioni strutturate che coprono input validation, autenticazione e crittografia, e un formato di reporting basato sulla severità.
La skill generata segue la stessa spec agentskills.io, quindi funziona non solo in ADK ma in qualsiasi agente compatibile: Gemini CLI, Claude Code, Cursor e altri 40+ prodotti che hanno adottato il formato.
Mettere tutto insieme
Con tutte e quattro le skill definite, impacchettarle in un SkillToolset e darle all’agente richiede poche righe:
skill_toolset = SkillToolset(
skills=[seo_skill, blog_writer_skill, content_researcher_skill, skill_creator]
)
root_agent = Agent(
model="gemini-2.5-flash",
name="blog_skills_agent",
description="A blog-writing agent powered by reusable skills.",
instruction=(
"You are a blog-writing assistant with specialized skills.\n"
"Load relevant skills to get detailed instructions.\n"
"Use load_skill_resource to access reference materials.\n"
"Follow each skill's step-by-step instructions.\n"
"Always explain which skill you're using and why."
),
tools=[skill_toolset],
)Le prime tre skill nella lista gestiscono SEO, scrittura e ricerca. La quarta, skill_creator, è la factory. Chiedi a questo agente “Crea una skill per scrivere introduzioni di blog tecnici” e genera un nuovo SKILL.md al volo.
Alcuni consigli prima di iniziare
Le descrizioni sono la tua documentazione API. Il campo description è quello che l’LLM vede a L1 per decidere se caricare una skill. “SEO optimization checklist for blog posts” dice all’agente esattamente quando attivarsi. “A helpful skill” no.
Parti con inline, passa ai file quando serve. Non complicare troppo. Se la tua skill sta in 10 righe di istruzioni, tienila inline. Passa a una skill basata su file quando hai bisogno di documenti di riferimento o vuoi riusarla tra agenti.
Reviewa le skill generate come dipendenze. L’output di una meta skill diventa il comportamento del tuo agente. Tratta i file SKILL.md generati come una code review. Leggi prima di fare deploy.
Best practice per skill generate: Anche se auto-generare skill è un workflow potente, consigliamo di tenere un human-in-the-loop per revieware il SKILL.md finale. Come pratica standard per qualsiasi skill che costruisci, dovresti testarne l’efficacia. Puoi farlo facilmente costruendo valutazioni robuste con ADK per assicurarti che la tua skill funzioni esattamente come previsto prima del deployment.
Inizia
Pronto a costruire la tua skill factory? Controlla la documentazione ADK Skills per capire SkillToolset e progressive disclosure, e clona il repository GitHub per eseguire tutti e quattro i pattern con ADK.
