hanafubuki-agent

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-notes
  • skills 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 和脚本。

本页目录