Skill
Skill 是什么、放在哪里、如何安装和使用,以及如何启用和停用。
Skill 是一个包含 SKILL.md 的目录:一份说明某类任务怎么做的指南,可以附带参考资料和脚本。模型看到 Skill 的目录(名字和说明),在任务需要时读取对应的 Skill,按其中的步骤工作。
SKILL.md
SKILL.md 以 YAML 头开始:
---
name: release-notes
description: 根据 git 历史为这个仓库撰写发布说明,按功能、修复和破坏性变更分组。
---
# 撰写发布说明
1. 用 `git log` 找出上一个标签以来的提交……| 字段 | 是否必需 | 说明 |
|---|---|---|
description | 必需 | 何时使用这个 Skill,最多 4096 字节。模型根据它决定是否读取 |
name | 可选 | 名字,最多 96 个字符;默认为目录名 |
license | 可选 | 许可证 |
metadata.version、metadata.short-description | 可选 | 版本和简短说明 |
不认识的字段会被忽略。Skill 目录中还可以有一个 agents/openai.yaml,提供显示名称、图标,以及它依赖的 MCP 服务器;依赖的服务器没有就绪时,这个 Skill 显示为不可用。
界面信息与显式调用
可选的 agents/openai.yaml 将展示信息与指令分开:
interface:
display_name: "发布说明"
short_description: "从仓库历史整理发布说明"
icon_small: "./assets/icon.svg"
brand_color: "#2563EB"
default_prompt: "使用 $release-notes 编写发布说明。"
policy:
allow_implicit_invocation: false
dependencies:
tools:
- type: "mcp"
value: "github"
description: "读取拉取请求和发布记录"
transport: "streamable_http"
url: "https://example.com/mcp"也支持 icon_large;两个图标路径都相对于 Skill 目录。展示字段是提供给界面的元数据,不会自动作为额外的用户指令发送。无法使用的字段逐项忽略并在目录的问题中报告;界面文件无效不会使原本可用的 SKILL.md 失效。
allow_implicit_invocation 默认为 true。设为 false 后,Skill 不出现在自动发现中(包括 skills_list),但仍可通过 $NAME 或 skill:// 显式选择。这与停用 Skill 不同:停用后,新回合不能使用它。声明的 MCP 依赖必须已经配置且就绪;依赖声明本身不会安装服务器或授予权限。
Skill 从哪里来
| 来源 | 位置 | ID 示例 |
|---|---|---|
| 内置 | 数据目录的 skills/system/,每次启动时更新 | system:skill-creator |
| 安装 | 数据目录的 skills/packages/,由 skills install 放入 | user:release-notes |
| 仓库 | 每个工作区目录及其上级目录(直到 Git 根目录)中的 .agents/skills/,只读 | repo:web/lint |
| 插件 | 启用的已安装插件的 skills/(或其清单指定的目录)以及由它的命令转换成的 Skill,只读 | plugin:demo@my-mkt:search |
内置的两个 Skill:
system:skill-creator:帮你编写或修改 Skill。system:skill-manager:查看 Skill、启用或停用某个 Skill、从目录或 Git 仓库安装 Skill(仓库由模型运行的命令克隆,因此经过network.proxy),并解释某个 Skill 为什么在或不在本次回合中使用。
把团队共用的 Skill 放进仓库的 .agents/skills/ 中,所有在这个仓库中工作的人都能使用。
插件的 Skill 以插件命名,与 Codex 相同:插件 demo 的 Skill search 在列表中和对模型都叫 demo:search($demo:search 选择它),它的 ID 写明包:plugin:demo@my-mkt:search。Agent Plugins 包的 Skill 是其 skills/ 的直接子目录;其他包的 Skill 在任意深度都会被找到。它们随插件出现和消失:关闭插件就会移除它们,无需重启。它们和其他 Skill 一样可以单独开关。
skills_list 返回配置的用户安装根目录 user_root,即使列表为空也会返回。直接将包放在 <user_root>/<name>/SKILL.md。每个条目的 directory 是完整的原生目录路径,可能已经解析了符号链接,不能用它可靠地推导安装根目录。skill ID 中的路径相对于作用域根目录,并非绝对目录。system、repo 和 plugin 的根目录相互独立。独立应用默认为 skills/packages/,嵌入宿主可以配置其他根目录。authority 筛选支持 system、user、repo 和 plugin,所有 Skill 工具均接受插件 ID,例如 plugin:demo@local:search。
查看和安装
hanafubuki-agent skills list
hanafubuki-agent skills install ./release-notes
hanafubuki-agent skills install ./release-notes --overwrite
hanafubuki-agent skills remove user:release-notesskills list打印每个 Skill 的 ID、是否停用和说明;目录中有问题的 Skill 打印到标准错误。skills install 目录:目录本身包含SKILL.md,或者只有一个子目录包含它。Skill 必须能被正确解析。安装后的目录名取自源目录名。已经有同名的 Skill 时会失败,加上--overwrite替换它。skills remove ID删除一个安装的 Skill。仓库中的 Skill 随仓库一起管理。
/skills 打开统一的 Skills 管理集合;/skills verbose 把目录写入对话记录。集合支持从本地目录安装、启停、查看 SKILL.md 和删除用户安装的 Skill。资源文件创作仍通过 facade 和文件编辑器进行。
在对话中使用
- 让模型自己选:模型能看到允许隐式调用的可用 Skill,任务符合某个 Skill 的说明时会用
skills_read读取它。 - 点名使用:在消息中写
$名字,例如用 $release-notes 写 0.2.0 的发布说明。点名的 Skill 会在这个回合中提供给模型。 - 用链接指定:
[$release-notes](skill://user:release-notes)按 ID 指定 Skill,即使它的名字已经改了,或者与某个工具同名,也照样选中它。模型提到它读过的 Skill 时就写这种形式。
$PATH、$HOME 这类环境变量名,以及工具名和 MCP 服务器名,不会被当作 Skill。
读取参考资料与资源
模型使用的 Skill 目录在用户回合开始时捕获。不带 path 读取 Skill 会采用它:完整 SKILL.md 以 <skill> 上下文块交付一次,重复读取不会再次插入。目录和指令改动在之后的用户回合捕获,不重写当前或过去的回合;读取资源时仍检查 Skill 当前是否启用。
skills_list 接受可选的 authority(system、user、repo 或 plugin),通过 next_cursor 对条目分页:保持相同的 authority 过滤,将它作为下一次的 cursor,直到返回 null。即使尚未安装用户 Skill,结果也会报告 user_root,安装时不必从已有条目推算根目录。
每个条目列出非脚本资源的包内相对路径、类型和大小。之后 skills_read 接受 skill、path,读取文本后还可把结果中的 next_cursor 作为下一次的 cursor:
- 参考文本每页最多 8 KiB,不会切断 UTF-8 字符。资源自上一页后发生变化会使游标失效,需要不带游标重新读取。
- 图片作为图片内容返回,其他二进制资源作为嵌入资源返回;二进制资源不接受游标。
scripts/下的文件不通过skills_read披露。执行脚本使用命令执行工具,并遵循通常的审批规则。
这种方式只能读取本回合目录已列出的资源。资源路径相对于所属 Skill,不是任意文件系统路径。指令在回合内固定;资源字节在请求时读取。
启用和停用
所有发现的 Skill 默认启用。停用的 Skill 不会出现在模型看到的目录中。
- 让模型帮你做:例如“停用 release-notes 这个 Skill”。模型会调用
disable_skill(或enable_skill),这类操作总是询问你,在任何权限模式下都需要你确认,计划模式下不可用。 - 或者编辑数据目录的
skills/state.json,在其中的disabled列表中加入或去掉 Skill 的 ID。
在终端界面打开 /skills,选择 Skill,修改 Enabled,表单会保存改动。这是直接的设置操作,不需要模型调用工具。独立的 skills CLI 没有 enable/disable 子命令。
宿主 API 还支持创建、复制 Skill 及编辑其文件;这些编辑操作只写入用户根目录。
要关闭整个 Skill 功能,把 skills 加入 disabledPlugins。
Skill 中的脚本由模型通过命令运行,同样需要审批。安装来源不明的 Skill 前,请先阅读它的 SKILL.md
和脚本。