Agent 技能最佳实践优化

要解决的问题

Agent skill 写得越多，越容易陷入三类问题：结构靠感觉、资源堆在一起、质量检查只靠人工读。新建技能时，容易把触发条件、输出物、脚本和参考文档混在 SKILL.md 里；改进旧技能时，又很难判断哪些问题是结构性缺陷，哪些只是措辞冗长。这个技能面向的，是把“技能写作”从凭经验变成有明确参考、可分析、可复查的流程。

如何工作

它分两种模式：

• Create Mode：先澄清触发条件、使用场景和产出物，再把例子映射到资源类型，选择 Workflow、Task、Reference 或 Capabilities 结构，然后起草 SKILL.md 并补齐脚本、参考和资产。
• Improve Mode：读取目标技能，运行 analyze_skill.py 做自动分析，再对照 best-practices.md 和 fix-priority.md 做人工审计，把问题按 Critical、Recommended、Optional 分级修复。

它的关键不是直接给模板，而是要求把 references/best-practices.md、references/skill-anatomy.md、references/fix-priority.md 作为前置材料加载。自动分析负责结构问题，人工审查负责语气、简洁度、自由度和信息披露，最终用 quick_validate.py 校验并输出前后对比。

适用边界

这个技能适合已经明确要创建或优化 Agent skill 的工程师。它不替代业务判断，也不会凭空补充缺失的产品需求；如果原始技能缺少真实使用案例、目标用户或核心输出，仍需要先补齐上下文。对于只想做简单文案润色、不改变技能结构的场景，直接修改原文可能更合适。