用途：围绕 Anthropic《The Complete Guide to Building Skills for Claude》，指导创建、评审和改进 Claude/Codex 技能，使技能能正确触发、可靠执行并保持简洁。
核心原则：采用渐进式披露，frontmatter（name、description）负责触发选择，SKILL.md 正文承载核心流程，references/ 存放按需加载的深层细节；技能应可组合，不假设自身是唯一激活技能；脆弱校验逻辑优先用确定性脚本。
工作流程：定义 2-3 个具体用例；起草触发力强的前台信息；设计可复用资源（scripts/、references/、assets/）；编写可执行指令与错误处理；运行触发、功能与性能测试；根据欠触发/过触发信号迭代。用例需记录用户原话、预期结果、多步流程与所需工具、需防护的失败点，模糊时应先追问。
frontmatter 设计最关键：name 用 kebab-case 且与文件夹名一致；description 须同时包含技能做什么与何时使用（触发短语、上下文、文件类型），公式为“做什么 + 何时用 + 关键能力”，避免含糊表述，可加入负向触发以减少过度触发。
资源规则：SKILL.md 保持精简并链接 references/；技能目录中不放 README.md、changelog 等额外文档。指令应祈使、可测试，包含步骤顺序与依赖、验证检查点、常见错误及修复、输入输出示例；关键检查优先脚本化。
测试分三组：触发测试（明显请求与改写请求应触发，无关请求不应触发，目标约 90% 命中率）；功能测试（输出正确性、工具/API 调用、错误处理、边界情况）；性能对比（有无技能时的澄清轮次、失败调用、token 用量、端到端质量）。迭代规则：欠触发时补充清晰触发短语与技术术语；过触发时加负向触发并收紧范围；执行不一致时收紧指令、增加显式校验并脚本化关键检查。
打包前需验证与打包。可用命令：bash scripts/new_skill.sh <skill-name> 生成新技能目录。注意 quick_validate.py 与 package_skill.py 未随本技能捆绑；可用 synapse skills show <name> 验证 frontmatter，用 synapse skills deploy <name> 分发。
常见故障排查：缺少 SKILL.md 导致上传失败（文件名必须恰为 SKILL.md）；frontmatter 无效需检查 YAML 分隔符 --- 与语法；技能名无效需用小写 kebab-case；技能未被遵循可将关键指令前移并具体化；行为缓慢可把长内容移至 references/ 并减少启用技能。
参考文件：references/checklist.md、prompt-templates.md、patterns.md、source.md、trigger-examples.md、failure-remedies.md。