Skills
Skill 是可复用的本地工作流。一个 skill 以一个 SKILL.md 文件为根，描述一种
可重复的任务模式，Agent 需要时可以加载。
什么是 skill
一个 skill 通常包含：
- 用途 — 这个 skill 帮助完成什么任务
- 工作流 — 给 Agent 的分步指引
- 边界 — 这个 skill 该做什么、不该做什么
- 引用 — 要查看的相关文件或命令
Skill 不会自动生效。运行时会提供一份可用 skill 的目录，只有当出现匹配的
任务时，Agent 才会打开对应的 SKILL.md。
位置
仓库内的 skill 通常放在：
.codex/skills/<skill-name>/SKILL.md
skills/<skill-name>/SKILL.md
本仓库中的示例 skill 有：
ghxcode-reviewgithub-issue-solvegithub-pr-fixgithub-review
Agent 如何使用 skill
- 运行时提供一份 skills 目录，包含名称、描述和路径
- 只有当 skill 匹配当前任务时，Agent 才会选择它
- Agent 读取该 skill 的
SKILL.md - Agent 用普通的工具调用执行其中的工作流
这样能让 skill 保持显式，也避免加载无关的指引。
用 CLI 管理 skill
Holon 把 skill 管理分成两层：
- Skill Library — 已知 skill 的全局目录，用
holon skills add/remove/check/reconcile/catalog管理。可以把它当作你的 本地 skill 注册表。 - Agent Skills — 按 Agent 启用的 skill，用
holon skills enable/disable/list管理。skill 必须先存在于 library， 才能为某个 Agent 启用。
Skill Library（全局）
Skill Library 是你本地的 skill 目录。用下面的命令管理：
查看 library 目录
holon skills catalog
列出本地 Skill Library 中注册的所有 skill。
向 library 添加 skill
# 从本地目录或 SKILL.md 文件添加
holon skills add /path/to/skill-dir
# 从远程源添加
holon skills add https://github.com/user/repo/tree/main/skills/my-skill --remote
# 把 skill 复制到用户目录，而不是引用它
holon skills add /path/to/skill --copy
从 library 移除 skill
holon skills remove my-skill
检查 library 一致性
# 对照 .skill-lock.json 检查所有 library 条目
holon skills check
# 检查某个具体 skill
holon skills check my-skill
注意： 安装一个已安装的全局 skill 是幂等的：
holon skills add会跳过 安装并报告已有条目，不报错。在脚本和自动化里 可以放心重复执行。
用 lock 文件校准 library
# 校准所有 library 条目
holon skills reconcile
# 校准某个具体 skill
holon skills reconcile my-skill
从远程源更新 skill
holon skills update
拉取远程 skill 源并与 lock 文件（.skill-lock.json）比对。上游有变化的
skill 会被下载并更新。更新会保留 npx skills v3 的 lock 格式（source、
subdir、mode、etag），以便互通。
Agent Skills（按 Agent）
skill 进入 library 后，再为具体 Agent 启用：
列出某个 Agent 已启用的 skill
# 列出默认 Agent 的
holon skills list
# 列出某个具体 Agent 的
holon skills list --agent reviewer
列出该 Agent 当前已启用的所有 skill，包括名称、作用域（agent、workspace 或 user）和来源。
为 Agent 启用 skill
# 为默认 Agent 启用
holon skills enable my-skill
# 为某个具体 Agent 启用
holon skills enable my-skill --agent reviewer
# 启用并复制到 Agent home
holon skills enable my-skill --copy
为 Agent 禁用 skill
# 为默认 Agent 禁用
holon skills disable my-skill
# 为某个具体 Agent 禁用
holon skills disable my-skill --agent reviewer
兼容别名：
holon skills install和holon skills uninstall仍被接受， 但会映射到新的 add/enable 和 remove/disable 模型。为了清晰，优先用新命令。
Skill 的 uses 简写
添加 GitHub 上托管的 skill 时，可以用 uses 简写语法代替仓库 URL：
# 完整 URL 形式
holon skills add https://github.com/holon-run/holon/tree/main/skills/ghx --remote
# uses 简写，效果相同
holon skills add holon-run/holon/skills/ghx@main
uses 形式（owner/repo/path@ref）会在内部规范化为完整的 GitHub URL。它也
接受 owner/repo/path#ref 作为兼容输入。
Skill 源类型
| 源 | 标志 | 示例 |
|---|---|---|
| 本地路径 | （默认） | holon skills add ./skills/my-skill |
| 远程 URL | --remote | holon skills add https://... --remote |
命令速查
| 层 | 命令 | 用途 |
|---|---|---|
| Library | holon skills catalog | 列出 library 目录 |
| Library | holon skills update | 从远程源拉取并更新 skill |
| Library | holon skills refresh | 重新扫描本地根目录，刷新运行时目录 |
| Library | holon skills add <source> | 向 library 添加 skill |
| Library | holon skills remove <name> | 从 library 移除 |
| Library | holon skills check [name] | 检查 lock 文件一致性 |
| Library | holon skills reconcile [name] | 与 lock 文件校准 |
| Agent | holon skills list [--agent] | 列出已启用的 skill |
| Agent | holon skills enable <name> | 为 Agent 启用 |
| Agent | holon skills disable <name> | 为 Agent 禁用 |
注意：
--builtin标志和模板清单里的kind = "builtin"已在 v0.26.0 移除。官方 Holon skill 现在和其他 GitHub 托管的 skill 用同样的方式引用。
用 HTTP 管理 skill
HTTP 控制平面把 library 操作和 Agent 操作分开：
Library 端点
| 方法 | 路径 | 用途 |
|---|---|---|
GET | /api/skills/catalog | 列出 library 目录 |
GET | /api/skills/catalog/{skill_id} | 获取 skill 详情 |
POST | /api/skills/catalog/add | 向 library 添加 skill |
POST | /api/skills/catalog/refresh | 刷新运行时目录 |
POST | /api/skills/catalog/remove | 从 library 移除 |
POST | /api/skills/catalog/reconcile | 与 lock 文件校准 |
POST | /api/skills/catalog/check | 检查一致性 |
POST | /api/skills/catalog/update | 从远程源更新 skill |
Agent 端点
| 方法 | 路径 | 用途 |
|---|---|---|
GET | /agents/:agent_id/skills | 列出 Agent 的 skill |
POST | /control/agents/:agent_id/skills/enable | 为 Agent 启用 |
POST | /control/agents/:agent_id/skills/disable | 为 Agent 禁用 |
已弃用：
POST /api/control/agents/:agent_id/skills/install和POST /api/control/agents/:agent_id/skills/uninstall仍保留以兼容，但已被 enable/disable 和 add/remove 取代。
非阻塞安装任务
通过 HTTP API 安装 skill（例如从 Web GUI）时，安装会作为后台任务运行，不会
阻塞请求。任务进度可在 GET /api/jobs/{job_id} 查看，并通过 localStorage
在页面重新加载后保留。
TUI 集成
终端 UI 在 CLI 之外也提供 skill 管理：
- 斜杠命令 — 输入
/skills查看 Agent 的 skill，/skill-catalog浏览 library，/skill-add <source>添加到 library，/skill-remove <name>移除，/skill-enable <name>//skill-disable <name>直接在聊天输入框里管理 Agent 的启用状态。 - skill 名称补全 — 使用斜杠命令时，TUI 会自动补全 skill 名称。
- Agent 状态侧栏 — “Skills” 下的 Agent 详情视图列出所有可发现的 skill 及其作用域（agent、workspace、user）。
有了这些 TUI 功能，你无需离开交互会话就能管理 skill。
如何写好一个 skill
让 skill 保持：
- 小巧 — 只聚焦一个工作流
- 可执行 — 给出 Agent 能照做的具体步骤
- 有边界 — 避免大范围覆盖项目的指令
- 持久 — 记录可复用的行为，而不是一次性的任务笔记
适合写成 skill 的主题：
- 解决 GitHub issue
- PR 评审流程
- 发布清单
- 事故分类
- 项目专属的测试/调试循环
不适合写成 skill 的主题：
- 临时会议记录
- 一次性的任务计划
- 大段照搬的文档
与 AGENTS.md 的关系
这样分工：
AGENTS.md放持久的角色、权限和本地约定- Skill 放可复用的工作流
- 工作项 放当前跟踪的目标
它们是不同的层：
| 面 | 用途 |
|---|---|
AGENTS.md | 常驻指令和边界 |
SKILL.md | 某一类任务的可复用工作流 |
| 工作项 | 当前目标和进度 |
另见
- 多 Agent 协作 — 把工作委托给子 Agent
- 工作项指南 — 跟踪持久目标
- Web GUI — 在浏览器里管理 skill
- TUI 指南 — 在终端里管理 skill
- 运行时模型 — skill 如何融入 Agent 的运行循环