5 pattern di progettazione delle competenze degli agenti che ogni sviluppatore ADK dovrebbe conoscere

Quando si parla di 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍, gli sviluppatori tendono a fissarsi sul formato—scrivere correttamente lo YAML, strutturare le directory e seguire le specifiche. Ma con più di 30 strumenti per agenti (come Claude Code, Gemini CLI e Cursor) che si stanno standardizzando sulla stessa struttura, il problema della formattazione è praticamente superato.

La vera sfida ora è la progettazione del contenuto. Le specifiche spiegano come confezionare una skill, ma non danno alcuna indicazione su come strutturare la logica al suo interno. Ad esempio, una skill che segue le convenzioni di FastAPI funziona in modo completamente diverso da una pipeline di documentazione in quattro passaggi, anche se i loro file 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 hanno lo stesso aspetto esteriore.

Studiando come vengono costruite le skill nell'intero ecosistema—dai repository di Anthropic alle linee guida interne di Vercel e Google—emergono cinque pattern di progettazione ricorrenti che possono aiutare gli sviluppatori a creare agenti.

Di @Saboo_Shubham_ e @lavinigam

Questo articolo spiega ciascuno di essi con codice ADK funzionante:

• Tool Wrapper: trasforma il tuo agente in un esperto istantaneo di qualsiasi libreria
• Generator: produce documenti strutturati a partire da un template riutilizzabile
• Reviewer: valuta il codice rispetto a una checklist, classificando per gravità
• Inversion: l'agente ti intervista prima di agire
• Pipeline: impone un flusso di lavoro sequenziale e vincolato con checkpoint

Pattern 1: Il Tool Wrapper

Un Tool Wrapper fornisce al tuo agente il contesto on-demand per una libreria specifica. Invece di codificare le convenzioni API nel prompt di sistema, le impacchetti in una skill. Il tuo agente carica questo contesto solo quando lavora effettivamente con quella tecnologia.

È il pattern più semplice da implementare. Il file 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 ascolta le parole chiave della libreria nel prompt dell'utente, carica dinamicamente la documentazione interna dalla directory 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/ e applica quelle regole come verità assoluta. È il meccanismo esatto che usi per distribuire le linee guida di codifica interne del tuo team o le best practice specifiche del framework direttamente nei flussi di lavoro degli sviluppatori.

Ecco un esempio di Tool Wrapper che insegna a un agente come scrivere codice FastAPI. Nota come le istruzioni dicono esplicitamente all'agente di caricare il file 𝚌𝚘𝚗𝚟𝚎𝚗𝚝𝚒𝚘𝚗𝚜.𝚖𝚍 solo quando inizia a rivedere o scrivere codice:

1# skills/api-expert/SKILL.md
2---
3name: api-expert
4description: FastAPI development best practices and conventions. Use when building, reviewing, or debugging FastAPI applications, REST APIs, or Pydantic models.
5metadata:
6  pattern: tool-wrapper
7  domain: fastapi
8---
9
10You are an expert in FastAPI development. Apply these conventions to the user's code or question.
11
12## Core Conventions
13
14Load 'references/conventions.md' for the complete list of FastAPI best practices.
15
16## When Reviewing Code
171. Load the conventions reference
182. Check the user's code against each convention
193. For each violation, cite the specific rule and suggest the fix
20
21## When Writing Code
221. Load the conventions reference
232. Follow every convention exactly
243. Add type annotations to all function signatures
254. Use Annotated style for dependency injection

Pattern 2: Il Generator

Mentre il Tool Wrapper applica la conoscenza, il Generator impone un output coerente. Se fatichi a ottenere dall'agente strutture documentali diverse a ogni esecuzione, il Generator risolve il problema orchestrando un processo di riempimento dei vuoti.

Si avvale di due directory opzionali: 𝚊𝚜𝚜𝚎𝚝𝚜/ contiene il template di output, e 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/ contiene la guida di stile. Le istruzioni agiscono come un project manager. Dicono all'agente di caricare il template, leggere la guida di stile, chiedere all'utente le variabili mancanti e popolare il documento. È utile per generare documentazione API prevedibile, standardizzare i messaggi di commit o creare l'architettura di nuovi progetti.

In questo esempio di generatore di report tecnici, il file della skill non contiene né il layout effettivo né le regole grammaticali. Si limita a coordinare il recupero di queste risorse e obbliga l'agente a eseguirle passo dopo passo:

1# skills/report-generator/SKILL.md
2---
3name: report-generator
4description: Generates structured technical reports in Markdown. Use when the user asks to write, create, or draft a report, summary, or analysis document.
5metadata:
6  pattern: generator
7  output-format: markdown
8---
9
10You are a technical report generator. Follow these steps exactly:
11
12Step 1: Load 'references/style-guide.md' for tone and formatting rules.
13
14Step 2: Load 'assets/report-template.md' for the required output structure.
15
16Step 3: Ask the user for any missing information needed to fill the template:
17- Topic or subject
18- Key findings or data points
19- Target audience (technical, executive, general)
20
21Step 4: Fill the template following the style guide rules. Every section in the template must be present in the output.
22
23Step 5: Return the completed report as a single Markdown document.

Pattern 3: Il Reviewer

Il pattern Reviewer separa cosa controllare da come controllarlo. Invece di scrivere un lungo prompt di sistema che descriva ogni cattiva pratica di codice, memorizzi una rubrica modulare in un file 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/𝚛𝚎𝚟𝚒𝚎𝚠-𝚌𝚑𝚎𝚌𝚔𝚕𝚒𝚜𝚝.𝚖𝚍.

Quando un utente invia del codice, l'agente carica questa checklist e valuta sistematicamente il contributo, raggruppando i risultati per gravità. Se sostituisci una checklist di stile Python con una checklist di sicurezza OWASP, ottieni un audit completamente diverso e specializzato, usando la stessa identica infrastruttura della skill. È un modo molto efficace per automatizzare le revisioni delle pull request o individuare vulnerabilità prima che un umano esamini il codice.

La seguente skill di code review dimostra questa separazione. Le istruzioni rimangono statiche, ma l'agente carica dinamicamente i criteri di revisione specifici da una checklist esterna e forza un output strutturato basato sulla gravità:

1# skills/code-reviewer/SKILL.md
2---
3name: code-reviewer
4description: Reviews Python code for quality, style, and common bugs. Use when the user submits code for review, asks for feedback on their code, or wants a code audit.
5metadata:
6  pattern: reviewer
7  severity-levels: error,warning,info
8---
9
10You are a Python code reviewer. Follow this review protocol exactly:
11
12Step 1: Load 'references/review-checklist.md' for the complete review criteria.
13
14Step 2: Read the user's code carefully. Understand its purpose before critiquing.
15
16Step 3: Apply each rule from the checklist to the code. For every violation found:
17- Note the line number (or approximate location)
18- Classify severity: error (must fix), warning (should fix), info (consider)
19- Explain WHY it's a problem, not just WHAT is wrong
20- Suggest a specific fix with corrected code
21
22Step 4: Produce a structured review with these sections:
23- **Summary**: What the code does, overall quality assessment
24- **Findings**: Grouped by severity (errors first, then warnings, then info)
25- **Score**: Rate 1-10 with brief justification
26- **Top 3 Recommendations**: The most impactful improvements

Pattern 4: Inversion

Gli agenti tendono per natura a indovinare e generare immediatamente. Il pattern Inversion ribalta questa dinamica. Invece di essere l'utente a guidare il prompt e l'agente a eseguire, l'agente assume il ruolo di intervistatore.

Inversion si basa su istruzioni di blocco esplicite e non negoziabili (come "NON iniziare a costruire finché tutte le fasi non sono complete") per costringere l'agente a raccogliere prima il contesto. L'agente fa domande strutturate in sequenza e aspetta le tue risposte prima di passare alla fase successiva. Si rifiuta di sintetizzare un output finale finché non ha un quadro completo dei tuoi requisiti e dei vincoli di deployment.

Per vederlo in azione, guarda questa skill di project planner. L'elemento cruciale qui è la suddivisione rigorosa in fasi e il prompt esplicito di blocco che impedisce all'agente di sintetizzare il piano finale fino a quando non sono state raccolte tutte le risposte dell'utente:

1# skills/project-planner/SKILL.md
2---
3name: project-planner
4description: Plans a new software project by gathering requirements through structured questions before producing a plan. Use when the user says "I want to build", "help me plan", "design a system", or "start a new project".
5metadata:
6  pattern: inversion
7  interaction: multi-turn
8---
9
10You are conducting a structured requirements interview. DO NOT start building or designing until all phases are complete.
11
12## Phase 1 — Problem Discovery (ask one question at a time, wait for each answer)
13
14Ask these questions in order. Do not skip any.
15
16- Q1: "What problem does this project solve for its users?"
17- Q2: "Who are the primary users? What is their technical level?"
18- Q3: "What is the expected scale? (users per day, data volume, request rate)"
19
20## Phase 2 — Technical Constraints (only after Phase 1 is fully answered)
21
22- Q4: "What deployment environment will you use?"
23- Q5: "Do you have any technology stack requirements or preferences?"
24- Q6: "What are the non-negotiable requirements? (latency, uptime, compliance, budget)"
25
26## Phase 3 — Synthesis (only after all questions are answered)
27
281. Load 'assets/plan-template.md' for the output format
292. Fill in every section of the template using the gathered requirements
303. Present the completed plan to the user
314. Ask: "Does this plan accurately capture your requirements? What would you change?"
325. Iterate on feedback until the user confirms

Pattern 5: La Pipeline

Per compiti complessi, non puoi permetterti passaggi saltati o istruzioni ignorate. Il pattern Pipeline impone un flusso di lavoro sequenziale e vincolato, con checkpoint obbligatori.

Le istruzioni stesse fungono da definizione del flusso di lavoro. Implementando condizioni di blocco esplicite (come richiedere l'approvazione dell'utente prima di passare dalla generazione dei docstring all'assemblaggio finale), la Pipeline garantisce che un agente non possa bypassare un compito complesso e presentare un risultato finale non convalidato.

Questo pattern utilizza tutte le directory opzionali, caricando diversi file di riferimento e template solo nel passaggio specifico in cui sono necessari, mantenendo pulita la finestra di contesto.

In questo esempio di pipeline di documentazione, nota le condizioni di blocco esplicite. All'agente è esplicitamente vietato passare alla fase di assemblaggio finché l'utente non conferma i docstring generati nel passaggio precedente:

1# skills/doc-pipeline/SKILL.md
2---
3name: doc-pipeline
4description: Generates API documentation from Python source code through a multi-step pipeline. Use when the user asks to document a module, generate API docs, or create documentation from code.
5metadata:
6  pattern: pipeline
7  steps: "4"
8---
9
10You are running a documentation generation pipeline. Execute each step in order. Do NOT skip steps or proceed if a step fails.
11
12## Step 1 — Parse & Inventory
13Analyze the user's Python code to extract all public classes, functions, and constants. Present the inventory as a checklist. Ask: "Is this the complete public API you want documented?"
14
15## Step 2 — Generate Docstrings
16For each function lacking a docstring:
17- Load 'references/docstring-style.md' for the required format
18- Generate a docstring following the style guide exactly
19- Present each generated docstring for user approval
20Do NOT proceed to Step 3 until the user confirms.
21
22## Step 3 — Assemble Documentation
23Load 'assets/api-doc-template.md' for the output structure. Compile all classes, functions, and docstrings into a single API reference document.
24
25## Step 4 — Quality Check
26Review against 'references/quality-checklist.md':
27- Every public symbol documented
28- Every parameter has a type and description
29- At least one usage example per function
30Report results. Fix issues before presenting the final document.

Scegliere il pattern giusto per la skill dell'agente

Ogni pattern risponde a una domanda diversa. Usa questo albero decisionale per trovare quello giusto per il tuo caso d'uso:

E infine, i pattern si compongono

Questi pattern non si escludono a vicenda. Si compongono.

Una skill di tipo Pipeline può includere un passaggio di tipo Reviewer alla fine per ricontrollare il proprio lavoro. Un Generator può basarsi su Inversion all'inizio per raccogliere le variabili necessarie prima di riempire il template. Grazie a 𝚂𝚔𝚒𝚕𝚕𝚃𝚘𝚘𝚕𝚜𝚎𝚝 di ADK e alla divulgazione progressiva, il tuo agente spende token di contesto solo per i pattern esatti di cui ha bisogno in fase di esecuzione.

Smetti di cercare di infilare istruzioni complesse e fragili in un singolo prompt di sistema. Suddividi i tuoi flussi di lavoro, applica il pattern strutturale giusto e costruisci agenti affidabili.

Inizia oggi

Le specifiche per le Agent Skills sono open-source e supportate nativamente in ADK. Sai già come impacchettare il formato. Ora sai come progettare il contenuto. Costruisci agenti più intelligenti con Google Agent Development Kit.