Skill dell'agente

Le skill dell’agente consentono a OpenCode di scoprire istruzioni riutilizzabili dal tuo repository o directory home. Le skill vengono caricate su richiesta tramite lo strumento nativo skill — gli agenti vedono le skill disponibili e possono caricare il contenuto completo quando necessario.

---

Posiziona i file

Crea una cartella per nome skill e inserisci un SKILL.md all’interno. OpenCode cerca queste posizioni:

• Configurazione del progetto: .opencode/skill/<name>/SKILL.md
• Configurazione globale: ~/.config/opencode/skill/<name>/SKILL.md
• Compatibile Claude del progetto: .claude/skills/<name>/SKILL.md
• Compatibile Claude globale: ~/.claude/skills/<name>/SKILL.md

---

Comprendere la scoperta

Per i percorsi locali del progetto, OpenCode risale dalla tua directory di lavoro corrente fino a raggiungere l’albero di lavoro git. Carica qualsiasi skill/*/SKILL.md corrispondente in .opencode/ e qualsiasi .claude/skills/*/SKILL.md corrispondente lungo il percorso.

Le definizioni globali vengono anche caricate da ~/.config/opencode/skill/*/SKILL.md e ~/.claude/skills/*/SKILL.md.

---

Scrivere il frontmatter

Ogni SKILL.md deve iniziare con YAML frontmatter. Solo questi campi sono riconosciuti:

• name (obbligatorio)
• description (obbligatorio)
• license (opzionale)
• compatibility (opzionale)
• metadata (opzionale, mappa stringa a stringa)

I campi frontmatter sconosciuti vengono ignorati.

---

Convalidare i nomi

name deve:

• Avere 1–64 caratteri
• Essere alfanumerico minuscolo con separatori di trattino singolo
• Non iniziare o finire con -
• Non contenere -- consecutivi
• Corrispondere al nome della directory che contiene SKILL.md

Espressione regex equivalente:

^[a-z0-9]+(-[a-z0-9]+)*$

---

Seguire le regole di lunghezza

description deve avere 1-1024 caratteri. Mantienila abbastanza specifica affinche l’agente possa scegliere correttamente.

---

Usare un esempio

Crea .opencode/skill/git-release/SKILL.md come questo:

---
name: git-release
description: Crea release e changelog coerenti
license: MIT
compatibility: opencode
metadata:
  audience: manutentori
  workflow: github
---

## Cosa faccio

- Redigere note di release dalle PR unite
- Proporre un incremento di versione
- Fornire un comando `gh release create` copiabile

## Quando usarmi

Usalo quando stai preparando una release taggata.
Fai domande di chiarimento se lo schema di versionamento di destinazione non e chiaro.

---

Riconoscere la descrizione dello strumento

OpenCode elenca le skill disponibili nella descrizione dello strumento skill. Ogni voce include il nome e la descrizione della skill:

<available_skills>
  <skill>
    <name>git-release</name>
    <description>Crea release e changelog coerenti</description>
  </skill>
</available_skills>

L’agente carica una skill chiamando lo strumento:

skill({ name: "git-release" })

---

Configurare i permessi

Controlla a quali skill possono accedere gli agenti usando permessi basati su pattern in opencode.json:

{
  "permission": {
    "skill": {
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask",
      "*": "allow"
    }
  }
}

Permission	Comportamento
allow	La skill viene caricata immediatamente
deny	Skill nascosta dall’agente, accesso rifiutato
ask	Utente richiesto di approvare prima del caricamento

I pattern supportano caratteri jolly: internal-* corrisponde a internal-docs, internal-tools, ecc.

---

Sostituire per agente

Dai ad agenti specifici permessi diversi dai valori predefiniti globali.

Per agenti personalizzati (nel frontmatter dell’agente):

---
permission:
  skill:
    "documents-*": "allow"
---

Per agenti integrati (in opencode.json):

{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "internal-*": "allow"
        }
      }
    }
  }
}

---

Disabilitare lo strumento skill

Disabilita completamente le skill per agenti che non dovrebbero usarle:

Per agenti personalizzati:

---
tools:
  skill: false
---

Per agenti integrati:

{
  "agent": {
    "plan": {
      "tools": {
        "skill": false
      }
    }
  }
}

Quando disabilitato, la sezione <available_skills> viene omessa completamente.

---

Risolvere i problemi di caricamento

Se una skill non appare:

1. Verifica che SKILL.md sia scritto in maiuscolo
2. Controlla che il frontmatter includa name e description
3. Assicurati che i nomi delle skill siano univoci in tutte le posizioni
4. Controlla i permessi — le skill con deny sono nascoste agli agenti