需要创建或改进 Agent…

当用户想编写、设计或改进一个可复用的 Agent Skill（SKILL.md），或把某个工作流固化成可安装技能时，按阶段完成查重、定范围、撰写、评测与安装。

适用场景

解决思路

1. 先做查重门禁：用 `skills({})` 列出已管理的技能，再用 `skills({ name })` 读取可能匹配的技能；同时用 `skills({ query: "<2-4 个触发词>" })` 搜索公开市场，查看候选的 `name`、`source`、`description`，判断是否已有技能覆盖大部分需求。
2. 若找到可复用技能，用 `import({ source, skill: name, add: [...] })` 导入并适配；只有在 OK MCP 的 `skills({ query })` 不可用时，才改用 Vercel 的 `find-skills` 技能、`npx skills find <query>` 或手动搜索 skills.sh；若用户已打开 skills.sh 页面，可把完整页面 URL 作为 `source` 传入（URL 中段是 REPO，不是字面量 `skills`）。
3. 不要用 `npx skills add` 作为默认安装路径；应通过 OpenKnowledge 的 `import({ source, skill, add })` 导入，使其成为带来源、版本和受管分发的真实文件夹，`add` 决定落点，之后的 `install` 改变其所在位置。
4. 若已有或公开技能覆盖大部分需求，停止并建议复用；若接近但不完全匹配，与用户共同决定是导入/适配、用 Skills CLI 在 OK 之外安装，还是写一个更窄的伴随技能并在 `description` 中显式交接；只有确实不同才新建技能。在起草或写入前，先向用户披露检查了什么、匹配到什么、为何选择复用/导入/适配/新建。
5. 只询问无法推断的信息：这个技能要处理什么重复性任务（要一个具体例子）；技能类型是参考/技巧型还是纪律型（纪律型需要 RED 基线和压力测试）；自由度高低（高=自由散文用于判断类任务，中=参数化步骤，低=固定 `scripts/` 命令）。
6. 先明确范围，不要静默推断：Global 技能放在 home 的技能根目录（如 `~/.claude/skills/<name>/`），`install` 会分发到所有项目的编辑器；Project 技能放在本仓库技能根目录（如 `.claude/skills/<name>/` 或 `.agents/skills/` 中枢，通过 git 共享），`install` 只分发到本项目编辑器。默认启发式：在 OK 项目内且任务特定于该项目→project；面向所有工作→global；否则问一个问题。写入前说明选择及其后果。
7. 若当前仓库本身是技能分发仓库（插件，如有 `.claude-plugin/` 清单或市场列表，或以 `skills/<name>/` 陈列技能供他人导入的目录仓库），则该技能是仓库的产物而非安装到仓库中：按仓库自身布局写在同级技能旁，遵循仓库已有格式；不要放在 `.claude/skills/` 或 `.agents/skills/` 下，也不要 `install` 它。不确定时先问。
8. 规划正文：正文是持久可复用的指令，控制在约 500 行以内；超出则把深度内容移到 `references/<topic>.md`（按需加载）并在正文中指向它。Project 技能的引用会自动连入图谱，用反引号路径 `` `references/<topic>.md` `` 即可，只有想要可点击内联链接时才用 `[[references/<topic>]]` wiki-link；Global 技能用普通反引号路径（其引用不是图谱文档，wiki-link 会悬空）。引用保持一层深度。
9. 不要包含：README/CHANGELOG/QUICK_REFERENCE、技能自身的安装说明、版本历史或任何宿主特定内容。技能就是指令本身，不是关于指令的文档。
10. 纪律型技能在写之前先跑 RED 基线：在没有该技能的情况下运行场景，逐字记录 agent 做错的地方及其合理化说辞（如“测试太简单所以跳过”），这些说辞正是技能正文要堵住的漏洞。在全新 agent 会话（新聊天、子代理或第二个终端）中运行并保留记录；无法干净运行时与用户一起推演基线。参考型技能跳过此阶段。
11. 用技能动词撰写源文件：`write({ skill: { name: "<lowercase-hyphen-name>", description: "<triggers>", body: "<markdown>", scope: "project" } })`。Frontmatter 契约：`name` 为小写字母、数字、连字符，≤64，且必须等于目录名；`description` ≤1024 字符，无 XML 标签，无 `version` 字段；不要其他字段。正文用祈使句、第二人称直接对 agent 下指令，具体优于抽象。
12. 通过技能动词添加深度文件，不要用原生 `Write`/`cat`：`write({ skill: { name: "<name>", files: [{ path: "references/tiers.md", content: "..." }] } })` 写文件；`edit({ skill: { name: "<name>", file: "references/tiers.md", find: "...", replace: "..." } })` 做局部编辑；`skills({ name: "<name>" })` 列出文件，`skills({ name: "<name>", file: "references/tiers.md" })` 读取文件；`delete({ skill: { name: "<name>", files: ["references/tiers.md"] } })` 删除指定文件（省略 `files` 则删除整个技能）。路径为技能相对路径，不得越出技能目录（禁止 `../` 和绝对路径）。
13. 跑 GREEN 评测并重构：带技能重跑场景。纪律型技能要做压力测试——组合 2–3 种压力（时间、权威、沉没成本），确认 agent 仍遵守规则，然后修补漏洞并重测（见 `references/pressure-testing.md`）。参考型技能确认 agent 现在能正确完成任务且正文不过长，删掉 agent 已知的内容。
14. 优化 `description`（它决定技能能否触发）：写触发条件而非摘要，用用户的原话和措辞说明何时使用，不要复述正文（复述会让 agent 照描述走而跳过正文）；要具体且略带推动性以对抗触发不足，点名应激活的情境、动词和措辞；用近似查询做检查——应该触发的措辞和不应触发的相邻措辞。
15. 安装以决定可用位置：技能在其创建目录中已对该 agent 生效（其文件夹本身就是技能，没有草稿态），`install` 以叠加方式管理它还能在哪里可用。用 `install({ name: "<name>", add: ["codex", "opencode"] })` 添加位置；`install({ name: "<name>", remove: ["codex"] })` 移除位置；`install({ name: "<name>", add: ["codex"], mode: "link" })` 以符号链接添加；`install({ name: "<name>", convert: ["codex"], mode: "copy" })` 改变某位置的形式；`install({ name: "<name>", source: ".team/skills" })` 移动真实文件夹（需单独运行）。位置 id 为编辑器宿主 id（`claude` … `pi`）、`agents`（厂商中立中枢）或自定义根路径如 `.team/skills`。
16. 理解位置形式：`mode` 只作用于本次调用点名的位置（`add` 或 `convert` 中的），不影响其他位置；`add` 省略 `mode` 时新位置沿用技能已有形式；没有技能级 mode，安装不会改写未点名的位置；改变已有位置用 `convert`，它不改成员关系，传入所有位置可使其统一。符号链接指向源不会漂移；副本是独立文件夹并自动从源刷新，直到有人手改后分叉、不再被覆盖。
17. 生命周期管理：用 `edit({ skill })` 编辑，它会路由到源并原地版本化；没有“到处卸载”，移除所有其他位置后源文件夹仍对其 agent 加载，技能只有通过 `delete({ skill })` 才消失（删除源和所有位置）。Project 技能用 `history({ skill })` → `restore_version({ skill, version })` 回滚；Global 技能在此构建中无版本。Project 技能要提交技能文件夹——它们是 git 中的普通文件，队友 pull 即可获得。
18. 优先一个高质量技能而非多个重叠技能，只有触发条件分化时才拆分（在查重门禁处强制执行，不要留到事后发现重叠）。
19. 范围是唯一的放置决策，不要把宿主/格式/工具链假设混入范围，也不要把某一种写进范围问题的措辞。用 `write({ skill })` 创建，它会落在项目默认技能目录并带归属和版本；用 `install` 分发，不要手工把副本散落到各编辑器目录，因为 `install` 负责分发并从源刷新未编辑的副本（手改的副本会分叉并停止刷新）。
20. 关于技能行为的断言（版本化、安装目标、范围语义）要基于本指南或工具描述，不要凭假设断言系统事实。
21. 避免没有说明理由的笼统 ALWAYS/NEVER 规则——它们会被当作噪音忽略；要解释原因。
22. 附带可执行 `scripts/` 的技能会被原样投射到另一个 agent 的信任域，只包含用户已审查过的脚本。

适用边界 · 注意事项

• 已有或公开技能已覆盖大部分需求时，不要新建近似重复技能——重叠触发会误触发并稀释两者。
• 当前仓库本身是技能分发仓库（插件或目录仓库）时，不要把技能写到 `.claude/skills/` 或 `.agents/skills/`，也不要 `install` 它。
• 不要用 `npx skills add` 作为默认安装路径，也不要用原生 `Write`/`cat` 写技能文件或手工把副本散落到各编辑器目录。