Agent Skills

Skills 把可复用行为写在一个目录的 SKILL.md 中。Agent 先看到名称和描述，在需要时通过原生 skill 工具读取完整内容，默认不是把所有正文预先塞进上下文。

发现位置

项目发现会从当前工作目录向上走到 Git worktree，查找沿途匹配位置；全局目录也参与。需要避免不同位置的 Skill 重名，官方排障要求名称唯一，没有在本页承诺同名冲突的固定选择规则。

Claude 兼容目录可以通过兼容开关关闭；不要将发现列表理解为无条件读取所有目录。

Frontmatter

必须包含 name 和 description。可选字段是 license、compatibility、metadata，其中 metadata 是字符串到字符串的映射；未知字段被忽略。

name 必须满足：

• 长度 1–64 个字符。
• 只使用小写字母、数字和单个连字符分隔。
• 不能以连字符开头或结束，不能包含连续 --。
• 与包含 SKILL.md 的目录名一致。

对应模式为 ^[a-z0-9]+(-[a-z0-9]+)*$。description 长度为 1–1024 个字符，应明确说明什么任务适合调用它。

加载与权限

可用 Skills 以名称和描述列入 skill 工具说明，Agent 通过 skill({ name: "..." }) 请求正文。

在 permission.skill 中按名称匹配：

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

allow 直接加载，ask 加载前询问，deny 将 Skill 对 Agent 隐藏并拒绝访问。Agent 自己的权限可以覆盖普通全局规则，具体合并见权限。

禁用工具与旧示例

官方 Skills 页仍用 tools.skill: false 演示彻底禁用，禁用后不再提供 available_skills 列表。Permissions 专门页已将 tools 布尔配置标为兼容用法；新配置应优先通过角色的 permission.skill 设置 deny，并验证实际可见性。

“某个 Skill 被拒绝”与“整个 skill 工具不再提供”是不同粒度，排查时分别检查，不将两者混为一谈。

找不到 Skill 时

依次确认文件名为大写 SKILL.md、必填 frontmatter 存在、名称符合目录与字符规则、不同发现位置没有同名条目，以及权限没有将它隐藏。还要确认启动目录能够发现对应项目路径。