open-knowledge-write-skill

编写 OpenKnowledge 技能

你正在帮助用户编写一个 Agent Skill——一个 SKILL.md 文件（以及可选的 references/ 和 scripts/），用于教 AI Agent 执行重复性任务。在 OpenKnowledge 中，技能是一种一等公民、带版本控制且可安装的制品：你使用 write / edit 技能动词编写它，然后将其 install 到用户的编辑器中。

技能的价值在于能在恰当时机被识别并得到忠实执行。大部分功夫要下在两处：确保能可靠触发的 description，以及足够简短具体、能让 Agent 照做的正文。请按顺序完成以下阶段，但如果用户已经进行到某个阶段，就直接从那里开始。

阶段 1 — 明确意图并对技能进行分类

关卡——这个技能是否已经存在？构建之前先检查。 首先用 skills({}) 列出已管理的技能，然后用 skills({ name }) 阅读所有可能匹配的技能；这些是 OpenKnowledge 已管理的 Project/Global 技能。如果任务听起来可能在当前项目之外复用，起草前也要通过 skills({ query: "<2-4 trigger words>" }) 搜索公共市场。市场中的每一行都会返回 name、source 和 description；检查最匹配的描述，然后用 import({ source, skill: name, add: [...] }) 导入合适的候选技能，并且仅在复用确实合适时才对其进行调整。只有在无法使用 OK MCP 的 skills({ query }) 路径时，才使用 Vercel 的 find-skills 技能、npx skills find <query> 或手动搜索 skills.sh。如果用户已经打开了 skills.sh 页面，请将完整的技能页面 URL 作为 source 传入，例如： import({ source: "https://www.skills.sh/<owner>/<repo>/<skill>", add: [...] })——中间部分是 REPO，不是字面上的 skills。在此流程中，不要将 npx skills add 作为默认安装方式：通过 OpenKnowledge 导入（import({ source, skill, add })），这样技能才能成为具备来源信息、版本控制和集中分发能力的真正文件夹；add 指定技能放置的位置，之后的 install 则会更改技能所在的位置。使用用户请求中的 2-4 个具体触发短语，加上领域或工具名称，然后打开并阅读最匹配候选技能的描述，再作判断。如果现有技能或公共技能已覆盖大部分需求，就停止并建议复用——触发条件重叠的近似重复技能会造成误触发，并削弱彼此的效果。如果公共技能接近但并不完全匹配，请与用户一起决定是将其导入/调整后用于 OpenKnowledge、通过 Skills CLI 在 OK 之外安装，还是编写一个更精简的配套技能，并在其 description 中明确说明何时交由该技能处理。只有在确实与众不同的情况下，才构建新技能。在起草或编写任何内容之前，先说明技能之间的重叠情况，以及已安装技能和市场搜索的结果。这是一个信息披露关卡：告诉用户你检查了什么、发现了哪些匹配项，以及复用/导入/调整/新建为何是合适的下一步。绝不要等技能写完后才发现重叠。如果 skills({ query }) / skills.sh 无法访问，请坦诚说明，然后继续检查已安装的技能。

只询问无法推断的信息：

• 要处理什么重复性任务？ 请提供一个具体示例。
• 技能类型，因为它决定了需要多严格：
  • 参考 / 技巧（大多数技能）——“如何执行 X”。正文采用说明性文字，并提供示例。
  • 纪律——强制执行 Agent 在压力下容易跳过的行为（例如“始终先编写一个会失败的测试”）。这类技能需要在阶段 4–6 中建立 RED 基线并进行压力测试；参考类技能不需要。
• 自由度（根据任务的脆弱程度调整正文精确度）： 高（自由行文——判断类任务）、中（带参数的步骤）、低（固定的 scripts/ 命令——任何偏离都会导致结果出错）。不要对判断类任务规定过细，也不要对脆弱任务规定不足。

阶段 2 — 先确定范围（绝不默默推断）

范围决定技能存放的位置，以及 install 会将其分发到哪里。这由用户决定，且影响范围各不相同——务必明确说明。

范围	存放位置	install 会将其分发到
全局	主目录的技能根目录下的实际文件夹（例如 ~/.claude/skills/<name>/）	你的编辑器，在每个项目中
项目	此仓库技能根目录中的实际文件夹（例如 .claude/skills/<name>/ 或 .agents/skills/ 中枢——通过 git 共享）	此项目的编辑器；队友在执行 git pull 后也会获得

默认判断方式：如果位于合适的项目中，且任务专属于该项目 → 项目； “用于我的所有工作／全局” → 全局；否则提出一个问题。开始编写前，说明选择及其影响。

正在开发技能仓库或插件？那么这两种范围都不适用。 如果你正在处理的仓库本身就是一个技能分发仓库——插件（例如 .claude-plugin/ 清单或市场列表），或将技能存放在 skills/<name>/ 供他人导入的目录仓库——那么你编写的技能是该仓库的产品，而不是要安装到其中的内容。按照仓库已有的格式，将技能写入仓库自己的布局中，与同级技能放在一起。不要将它放在此处的 .claude/skills/ 或 .agents/skills/ 下，也不要对其执行 install：用户通过安装插件或从仓库导入来获取它，而插件自身的仓库不会加载自身的内容。install 只适用于当前项目或用户需要加载的技能。如果不确定该仓库是分发仓库还是使用仓库，请先询问——放错位置会导致技能发布后无人能找到。

阶段 3 — 规划内容

• 正文 = 持久、可复用的说明，长度约低于 500 行。如果内容持续增长并超出此范围，就将详细内容移到 references/<topic>.md（仅在需要时加载），并在正文中引用。对于项目技能，参考文档无论如何都会自动连接到图谱中，因此使用带反引号的 `references/<topic>.md` 路径即可；只有想让提及内容成为可点击的内联链接时，才使用 [[references/<topic>]] wiki 链接。对于全局技能，使用普通的反引号路径——全局参考文档不是图谱文档，在其中使用 wiki 链接会产生悬空链接。参考文档最多一层深。
• 不要包含：README/CHANGELOG/QUICK_REFERENCE、该技能本身的安装说明、版本历史，或任何特定于宿主的内容。技能本身就是说明，而不是关于这些说明的文档。
• 对于规范类技能，规划要纠正的失败模式，以及如何证明技能能修复该问题（阶段 4）。

阶段 4 — RED 基线（仅限规范类技能）

编写技能前，先在不使用技能的情况下运行该场景，并逐字记录 Agent 的错误做法——包括其自我辩解（“测试很简单，所以我跳过了”）。这些自我辩解正是技能正文必须堵住的漏洞。在一个没有加载该技能的全新 Agent 会话中运行该场景——可以是新聊天、子 Agent 或第二个终端——并保留对话记录；如果无法在干净环境中运行，就与用户一起推演基线。纯参考类技能跳过此阶段。

阶段 5 — 起草技能

使用技能动词编写源内容（fs-direct；如果服务正在运行，实时预览会自动更新）：

write({ skill: { name: "<lowercase-hyphen-name>", description: "<triggers>", body: "<markdown>", scope: "project" } })

Frontmatter 规范（写入时会验证，请务必正确填写）：

• name — 仅限小写字母、数字和连字符；≤64；必须与目录名一致。
• description — ≤1024 个字符，不得包含 XML 标签，不得包含 version 字段。参见阶段 7。
• 不得包含其他内容。OK 绝不会自行注入 frontmatter；记录信息存放在 .ok/ 中。

正文应直接向 Agent 发出指令（祈使语气，使用第二人称），内容要具体而非抽象。

通过技能动词添加深度文件——references/*.md（按需加载）和 scripts/*（作为文本显示，绝不由 OK 执行），切勿使用原生 Write/cat：

# write one or more bundle files (independent of body — no need to resend SKILL.md)
write({ skill: { name: "<name>", files: [{ path: "references/tiers.md", content: "..." }] } })

# surgical edit inside one bundle file (mirrors edit({ document }))
edit({ skill: { name: "<name>", file: "references/tiers.md", find: "...", replace: "..." } })

# list the bundle, then read one file (no native cat)
skills({ name: "<name>" })                         # → files: [{ path, kind }]
skills({ name: "<name>", file: "references/tiers.md" })   # → { path, kind, text }

# delete specific bundle files (omit `files` to delete the whole skill)
delete({ skill: { name: "<name>", files: ["references/tiers.md"] } })

路径相对于技能目录，必须位于技能目录内（不得使用 ../ 或绝对路径）。references/ 和 scripts/ 是惯用目录，也是首选目录；也接受其他根目录（assets/、特定于某个 harness 的目录），因为已发布的技能会随附这些目录，导入时也会原样保留。引用文件应保持一层深度。项目中的 .md 引用文件会成为实时内容文档，无论正文如何提及它，都会在图谱中自动关联到其 SKILL——反引号括起来的 `references/<name>.md` 路径和 [[references/<name>]] wiki 链接一样，都会加入图谱。只有在需要可点击的行内链接时，才使用 wiki 链接（或 [label](references/<name>.md)）。全局技能则有所不同：它们的引用文件不是图谱文档，因此应使用普通的反引号路径；wiki 链接会成为无效链接。

阶段 6 — GREEN 评估 + 重构

重新运行场景，并启用技能。对于规范类技能，进行压力测试：组合 2–3 种压力（时间、权威、沉没成本），确认 Agent 仍会遵循规则；然后修补任何漏洞并重新测试（references/pressure-testing.md）。对于参考类技能，确认 Agent 现在能正确完成任务，且正文没有超出必要长度。删掉 Agent 已经知道的内容。

阶段 7 — 优化 description（技能能否触发取决于此）

Agent 在判断是否加载技能时，唯一能看到的内容就是 description。务必认真编写（references/description-optimization.md）：

• 写触发条件，不写摘要。 说明何时应使用技能，并采用用户的措辞和表达方式——不要复述正文内容。在 description 中总结工作流，会导致 Agent 只遵循 description 而跳过正文。
• 具体且略带强调，以避免触发不足：明确列出应激活技能的情境、动词和表达方式。
• 针对容易混淆的查询进行合理性检查：确认哪些表达 SHOULD 触发技能，哪些相近表达则不应触发。

阶段 8 — 安装（选择可用位置）

对于读取创建它的文件夹的 Agent 来说，技能已经生效——该文件夹本身就是技能（不存在草稿状态）。install 用于管理它还可以在其他哪些位置使用，并以增量方式添加：

install({ name: "<name>", add: ["codex", "opencode"] })   // add locations
install({ name: "<name>", remove: ["codex"] })            // remove locations
install({ name: "<name>", add: ["codex"], mode: "link" }) // ...as a symlink
install({ name: "<name>", convert: ["codex"], mode: "copy" })  // change one location's form
install({ name: "<name>", source: ".team/skills" })       // move the real folder (run alone)

位置 ID 是编辑器宿主 ID（claude … pi）、agents（与厂商无关的集成中心），或自定义根路径，例如 .team/skills。

位置采用何种形式。 mode 只适用于本次调用指定的位置——即 add 中的位置或 convert 中的位置，不影响其他位置。在 add 中省略它时，新位置会采用技能当前使用的形式。技能没有全局模式：安装绝不会重写未指定的位置。要更改现有位置，请使用 convert，它不会改变位置归属；要统一形式，请传入所有位置。

每种形式的含义。 符号链接指向源，因此不会出现偏离。副本是独立的文件夹。技能监视程序运行或服务启动时，记录在案且未经编辑的副本会从源更新，因此源文件编辑后，副本可能会短暂滞后。手动编辑会使副本分叉，并阻止后续自动覆盖。

生命周期。 使用 edit({ skill }) 编辑；它会将操作路由到源，并在原处进行版本管理。不存在“在所有位置卸载”——移除其他所有位置后，源文件夹仍会为其 Agent 加载；只有通过 delete({ skill }) 才会使技能不复存在，该操作会移除源和所有位置。使用 history({ skill }) → restore_version({ skill, version }) 回滚项目技能；此版本中，全局技能不进行版本管理。对于项目技能，请提交技能文件夹——它们是 git 中的普通文件，因此队友拉取后也会获得这些文件。

提醒

• 优先选择一个优质技能，而不是多个重叠技能；只有在触发条件不同时才拆分。（阶段 1 的检查关卡就是用于强制执行这一点——不要把发现重叠的工作留到之后。）
• 范围是唯一的放置决策——不要将执行环境、格式或工具链的假设混入其中，也不要在范围问题的措辞中预设这些假设。你正在编写 OpenKnowledge 技能：使用 write({ skill }) 创建技能——它会在项目默认的技能目录中生成真实文件夹，并附带归属信息和版本管理——再用 install 分发；不要手动将副本散布到各个编辑器目录，因为分发由 install 管理；记录在案且未经编辑的副本会在监视程序运行／启动时同步更新（手动编辑的副本会分叉并停止更新）。如果你使用此流程，就通过它来编写技能。
• 关于技能行为（版本管理、安装目标、范围语义）的说法，应以本指南或工具说明为依据——不要根据假设断言系统事实。
• 避免没有说明理由的笼统 ALWAYS／NEVER 规则——这类规则读起来像噪声，也容易被忽略。请解释原因。
• 随技能提供的可执行 scripts/ 会原样进入另一个 Agent 的信任域——只包含用户审阅过的脚本。