Dropstone Docs

Competenze dell'Agente

Definisci comportamenti riutilizzabili tramite definizioni SKILL.md

Le competenze dell'agente consentono a Dropstone di scoprire istruzioni riutilizzabili dal tuo repository o dalla directory home. Le competenze vengono caricate su richiesta tramite lo strumento skill integrato: gli agenti vedono quali competenze sono disponibili e possono caricare il contenuto completo quando una corrisponde all'attività.

Posiziona i file

Crea una cartella per ogni nome di competenza e inserisci un SKILL.md al suo interno. Dropstone cerca in questi percorsi:

  • Configurazione del progetto: .dropstone/skills/<name>/SKILL.md
  • Configurazione globale: ~/.config/dropstone/skills/<name>/SKILL.md
  • Compatibile con Claude del progetto: .claude/skills/<name>/SKILL.md
  • Compatibile con Claude globale: ~/.claude/skills/<name>/SKILL.md
  • Compatibile con agente del progetto: .agents/skills/<name>/SKILL.md
  • Compatibile con agente globale: ~/.agents/skills/<name>/SKILL.md

Comprendi la scoperta

Per i percorsi locali del progetto, Dropstone risale dalla tua directory di lavoro corrente fino a raggiungere il worktree git. Carica qualsiasi skills/*/SKILL.md corrispondente in .dropstone/ e qualsiasi .claude/skills/*/SKILL.md o .agents/skills/*/SKILL.md corrispondente lungo il percorso.

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

Scrivi il frontmatter

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

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

I campi frontmatter sconosciuti vengono ignorati.

Convalida i nomi

name deve:

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

Regex equivalente:

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

Segui le regole di lunghezza

description deve essere 1-1024 caratteri. Mantienila abbastanza specifica affinché l'agente possa scegliere correttamente.

Usa un esempio

Crea .dropstone/skills/git-release/SKILL.md così:

---
name: git-release
description: Create consistent releases and changelogs
license: MIT
compatibility: dropstone
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.

Riconosci la descrizione dello strumento

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

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

L'agente carica una competenza chiamando lo strumento:

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

Configura i permessi

Controlla quali competenze gli agenti possono accedere utilizzando i permessi basati su pattern in dropstone.json:

{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}
PermessoComportamento
allowLa competenza si carica immediatamente
denyCompetenza nascosta all'agente, accesso rifiutato
askL'utente viene richiesto per l'approvazione prima del caricamento

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

Sovrascrivi per agente

Assegna a specifici agenti permessi diversi dai valori predefiniti globali.

Per agenti personalizzati (nel frontmatter dell'agente):

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

Per agenti integrati (in dropstone.json):

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

Disabilita lo strumento skill

Disabilita completamente le competenze per gli 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.

Risolvi i problemi di caricamento

Se una competenza non viene visualizzata:

  1. Verifica che SKILL.md sia scritto in maiuscole
  2. Controlla che il frontmatter includa name e description
  3. Assicurati che i nomi delle competenze siano univoci in tutte le posizioni
  4. Controlla i permessi: le competenze con deny sono nascoste agli agenti
Ctrl+I