Estendere la modalità Agente con le competenze

Le competenze consentono di migliorare le funzionalità della modalità agente con competenze specializzate e workflow personalizzati. Si basano sullo standard aperto delle competenze degli agenti.

A differenza dei file AGENTS.md, le competenze rappresentano competenze on demand. Questa struttura consente alla modalità Agent di mantenere un numero elevato di funzionalità specializzate, ad esempio la migrazione tra versioni specifiche della libreria o l'adattamento di un elemento componibile a diverse dimensioni dello schermo, senza ingombrare la finestra contestuale immediata del modello.

Il modello decide autonomamente quando utilizzare una competenza in base alla richiesta e alla descrizione della competenza. Quando viene identificata una competenza pertinente, il modello recupera dinamicamente le istruzioni e le risorse complete necessarie per completare l'attività.

Per attivare una competenza on demand, chiedi all'agente di eseguire un'attività pertinente alla competenza. Puoi anche inserire @ nella casella di immissione per attivare una competenza specifica.

Vantaggi principali

  • Competenze condivise: impacchetta workflow complessi (ad esempio il processo di revisione delle richieste di pull di un team specifico) in una cartella dedicata che chiunque può utilizzare.
  • Workflow ripetibili: assicurati che le attività complesse in più passaggi vengano eseguite in modo coerente fornendo istruzioni standard.
  • Raggruppamento delle risorse: includi script, modelli o dati di esempio insieme alle istruzioni in modo che l'agente abbia tutto ciò di cui ha bisogno in un unico posto.
  • Utilizzo efficiente della finestra contestuale: per salvare i token di contesto, inizialmente vengono caricati solo i metadati della competenza (nome e descrizione). Il file SKILL.md completo viene caricato solo al momento dell'attivazione. I file di supporto nelle directory references/, scripts/ o assets/ vengono caricati nel contesto solo quando l'agente ne ha bisogno in modo specifico.

Creare competenze personalizzate

L'agente cerca le competenze a partire dalle directory .skills/ o .agent/skills/ che si trovano nella root del progetto. Per creare una competenza personalizzata:

  1. Crea una directory per la competenza (ad esempio, my-new-skill/).
  2. Crea un file SKILL.md (con distinzione tra maiuscole e minuscole) all'interno della nuova directory.

Le competenze devono rispettare le seguenti regole:

  • Una directory per competenza: ogni competenza deve avere una directory univoca che includa un file SKILL.md e eventuali risorse aggiuntive.
  • Nesting: tutte le competenze devono trovarsi nella directory .skills/ o .agent/skills/ nella root del progetto. Tuttavia, puoi utilizzare le sottodirectory per una migliore organizzazione (ad esempio, skills/ui-flows/<skill name>/SKILL.md o skills/testing/<skill name>/SKILL.md).
  • Ambito: al momento sono supportate solo le competenze che si trovano all'interno della codebase del progetto.

Il file SKILL.md utilizza un blocco YAML per i metadati e Markdown standard per le istruzioni.

  • name: un identificatore univoco per la competenza. Deve corrispondere al nome della directory.
  • description: una spiegazione chiara di cosa fa la competenza e quando l'agente deve utilizzarla.
  • Corpo: il corpo Markdown sotto il blocco YAML contiene le istruzioni che guidano il comportamento dell'agente quando la competenza è attiva.
---
name: skill-name
description: A description of what this skill does and when to use it.
metadata:
  author: example-org
  version: "1.0"
---

Skill content

Linee guida per la formattazione

  • Nome: massimo 64 caratteri (solo lettere minuscole, numeri e trattini).
  • Descrizione: massimo 1024 caratteri.
  • Contenuto del corpo: punta a 10.000-20.000 caratteri (~2500-5000 token). Se le tue istruzioni superano questo limite, valuta la possibilità di spostare la documentazione dettagliata in un file di risorse come descritto in Directory di competenze facoltative.

Directory di competenze facoltative

Per mantenere il file SKILL.md conciso e modulare, puoi includere risorse aggiuntive nelle seguenti directory facoltative all'interno della cartella della competenza:

  • scripts/: contiene codice eseguibile (ad esempio Python o Bash) che l'agente può eseguire.
  • references/: contiene documentazione tecnica dettagliata, riferimenti API o guide specifiche per il dominio.
  • assets/: contiene risorse statiche come modelli di documenti, diagrammi dell'interfaccia utente o schemi JSON.

Quando fai riferimento a questi file nelle istruzioni SKILL.md, utilizza i percorsi relativi dalla root della competenza. Ad esempio: Run the script at scripts/cleanup.py.