writing-skills

编写技能

技能提供特定任务所需的知识，或提供模型原本需要重新摸索的可靠操作。应以正确结果、有用证据和低开销为优化目标。只有当顺序属于约定的一部分时，每次运行都采用相同流程才有意义。

选择范围

• 遵循用户要求的结果和现有授权。技能不会增加审批步骤，也不会凌驾于仓库政策之上。
• 只有在规则会影响相关决策或防止有证据表明会发生的故障时才保留。删除通用建议、重复规则、过时的模型假设和施加修辞压力的内容。
• 保持描述简短：在第一句话中说明具体任务、触发条件和主要范围边界，以便内容截断时仍能保留技能的适用时机。仅在可能产生重叠时添加排除项。若流程只适用于更狭窄的问题，就避免让技能在每次代码编辑、测试或任务完成时都触发。
• 区分共享指导与仓库特定政策。先编辑共享源；同步时保留本地变体。安装程序覆盖技能之前，先检查整个目录的差异。

创建或修订

1. 明确预期结果、负责的文件、已知故障和现有说明。重用当前对话中的证据；仅重新收集缺失或过时的材料。
2. 在 SKILL.md 中保留最精简的通用约定；在链接分支特定参考资料时，注明适用条件和所需章节。只有在必须了解完整约定时，才阅读完整的架构或紧密关联的流程；默认不必阅读每份参考资料。
3. 仅在涉及依赖关系、变更、授权或清理时规定必需顺序。允许独立搜索并行进行，并让 Agent 自行决定常规实现细节。
4. 根据用户要求的交付物及其适用检查来定义完成标准。对未变更的输入重用已有证据。不要仅因已安装技能就额外要求提交报告、进行一轮子 Agent 协作、运行测试套件或请求确认。
5. 检查已更改的触发条件、链接、元数据及受影响的辅助行为。对于小型文案编辑，总结此次审查；对于新技能或大范围重写，使用 references/checklist.md。从源头修复实质性问题。

对于新软件包，请阅读 references/authoring-procedure.md；assets/SKILL.template.md 是可选模板。从技能的实际目录解析打包的辅助工具。只读元数据辅助工具为 python3 <writing-skills-dir>/scripts/validate-metadata.py --name "[name]" --description "[description]"。

诊断与衡量

如果遗漏了必要的参考资料，请使用 references/loading-diagnosis.md 区分触发条件不当、路径无法访问、规则冲突、内容过时和模型错误。应强化相关指引或修复辅助工具；默认不应通过额外强调来修复。

在实际可行时，使用相同模型和测试框架，在有代表性的任务上评估会改变行为的指导：检查正确性、返工、不必要的问题、工具调用和耗时。纳入成功运行作为对照。将参考资料读取次数和技能调用次数视为成本或诊断信息，绝不能将其本身视为成功。说明何时只进行了静态审查；没有对比运行时，不要声称效果有所提升。

需要时可查阅术语表：references/glossary.md。