Salta ai contenuti
OpenCode
app.header.homeapp.header.docs

Competenze dell'agente

Definisci comportamenti riutilizzabili tramite definizioni in SKILL.md

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.

Posiziona i 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

Comprendere la 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.

Scrivi il 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.

Valida i 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]+)*$

Rispetta le regole di lunghezza

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

Usa un 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.

Riconoscere la descrizione dello 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" })

Configura i 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"
    }
  }
}
PermessoComportamento
allowLa skill viene caricata immediatamente
denySkill nascosta all’agente, accesso negato
askL’utente viene invitato ad approvare il load

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

Sovrascrivi 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"
        }
      }
    }
  }
}

Disabilita 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 e’ disabilitato, la sezione <available_skills> viene omessa completamente.

Risoluzione problemi di caricamento

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