nesnilnehc/refine-skill-design

技能：完善技能设计

目的 (Purpose)

作为一项“元技能”，该技能审查并重构草稿形式的人工智能能力定义。它应用高级即时工程视角来提高逻辑稳健性、场景覆盖率和指令依从性，以便每项功能都满足LLM最佳实践。

---

核心目标（Core Objective）

首要目标：生成经过审查并重构的技能文档，以满足规范合规性和LLM最佳实践。

成功标准（必须满足所有要求）：

1. ✅ 结构兼容：技能遵循标准模板（YAML、目的、用例、行为、输入和输出、限制、自检、示例）
2. ✅ 逻辑清晰：输入→行为→输出链清晰明确
3. ✅ 定义的约束：限制部分涵盖了域中常见的故障模式
4. ✅ 示例全面：至少提供 2 个示例，包括一种边缘情况或具有挑战性的场景
5. ✅ 记录的更改：差异摘要列出了所有更改以及部分、描述和原因
6. ✅ 建议版本：SemVer 建议并提供理由

验收测试：人工智能代理能否在不同的环境中一致地应用这种精炼的技能，而不会产生歧义？

---

范围边界

本技能负责：

• 审查现有技能草稿的质量和合规性
• 重构技能结构和内容以满足规范
• 提高逻辑清晰度和指令精度
• 添加缺失部分或加强薄弱区域
• 提供差异摘要和版本建议

本技能不负责：

• 从头开始创建新技能（使用人类/技能中的“技能创建者”）
• 运行包脚本或初始化工作流（使用 Skills.sh 工具）
• 规划技能资产或参考（使用 Skills.sh 文档）
• 生成项目 docs/ 结构（由 AgentFabric runtime 或人工承接）

转交点：当 SKILL 被细化并提供差异摘要时，移交给用户进行审查和版本控制提交。

---

使用场景（用例）

• 新技能入门：代理生成新技能草案后进行专家审查。
• 质量修复：当技能在新模型上表现不一致时，请调整逻辑并加强示例。
• 一致性审查：检查新技能是否与 INDEX.md 中的标签体系和命名相匹配；确保 description、tags、triggers 足以支持语义发现。
• 升级：将简单的“格式化工具”转变为具有交互策略和错误处理的完整代理功能。

范围：此技能用于审查并重构现有技能，而不是从头开始创建。要学习如何创建新技能、规划脚本/引用/资产或运行 init/package 脚本，请使用 Skills.sh 的“技能创建器”（例如 anthropics/skills）。

---

行为（行为）

元审计模型

1. 意图：目的是否足够具体？避免使用“助手”、“实用程序”等模糊术语。
2. 逻辑：输入→行为→输出是否形成清晰的链条？
3. 约束：限制是否涵盖域中最常见的故障模式？
4. 示例：示例是否从简单到复杂并至少包含一种边缘情况？
5. 交互策略（规范§4.3）：行为是否规定默认值、选择选项以及哪些项目需要用户确认？首先首选默认值，首选选择，上下文推理。
6. 触发器（可选）：对于高可发现性技能，可以考虑在前面添加“触发器”（3-5 个英语短语），以实现快速调用匹配。

优化流程

1. 结构：应用标准模板（YAML、目的、用例、行为、I/O、限制、自检、示例）。
2. 动词：使用精确、明确的动词（例如“处理”→“解析”、“转换”、“修剪”）。
3. 交互：对于复杂的逻辑，添加“确认后再继续”或“选择选项”。与规范交互策略保持一致（默认优先，首选选择）。
4. 元数据：将标签与 INDEX.md 对齐；建议高可发现性技能的 triggers；建议合理的 SemVer。
5. 应用更改：除非用户明确要求空运行/临时细化文件，否则将细化内容直接回写到源 SKILL.md，并在输出中同时附上diff摘要与版本号建议，方便审阅和审核。

---

输入与输出 (Input & Output)

输入（输入）

• 一个需要优化的 SKILL Markdown 文档，或者一个草稿。

输出（输出）

• 优化的技能：满足规范的生产级 Markdown。
• 差异摘要：更改了什么以及原因。
• 版本建议：SemVer 推荐。

输出（Output） 持久化（文档处理）

规则：默认直接改进并覆盖原始SKILL.md，同时提供可审计的diff摘要与版本号建议；只有在用户明确要求“只生成精修草稿、不改源文件”时，才写入临时或新建精修文件。每次运行须在以下策略中二选一：

|战略|路径模式|行为 | | :--- | :--- | :--- | | 直接覆盖（默认）| 技能/<技能名称>/SKILL.md | 直接覆盖源文件，保证前置事项版本已更新，且在产出中包含变更摘要，属于审计 | | 固定温度（选择退出）| skills/<技能名称>/SKILL.refined.md | 在用户要求“不要改原文件，只给细化”时使用；每次运行覆盖相同的临时文件 | | 每次运行新（选择退出）| skills/<技能名称>/SKILL.refined.YYYYMMDD.md | 在用户要求“为这次细化保留单独的文件”时使用；每次运行创建新的细化文件 |

用户覆盖：如果用户指定路径或策略，请遵守它。否则使用直接覆盖。

---

限制（限制）

硬边界（Hard Boundaries）

• 默认覆盖但必须可审计：默认策略是直接覆盖源 SKILL.md，但必须同步更新 frontmatter 的 version，并在输出中提供完整的变更摘要，确保可审计。
• 尊重显式“稿草模式”请求：若用户明确要求“不要修改原文件”“只生成精炼草稿”等，则不得覆盖源SKILL.md，只能写入临时或新建精炼文件。
• 不要改变意图：优化必须保留技能的核心目的。
• 尽量减少散文：更喜欢列表和表格而不是长自述文件样式的文本。
• 多个示例：不要只保留一个“幸福之路”示例；包括至少一个具有挑战性或极端情况的示例。

技能边界 (Skill Boundaries)（避免重叠）

不要做这些（其他技能可以处理它们）：

• 从头开始创建新技能：生成初始技能结构和内容→使用“技能创建者”（如 anthropics/skills）
• 项目文档：生成 README → 使用 generate-standard-readme；生成 AGENTS.md → 使用 generate-agent-entry
• 文本去上下文化：删除 PII 或敏感信息 → 使用 decontextualize-text

何时停止并交接：

• 用户说“看起来不错”、“已批准”、“提交此”→ 细化完成，移交给用户进行版本控制
• 用户问「如何创建新技能？」 → 移交给技能创建者文档

---

自检（Self-Check）

核心成功标准（必须满足所有标准）

• [ ] 结构兼容：技能遵循标准模板（YAML、目的、用例、行为、输入和输出、限制、自检、示例）
• [ ] 逻辑清晰：输入→行为→输出链清晰明确
• [ ] 定义的约束：限制部分涵盖了域中的常见故障模式
• [ ] 示例全面：至少提供 2 个示例，包括一种边缘情况或具有挑战性的场景
• [ ] 记录的更改：差异摘要列出了所有更改以及部分、描述和原因
• [ ] 建议版本：提供 SemVer 建议并说明理由

流程质量检查

• [ ] 自举：此技能能否成功作用于自身（精炼自身）？
• [ ] 清晰度：没有域背景的代理能否重现行为结果？
• [ ] 合规性：是否存在所有必填部分和元数据字段？
• [ ] 意图保留：精炼后的技能是否保持了原技能的核心目的？
• [ ] 精确：动词是否具体且明确（不是“处理”等模糊术语）？
• [ ] 交互策略（规范§4.3）：行为是否有默认或基于选择的交互（如果适用）？
• [ ] 触发器（可选）：对于高可发现性技能，是否建议使用“触发器”？

验收测试

人工智能代理能否在不同的环境中一致地应用这种精炼的技能而不会产生歧义？

如果否：技能需要进一步完善。查看“行为”部分以确保清晰并添加更具体的说明。

如果是：细化已完成。向用户提供差异摘要和版本推荐。

---

示例（示例）

之前

名称：拼写检查 该技能检查拼写。 输入：多语言文本。 输出：更正后的文本。

之后

名称：波兰语-文本-拼写 描述：多语言文档的上下文感知拼写和术语纠正。 标签：[写作、质量控制] 版本：1.1.0

---

技能：拼写和术语

目的：识别并修复低级拼写错误和术语不一致，而不改变作者的意图或语气

行为

1. 检测语言。
2. 如果文本较长，则构建术语列表。
3. 区分“打字错误”和“故意风格”。

限制：不要更改专有名词或特定缩写，除非明显错误

示例 2：边缘情况 — 草案不明确

• 输入：技能草稿，其目的是“帮助用户处理文件”，没有用例或限制。
• 预期：确定意图（用具体动词替换“处理”：解析、转换、合并等）；添加用例和限制（例如，不要覆盖源代码；不要修改二进制文件）；添加至少一个边缘示例（例如空文件、非常大的文件、权限被拒绝）。