Compétences d'Agent

Les compétences d'agent permettent à Dropstone de découvrir des instructions réutilisables depuis votre dépôt ou répertoire personnel. Les compétences sont chargées à la demande via l'outil intégré skill : les agents voient quelles compétences sont disponibles et peuvent charger le contenu complet quand l'une d'elles correspond à la tâche.

Placer les fichiers

Créez un dossier par nom de compétence et placez un SKILL.md à l'intérieur. Dropstone recherche dans ces emplacements :

• Configuration du projet : .dropstone/skills/<name>/SKILL.md
• Configuration globale : ~/.config/dropstone/skills/<name>/SKILL.md
• Compatible Claude du projet : .claude/skills/<name>/SKILL.md
• Compatible Claude global : ~/.claude/skills/<name>/SKILL.md
• Compatible agent du projet : .agents/skills/<name>/SKILL.md
• Compatible agent global : ~/.agents/skills/<name>/SKILL.md

Comprendre la découverte

Pour les chemins locaux au projet, Dropstone remonte depuis votre répertoire de travail actuel jusqu'à atteindre la racine du dépôt git. Il charge tous les skills/*/SKILL.md correspondants dans .dropstone/ et tous les .claude/skills/*/SKILL.md ou .agents/skills/*/SKILL.md correspondants en chemin.

Les définitions globales sont également chargées depuis ~/.config/dropstone/skills/*/SKILL.md, ~/.claude/skills/*/SKILL.md et ~/.agents/skills/*/SKILL.md.

Écrire le frontmatter

Chaque SKILL.md doit commencer par un frontmatter YAML. Seuls ces champs sont reconnus :

• name (obligatoire)
• description (obligatoire)
• license (optionnel)
• compatibility (optionnel)
• metadata (optionnel, map chaîne-à-chaîne)

Les champs frontmatter inconnus sont ignorés.

Valider les noms

name doit :

• Faire 1–64 caractères
• Être alphanumériques minuscules avec des séparateurs tirets simples
• Ne pas commencer ou finir par -
• Ne pas contenir de -- consécutifs
• Correspondre au nom du répertoire qui contient SKILL.md

Expression régulière équivalente :

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

Respecter les règles de longueur

description doit faire 1-1024 caractères. Gardez-la assez spécifique pour que l'agent choisisse correctement.

Utiliser un exemple

Créez .dropstone/skills/git-release/SKILL.md comme ceci :

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

Reconnaître la description de l'outil

Dropstone liste les compétences disponibles dans la description de l'outil skill. Chaque entrée inclut le nom et la description de la compétence :

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

L'agent charge une compétence en appelant l'outil :

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

Configurer les permissions

Contrôlez quelles compétences les agents peuvent accéder en utilisant des permissions basées sur des motifs dans dropstone.json :

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

Les motifs supportent les caractères génériques : internal-* correspond à internal-docs, internal-tools, etc.

Remplacer par agent

Donnez à des agents spécifiques des permissions différentes des valeurs par défaut globales.

Pour les agents personnalisés (dans le frontmatter de l'agent) :

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

Pour les agents intégrés (dans dropstone.json) :

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

Désactiver l'outil skill

Désactivez complètement les compétences pour les agents qui ne devraient pas les utiliser :

Pour les agents personnalisés :

---
tools:
  skill: false
---

Pour les agents intégrés :

{
  "agent": {
    "plan": {
      "tools": {
        "skill": false
      }
    }
  }
}

Quand désactivé, la section <available_skills> est entièrement omise.

Dépanner le chargement

Si une compétence n'apparaît pas :

1. Vérifiez que SKILL.md est écrit en majuscules
2. Vérifiez que le frontmatter inclut name et description
3. Assurez-vous que les noms de compétences sont uniques dans tous les emplacements
4. Vérifiez les permissions : les compétences avec deny sont cachées aux agents