Dropstone Docs

Agent 技能

通过 SKILL.md 定义可复用的行为

Agent 技能让 Dropstone 从你的仓库或主目录中发现可复用的指令。 技能通过内置的 skill 工具按需加载：Agent 可以看到有哪些技能可用，并在某个技能与任务匹配时加载完整内容。

放置文件

每个技能名称创建一个文件夹，并在其中放置 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
  • 项目 Agent 兼容：.agents/skills/<name>/SKILL.md
  • 全局 Agent 兼容：~/.agents/skills/<name>/SKILL.md

理解发现机制

对于项目本地路径，Dropstone 会从当前工作目录向上遍历，直到到达 git 工作树。 它会沿途加载 .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 加载。

编写 frontmatter

每个 SKILL.md 必须以 YAML frontmatter 开头。 仅识别以下字段：

  • name（必填）
  • description（必填）
  • license（可选）
  • compatibility（可选）
  • metadata（可选，字符串到字符串的映射）

未知的 frontmatter 字段会被忽略。

验证名称

name 必须满足：

  • 长度为 1–64 个字符
  • 为小写字母数字，使用单个连字符分隔
  • 不能以 - 开头或结尾
  • 不能包含连续的 --
  • 与包含 SKILL.md 的目录名称匹配

等效正则表达式：

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

遵循长度规则

description 长度必须为 1-1024 个字符。 请确保描述足够具体，以便 Agent 能正确选择。

使用示例

创建如下所示的 .dropstone/skills/git-release/SKILL.md：

---
name: git-release
description: 创建一致的发布版本和变更日志
license: MIT
compatibility: dropstone
metadata:
  audience: maintainers
  workflow: github
---

## 我的功能

- 根据已合并的 PR 起草发布说明
- 建议版本号提升
- 提供可直接复制粘贴的 `gh release create` 命令

## 何时使用我

当你准备发布带标签的版本时使用我。
如果目标版本方案不明确，请提出澄清问题。

识别工具描述

Dropstone 会在 skill 工具描述中列出可用的技能。 每个条目包含技能名称和描述：

<available_skills>
  <skill>
    <name>git-release</name>
    <description>创建一致的发布版本和变更日志</description>
  </skill>
</available_skills>

Agent 通过调用工具来加载技能：

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

配置权限

使用 dropstone.json 中基于模式的权限来控制 Agent 可以访问哪些技能：

{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}
权限行为
allow技能立即加载
deny技能对 Agent 隐藏，访问被拒绝
ask加载前提示用户批准

模式支持通配符：internal-* 匹配 internal-docs、internal-tools 等。

按 Agent 覆盖

为特定 Agent 提供与全局默认值不同的权限。

对于自定义 Agent（在 Agent frontmatter 中）：

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

对于内置 Agent（在 dropstone.json 中）：

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

禁用 skill 工具

为不应使用技能的 Agent 完全禁用技能：

对于自定义 Agent：

---
tools:
  skill: false
---

对于内置 Agent：

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

禁用后，<available_skills> 部分会被完全省略。

排查加载问题

如果技能未显示：

  1. 确认 SKILL.md 全部使用大写字母拼写
  2. 检查 frontmatter 是否包含 name 和 description
  3. 确保所有位置的技能名称唯一
  4. 检查权限：带有 deny 的技能对 Agent 隐藏
Ctrl+I