write-a-skill

name	write-a-skill
description	创建、审查和维护 agent 技能（Skill）。Use when creating/refining a Skill or deciding whether Skill、command、hook、rule、AGENTS.md guidance is the right carrier.

编写 Skill

来源层级

• 【官方规范】: 目标平台要求，或被广泛记录的 Skill 行为。
• 【本地质量门槛】: 这个 LimCode Skill 采用的更严格默认标准。
• 【社区验证实践】: 来自真实用户反馈和开源实践验证的推荐模式。
• 【本设计扩展】: 用于提高可靠性的扩展，不是官方强制要求。

操作原则

创建能解决用户真实重复失败的最小可靠指令载体。可靠不是越完整越好；如果安全清单、eval、维护记录或额外目录会分散 agent 对任务本身的注意力，就降级、合并或删除。

工作流

1. 先选择载体【社区验证实践】。

   • AGENTS.md/rule：一两条长期成立的约定。
   • Command：用户手动触发的原子操作。
   • CLI/script/hook/CI：确定性、脆弱、重复或必须强制执行的操作。
   • Skill：需要可选引用材料的复杂可复用多步骤工作流。
   • 闸门：写文件前说明选择的载体，以及为什么更窄的载体不够。
   • 完整决策树见 references/carrier-decision-tree.md。

2. 写作前澄清结构边界【本设计扩展】。

   • 填写“已知/缺失/假设”矩阵：真实失败场景、目标用户、触发词、负例、输入、输出、工具、成功证据。
   • 检查结构属性：当前 prompt 外是否有必要上下文；输出是否会被当前回复之外的人、agent、工具或未来会话读取；是否会产生多份独立产物；是否触发 scripts、外部内容、secrets、网络/文件访问、破坏性或外部可见操作。
   • 如果关键事实缺失，只问缺失问题；如果上下文足够，先声明假设再继续。

3. 设计渐进披露和注意力预算。

   • 【官方规范】: 保持 SKILL.md 简洁，把详细或条件性材料放入支持文件，并在 SKILL.md 中引用。
   • 【本地质量门槛】: 除非用户明确接受更大的本地 Skill，否则 SKILL.md 控制在 100 行以内。
   • 【本设计扩展】: 每新增一个目录、章节、eval 或维护字段，都说明它会在实际执行中被谁读取、何时读取、解决什么失败。
   • 如果某部分只是“看起来完整”，但不会改善执行，删除它。
   • 若输出会被当前回复之外的消费者读取，或会产生多份独立产物，读取 references/distributed-context-boundary.md，设计外部化上下文、主题化信息库和无相对指代 prompt。

4. 编写合规 frontmatter。

   • 【官方规范】: name 必须匹配父目录，只使用小写字母、数字和连字符，长度不超过 64 字符，并避开禁用标记或平台保留词。
   • 【官方规范】: description 必须非空，低于目标平台限制，并说明 Skill 做什么以及何时使用。
   • 【本地写作规范】: 优先使用第三人称、关键词友好的描述；相似工作流容易混淆时，推荐写出负边界。
   • 结构细则见 references/skill-anatomy.md。

5. 正文写成任务流程，而不是治理流程【社区验证实践】。

   • 使用编号步骤、检查点、验证证据、陷阱提示和反合理化说明。
   • 优先写“agent 此刻该关注什么、忽略什么、产出什么”。
   • 避免把一个边界环境中的限制写成所有场景的默认限制。
   • 不要只写“永远不要做 X”；应写“不要做 X，改做 Y”。

6. 只打包真正需要的资源。

   • 【官方规范】: 只有在明显改善执行效果时，才创建 references/、scripts/ 或 assets/。
   • 【官方规范】: scripts 用于确定性工作，并必须输出可执行的错误信息。
   • 【本设计扩展】: evals/、MAINTENANCE.md、安全清单是风险触发项，不是每个 Skill 的默认配置。

7. 按风险选择评估和审查深度【社区验证实践】。

   • 简单本地 Skill：可只做正/负触发和人工试用。
   • 共享或高影响 Skill：加入 A/B、逻辑模拟、边界攻击、跨模型或跨 surface 测试。
   • 有 scripts、外部内容、secrets、破坏性操作或共享安装时，再读取 references/security-and-maintenance.md。
   • 发布评估结论前读取 references/evaluation-and-verification.md。

8. 用结构属性审查，而不是用场景标签审查【本设计扩展】。

   • 当前 prompt 外有必要上下文：审查是否提供文件路径或内联摘要。
   • 当前回复之外有人、agent、工具或未来会话会消费输出：审查是否禁止相对指代，并提供可定位上下文。
   • 产生多份独立产物、报告或审查结论：审查是否按主题组织状态、决策、证据、阻断项和报告。
   • 触发 scripts、外部内容、secrets、网络/文件访问、破坏性或外部可见操作：读取 references/security-and-maintenance.md，安全清单不可降级。
   • 每个额外产物都必须说明读取者、读取时机和解决的失败；否则删除。

输出契约

创建或修改 Skill 时，必须提供：

• 载体决策，以及为什么更窄的载体不够。
• 结构边界假设和注意力预算取舍。
• 目录树，且只包含实际会被使用的目录。
• 若触发外部消费者或多产物边界，说明上下文外部化方式、主题分类和回写规则。
• 完整文件内容或精确补丁。
• 验证方式：可轻可重，但必须匹配风险。
• 若触发风险条件，再提供安全清单、维护记录或评估文件；否则明确说明不创建的原因。

反合理化

借口	修正
“更好的 description 会让自动触发可靠。”	优化描述，但可靠性重要时加入 command、AGENTS.md 或 hook 兜底。
“用户给的上下文已经够了。”	先填写已知/缺失/假设矩阵。
“这只是文档。”	Skill 会改变 agent 行为；必须验证执行效果。
“评估触发过一次，所以可用了。”	至少测正例和负例；高风险再做 A/B 和回归。
“越完整越安全，总不会错。”	完整性会消耗注意力；不服务执行的字段、目录和清单都应删减。
“安全清单和维护记录应该默认加。”	只有风险边界触发时才加；普通工作流优先保持轻量。
“下游读者会理解聊天里的隐含指代。”	不会。凡脱离当前聊天记录无法唯一解析的指代，都必须改成文件路径或内联摘要。