---
title: "Competenze dell'agente"
description: "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.

---

## 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:

```text
^[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':

```markdown
---
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:

```xml
<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`:

```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):

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

**Per agenti integrati** (in `opencode.json`):

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

---

## Disabilitare skill

Disabilita completamente le skill per agenti che non dovrebbero usarle:

**Per agenti personalizzati**:

```yaml
---
tools:
  skill: false
---
```

**Per agenti integrati**:

```json
{
  "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