​

Skills (OpenClaw)

​

Posizioni e precedenza

1. Cartelle di skill extra: configurate con skills.load.extraDirs
2. Skills incluse: fornite con l’installazione (pacchetto npm o OpenClaw.app)
3. Skills gestite/locali: ~/.openclaw/skills
4. Skills agente personali: ~/.agents/skills
5. Skills agente del progetto: <workspace>/.agents/skills
6. Skills del workspace: <workspace>/skills

​

Skills per agente vs condivise

• Le Skills per agente si trovano in <workspace>/skills solo per quell’agente.
• Le Skills agente del progetto si trovano in <workspace>/.agents/skills e si applicano a quel workspace prima della normale cartella skills/ del workspace.
• Le Skills agente personali si trovano in ~/.agents/skills e si applicano a tutti i workspace su quella macchina.
• Le Skills condivise si trovano in ~/.openclaw/skills (gestite/locali) e sono visibili a tutti gli agenti sulla stessa macchina.
• Le Cartelle condivise possono anche essere aggiunte tramite skills.load.extraDirs (precedenza minima) se vuoi un pacchetto di skill comune usato da più agenti.

​

Allowlist delle skill per agente

• Posizione/precedenza decide quale copia di una skill con lo stesso nome prevale.
• Le allowlist dell’agente decidono quali skill visibili un agente può effettivamente usare.

{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // eredita github, weather
      { id: "docs", skills: ["docs-search"] }, // sostituisce i valori predefiniti
      { id: "locked-down", skills: [] }, // nessuna skill
    ],
  },
}

• Ometti agents.defaults.skills per avere skill senza restrizioni per impostazione predefinita.
• Ometti agents.list[].skills per ereditare agents.defaults.skills.
• Imposta agents.list[].skills: [] per non avere skill.
• Una lista non vuota in agents.list[].skills è l’insieme finale per quell’agente; non viene unita ai valori predefiniti.

​

Plugin + skill

​

ClawHub (installazione + sincronizzazione)

• Installa una skill nel tuo workspace:
  • openclaw skills install <skill-slug>
• Aggiorna tutte le skill installate:
  • openclaw skills update --all
• Sincronizza (scansione + pubblicazione aggiornamenti):
  • clawhub sync --all

​

Note di sicurezza

• Tratta le skill di terze parti come codice non attendibile. Leggile prima di abilitarle.
• Preferisci esecuzioni sandboxed per input non attendibili e strumenti rischiosi. Vedi Sandboxing.
• Il rilevamento delle skill nel workspace e nelle directory extra accetta solo radici di skill e file SKILL.md il cui realpath risolto rimane all’interno della radice configurata.
• Le installazioni di dipendenze delle skill supportate dal Gateway (skills.install, onboarding e UI delle impostazioni Skills) eseguono lo scanner integrato per codice pericoloso prima di eseguire i metadati di installazione. I rilevamenti critical bloccano per impostazione predefinita a meno che il chiamante non imposti esplicitamente l’override pericoloso; i rilevamenti sospetti invece generano solo un avviso.
• openclaw skills install <slug> è diverso: scarica una cartella skill da ClawHub nel workspace e non usa il percorso dei metadati di installazione sopra descritto.
• skills.entries.*.env e skills.entries.*.apiKey iniettano segreti nel processo host per quel turno dell’agente (non nella sandbox). Tieni i segreti fuori dai prompt e dai log.
• Per un modello di minaccia più ampio e checklist, vedi Sicurezza.

​

Formato (compatibile con AgentSkills + Pi)

---
name: image-lab
description: Generate or edit images via a provider-backed image workflow
---

• Seguiamo la specifica AgentSkills per layout/intento.
• Il parser usato dall’agente incorporato supporta solo chiavi frontmatter su singola riga.
• metadata deve essere un oggetto JSON su singola riga.
• Usa {baseDir} nelle istruzioni per fare riferimento al percorso della cartella della skill.
• Chiavi frontmatter facoltative:
  • homepage — URL mostrato come “Website” nella UI Skills di macOS (supportato anche tramite metadata.openclaw.homepage).
  • user-invocable — true|false (predefinito: true). Quando true, la skill è esposta come comando slash utente.
  • disable-model-invocation — true|false (predefinito: false). Quando true, la skill è esclusa dal prompt del modello (rimane comunque disponibile tramite invocazione utente).
  • command-dispatch — tool (facoltativo). Quando impostato su tool, il comando slash bypassa il modello e viene inviato direttamente a uno strumento.
  • command-tool — nome dello strumento da invocare quando è impostato command-dispatch: tool.
  • command-arg-mode — raw (predefinito). Per il dispatch allo strumento, inoltra la stringa raw degli argomenti allo strumento (senza parsing core). Lo strumento viene invocato con i parametri: { command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }.

​

Gating (filtri al momento del caricamento)

---
name: image-lab
description: Generate or edit images via a provider-backed image workflow
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
        "primaryEnv": "GEMINI_API_KEY",
      },
  }
---

• always: true — include sempre la skill (salta gli altri gate).
• emoji — emoji facoltativa usata dalla UI Skills di macOS.
• homepage — URL facoltativo mostrato come “Website” nella UI Skills di macOS.
• os — elenco facoltativo di piattaforme (darwin, linux, win32). Se impostato, la skill è idonea solo su questi OS.
• requires.bins — elenco; ciascuno deve esistere in PATH.
• requires.anyBins — elenco; almeno uno deve esistere in PATH.
• requires.env — elenco; la variabile env deve esistere oppure essere fornita nella configurazione.
• requires.config — elenco di percorsi openclaw.json che devono essere truthy.
• primaryEnv — nome della variabile env associata a skills.entries.<name>.apiKey.
• install — array facoltativo di specifiche di installazione usate dalla UI Skills di macOS (brew/node/go/uv/download).

• requires.bins viene controllato sull’host al momento del caricamento della skill.
• Se un agente è sandboxed, il binario deve esistere anche dentro il container. Installalo tramite agents.defaults.sandbox.docker.setupCommand (o un’immagine personalizzata). setupCommand viene eseguito una volta dopo la creazione del container. Le installazioni di pacchetti richiedono anche uscita di rete, un root FS scrivibile e un utente root nella sandbox. Esempio: la skill summarize (skills/summarize/SKILL.md) richiede la CLI summarize nel container sandbox per poter essere eseguita lì.

---
name: gemini
description: Use Gemini CLI for coding assistance and Google search lookups.
metadata:
  {
    "openclaw":
      {
        "emoji": "♊️",
        "requires": { "bins": ["gemini"] },
        "install":
          [
            {
              "id": "brew",
              "kind": "brew",
              "formula": "gemini-cli",
              "bins": ["gemini"],
              "label": "Install Gemini CLI (brew)",
            },
          ],
      },
  }
---

• Se sono elencati più installer, il gateway sceglie una singola opzione preferita (brew quando disponibile, altrimenti node).
• Se tutti gli installer sono download, OpenClaw elenca ogni voce in modo che tu possa vedere gli artifact disponibili.
• Le specifiche dell’installer possono includere os: ["darwin"|"linux"|"win32"] per filtrare le opzioni in base alla piattaforma.
• Le installazioni node rispettano skills.install.nodeManager in openclaw.json (predefinito: npm; opzioni: npm/pnpm/yarn/bun). Questo influisce solo sulle installazioni delle skill; il runtime del Gateway dovrebbe comunque essere Node (Bun non è consigliato per WhatsApp/Telegram).
• La selezione dell’installer supportata dal Gateway è basata sulle preferenze, non solo su node: quando le specifiche di installazione mescolano tipi diversi, OpenClaw preferisce Homebrew quando skills.install.preferBrew è abilitato ed esiste brew, poi uv, poi il node manager configurato, poi altri fallback come go o download.
• Se ogni specifica di installazione è download, OpenClaw mostra tutte le opzioni di download invece di comprimerle in un solo installer preferito.
• Installazioni Go: se go non è presente e brew è disponibile, il gateway installa prima Go tramite Homebrew e imposta GOBIN su bin di Homebrew quando possibile.
• Installazioni download: url (obbligatorio), archive (tar.gz | tar.bz2 | zip), extract (predefinito: automatico quando viene rilevato un archivio), stripComponents, targetDir (predefinito: ~/.openclaw/tools/<skillKey>).

​

Override di configurazione (~/.openclaw/openclaw.json)

{
  skills: {
    entries: {
      "image-lab": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // o stringa plaintext
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
        config: {
          endpoint: "https://example.invalid",
          model: "nano-pro",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

• enabled: false disabilita la skill anche se è inclusa/installata.
• env: iniettato solo se la variabile non è già impostata nel processo.
• apiKey: scorciatoia per skill che dichiarano metadata.openclaw.primaryEnv. Supporta una stringa plaintext o un oggetto SecretRef ({ source, provider, id }).
• config: contenitore facoltativo per campi personalizzati per skill; le chiavi personalizzate devono stare qui.
• allowBundled: allowlist facoltativa solo per le Skills incluse. Se impostata, solo le Skills incluse presenti nell’elenco sono idonee (le skill gestite/workspace non sono interessate).

​

Iniezione dell’ambiente (per esecuzione dell’agente)

1. Legge i metadati della skill.
2. Applica eventuali skills.entries.<key>.env o skills.entries.<key>.apiKey a process.env.
3. Costruisce il prompt di sistema con le skill idonee.
4. Ripristina l’ambiente originale al termine dell’esecuzione.

​

Snapshot della sessione (prestazioni)

​

Nodi remoti macOS (gateway Linux)

​

Watcher delle skill (aggiornamento automatico)

{
  skills: {
    load: {
      watch: true,
      watchDebounceMs: 250,
    },
  },
}

​

Impatto sui token (elenco delle skill)

• Overhead di base (solo quando ≥1 skill): 195 caratteri.
• Per skill: 97 caratteri + la lunghezza dei valori XML-escaped di <name>, <description> e <location>.

total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped))

• L’escaping XML espande & < > " ' in entità (&, <, ecc.), aumentando la lunghezza.
• Il numero di token varia in base al tokenizer del modello. Una stima approssimativa in stile OpenAI è ~4 caratteri/token, quindi 97 caratteri ≈ 24 token per skill più le lunghezze effettive dei campi.

​

Ciclo di vita delle Skills gestite

​

Riferimento della configurazione

​

Cerchi altre skill?

​

Correlati

• Creazione di Skills — creazione di skill personalizzate
• Configurazione Skills — riferimento della configurazione delle skill
• Comandi slash — tutti i comandi slash disponibili
• Plugin — panoramica del sistema di plugin