Competenze dell'agente

Le skill degli agenti permettono a OpenCode di individuare istruzioni riutilizzabili dal tuo repo o dalla home directory. Le skill vengono caricate on-demand tramite lo strumento nativo skill: gli agenti vedono le skill disponibili e possono caricarne il contenuto completo quando serve.

---

Posizione dei file

Crea una cartella per ogni nome di skill e metti un SKILL.md al suo interno. OpenCode cerca in queste posizioni:

• Config di progetto: .opencode/skills/<name>/SKILL.md
• Config globale: ~/.config/opencode/skills/<name>/SKILL.md
• Progetto compatibile con Claude: .claude/skills/<name>/SKILL.md
• Globale compatibile con Claude: ~/.claude/skills/<name>/SKILL.md
• Progetto compatibile con agent: .agents/skills/<name>/SKILL.md
• Globale compatibile con agent: ~/.agents/skills/<name>/SKILL.md

---

Discovery

Per i percorsi locali al progetto, OpenCode risale dalla directory di lavoro corrente finche’ non raggiunge il worktree git. Carica qualsiasi skills/*/SKILL.md corrispondente in .opencode/ e qualsiasi .claude/skills/*/SKILL.md o .agents/skills/*/SKILL.md corrispondente lungo il percorso.

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

---

Frontmatter

Ogni SKILL.md deve iniziare con frontmatter YAML. Sono riconosciuti solo questi campi:

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

I campi di frontmatter sconosciuti vengono ignorati.

---

Validazione nomi

name deve:

• Essere lungo 1-64 caratteri
• Essere alfanumerico minuscolo con separatori - singoli
• Non iniziare o finire con -
• Non contenere -- consecutivi
• Corrispondere al nome della directory che contiene SKILL.md

Regex equivalente:

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

---

Regole di lunghezza

description deve essere lunga 1-1024 caratteri. Tieni la descrizione abbastanza specifica da permettere all’agente di scegliere correttamente.

---

Esempio

Crea .opencode/skills/git-release/SKILL.md cosi’:

---
name: git-release
description: Create consistent releases and changelogs
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
  workflow: github
---

## What I do

- Draft release notes from merged PRs
- Propose a version bump
- Provide a copy-pasteable `gh release create` command

## When to use me

Use this when you are preparing a tagged release.
Ask clarifying questions if the target versioning scheme is unclear.

---

Descrizione strumento

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

<available_skills>
  <skill>
    <name>git-release</name>
    <description>Create consistent releases and changelogs</description>
  </skill>
</available_skills>

L’agente carica una skill chiamando lo strumento:

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

---

Permessi

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

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

Permesso	Comportamento
allow	La skill viene caricata immediatamente
deny	Skill nascosta all’agente, accesso negato
ask	L’utente viene invitato ad approvare il load

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

---

Sovrascrittura per agente

Dai ad agenti specifici permessi diversi dai default 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 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 e’ disabilitato, la sezione <available_skills> viene omessa completamente.

---

Risoluzione problemi

Se una skill non compare:

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 unici in tutte le posizioni
4. Controlla i permessi: le skill con deny vengono nascoste agli agenti