Dropstone Docs

代理技能

透過 SKILL.md 定義來定義可重複使用的行為

代理技能讓 Dropstone 從你的儲存庫或主目錄中發現可重複使用的指令。 技能透過內建的 skill 工具按需載入：代理可以看到哪些技能可用，並在符合任務時載入完整內容。

放置檔案

為每個技能名稱建立一個資料夾，並在其中放入 SKILL.md。 Dropstone 搜尋這些位置：

  • 專案設定：.dropstone/skills/<name>/SKILL.md
  • 全域設定：~/.config/dropstone/skills/<name>/SKILL.md
  • 專案 Claude 相容：.claude/skills/<name>/SKILL.md
  • 全域 Claude 相容：~/.claude/skills/<name>/SKILL.md
  • 專案代理相容：.agents/skills/<name>/SKILL.md
  • 全域代理相容：~/.agents/skills/<name>/SKILL.md

了解發現機制

對於專案本地路徑，Dropstone 從你的目前工作目錄向上走，直到到達 git worktree。 它會載入沿途 .dropstone/ 中任何符合的 skills/*/SKILL.md，以及任何符合的 .claude/skills/*/SKILL.md 或 .agents/skills/*/SKILL.md。

全域定義也會從 ~/.config/dropstone/skills/*/SKILL.md、~/.claude/skills/*/SKILL.md 和 ~/.agents/skills/*/SKILL.md 載入。

撰寫前置資料

每個 SKILL.md 必須以 YAML 前置資料開始。 只有這些欄位被識別：

  • name（必需）
  • description（必需）
  • license（選用）
  • compatibility（選用）
  • metadata（選用，字串對字串的對應）

未知的前置資料欄位會被忽略。

驗證名稱

name 必須：

  • 為 1–64 個字元
  • 為小寫英數字，以單個連字號分隔
  • 不以 - 開始或結束
  • 不包含連續的 --
  • 符合包含 SKILL.md 的目錄名稱

等效的正規表達式：

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

遵循長度規則

description 必須為 1-1024 個字元。 保持足夠具體，以便代理能正確選擇。

使用範例

建立 .dropstone/skills/git-release/SKILL.md，如下所示：

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

識別工具描述

Dropstone 在 skill 工具描述中列出可用的技能。 每個項目包括技能名稱和描述：

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

代理透過呼叫工具來載入技能：

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

設定權限

使用 dropstone.json 中基於模式的權限來控制代理可以存取哪些技能：

{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}
權限行為
allow技能立即載入
deny技能對代理隱藏，存取被拒絕
ask載入前提示使用者批准

模式支援萬用字元：internal-* 符合 internal-docs、internal-tools 等。

按代理覆蓋

給予特定代理不同於全域預設值的權限。

對於自訂代理（在代理前置資料中）：

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

對於內建代理（在 dropstone.json 中）：

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

停用技能工具

完全停用不應使用技能的代理的技能：

對於自訂代理：

---
tools:
  skill: false
---

對於內建代理：

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

停用時，<available_skills> 部分會完全省略。

疑難排解載入

如果技能未顯示：

  1. 驗證 SKILL.md 拼寫為全大寫
  2. 檢查前置資料是否包含 name 和 description
  3. 確保技能名稱在所有位置中是唯一的
  4. 檢查權限：具有 deny 的技能對代理隱藏
Ctrl+I