用途：在创建或编辑技能（skill）时使用，帮助技能做到可被发现、简洁，并原生适配目标执行环境（harness）。核心原则是：技能应记录可复用的判断，而不是某次会话的叙述；只写能可靠改变未来智能体在正确任务类别上行为的最少指令。
目录选择：编辑前先确定唯一事实来源。共享技能源应编辑仓库管理的 Claude 技能，而不是生成的运行时副本；仅适用 Codex 的适配应编辑仓库管理的 Codex 覆盖，而不是生成的运行时副本。在 dotfiles 配置中，它们位于 claude-code/.claude/skills/<skill-name>/ 与 claude-code/codex-overrides/skills/<skill-name>/。当上游共享技能已存在，但其工作流或措辞不能干净地适配 Codex 时，使用 Codex 覆盖。
何时创建技能：当技术可跨任务复用、智能体反复错过同一判断、或一份短文档能防止重复错误时创建或更新。不要为一次性项目上下文、应由代码或 lint 强制执行的纯机械规则、或应放入仓库说明的内容创建技能。
结构：每个技能目录应保持小巧，包含 SKILL.md，仅在需要时添加 supporting-file.md。优先一份简洁的 SKILL.md，只有大量参考材料才添加支持文件。
元数据规则：frontmatter 仅支持 name 和 description。description 应以 Use when... 开头，描述触发条件而非工作流，保持足够具体以便发现；除非技能有意针对特定环境，否则避免特定于执行环境的断言。
编写规则：工作流保持对目标环境原生；命名智能体实际拥有的真实工具与文件；优先具体触发而非宽泛抽象；大幅删减重复解释；当失败模式可预测时加入警示信号。
测试技能：用真实任务验证——观察代表性请求的基线行为；编写或修订技能以解决真实失败；重新运行任务并比较行为；仅在技能仍留有漏洞处收紧措辞。只有当子智能体能增加信号时才使用它们测试；子智能体是可选的，不是重点。
警示信号：description 概括了完整工作流；指令引用了目标环境中不可用的工具；长示例重复同一规则；技能重复仓库级策略。