用途
create-skill 用于指导如何为 Harness Anything Agent 编写或修订一个项目技能（skill）。其核心观点是：技能不是文档，而是 Agent 在执行前加载的程序性内容——按名称被发现，并以路径加 SKILL.md 的形式注入。若 Agent 能从任务计划中完成同样的步骤，就不应存在该技能；若每次派发都要重复告知同一件事，那属于 instructions 而非技能。
技能从何而来
在写路径前，需确认服务节点实际扫描的根目录。权威读取逻辑位于 packages/daemon/src/agent-skills.ts（discoverAgentSkills / resolveAgentSkills），按顺序扫描：
- 用户级：~/.claude/skills、~/.agents/skills、~/.codex/skills，跨项目共享。
- 项目级：<project>/.claude/skills、<project>/skills（本仓库放置随附技能之处）、<project>/.agents/skills（跟随符号链接），以及 <harness authored root>/skills（私有账本的技能根）。
目录中存在常规 SKILL.md 即视为技能，符号链接的 SKILL.md 会被拒绝；技能 id 是目录的 basename。由此有两条规则：目录按 id 命名并保持稳定，Agent 声明中的 skills[].id 匹配路径而非 frontmatter 的 name；且必须在 Agent 中声明路径，仅创建文件不会挂载——通过 ha agent install 搭配 skills: [{ "id": "<dir>", "path": "skills/<dir>" }] 才会挂载，路径在服务节点无法解析会导致整次派发以 agent_skill_not_found 失败。本仓库可用 npm run harness:sync-runtime-skills 将新技能链接到运行时目录，该命令会先检查冲突，绝不覆盖外部链接。
frontmatter 是契约
frontmatter 格式为 name（必须等于目录 basename）与 description（同一句中写明技能做什么以及何时加载）。description 是模型决定是否加载前看到的唯一文本，应按触发条件写：包含情境、包含所管辖的文件/命令/产物、排除具体流程（流程属于正文）；不要写“帮助处理”“最佳实践”或主题列表。
正文结构
建议按顺序使用以下小节，并删除不承载判断的部分：Boundary（适用范围及不适用时由哪个相邻技能或规则接管）、Contract source（权威文件、--help 或命令的路径，不重述可机读的 schema）、Procedure（可执行的编号步骤，每步写明运行的命令与正确结果的样子）、Failure branches（具体错误码或症状及下一步动作）、Evidence（Agent 需回报供所有者核验的内容）。
经验规则包括：不要重复注入的基线内容；每条规则只有一个权威出处；长尾内容放入 references/ 并在正文标注何时打开；能用命令或检查替代提醒就写成命令；触发条件前置。
删除预算与验证
每次编辑都要说明删除了什么：新小节替代、收窄或吸收了哪段旧内容；若为全新维度，哪条旧规则已失效或冗余。用 wc -c skills/<id>/SKILL.md 记录改动前后大小，增长必须对应明确的缩减。
验证按成本从低到高：结构（frontmatter 可解析、name 等于目录、SKILL.md 为常规文件；npm run harness:sync-runtime-skills 检查冲突，node --test tools/skill-contracts.test.mjs 校验仓库技能契约）；解析（ha agent validate --source <declaration> 在路径缺失时报错）；组合（ha agent run <id> --task <task-id> --dry-run 在组装后的提示中显示解析出的技能路径）；行为（让未参与改动的人按场景执行并记录结果）。
不应做的事
不要为一次性任务创建技能；不要把公共技能复制进项目再改名（分叉会带来维护重复与漂移，应引用公共技能并只补充项目特有内容）；不要在技能中放密钥、绝对机器路径或私有 URL；不要因一次失败就写成永久禁令，应写明失败条件与动作并给本地防护设置过期或移除触发；不要让技能变成堆放一切之处——instructions 是每次派发的判断，技能是特定情境的流程，任务计划是本次交付。
输出契约
完成后需报告：技能路径与 id、frontmatter 的 description 句、所指向的契约源、注册的 Agent 及挂载它的声明变更、前后 wc -c、删除清单、已运行的验证命令及结果，以及尚未验证的事项。