Skills

Skill 是可发现、可调用的指令包。它在需要时加载完整正文，不会把所有 Skill 内容预先塞入每次请求。

存放形式

项目 Skill 可以使用目录形式:

file:///path/to/workspace/.agents/skills/review/SKILL.md

SKILL.md 同目录的其他文件是 Skill 资源，不会被扫描成独立 Skill。也可以在 skills 目录中使用单个 Markdown 文件。

个人 Skill 使用 file:///Users/you/.agents/skills/。

必需信息

Skill 必须提供明确 description，否则不会出现在发现和调用清单中。还可以配置:

• when_to_use
• arguments
• needs
• user_invocable
• disable-model-invocation

needs 用于在 Skill 加载时一起注入依赖知识，而不是永久增加 system prompt。

调用方式

用户可调用 Skill 出现在 Composer 的 / 列表。允许模型调用的 Skill 出现在按需 skill 工具中。

disable-model-invocation 可以把 Skill 限制为仅用户显式触发。user_invocable 可以控制它是否进入用户调用面。

参数

Skill 支持 $ARGUMENTS、$1 到 $n 和 $ARGUMENTS[i]。没有占位符时，参数会附加到加载正文末尾。

运行边界

• 未信任 Workspace 的项目 Skill 不进入可调用清单。
• 同一个 Session 中，相同 Skill 和相同参数不能重复加载。
• Skill 调用 Skill 的递归深度上限是 3。
• Skill 只能指导 Agent，不能覆盖角色权限、Safety 或 Approval。