refine-skill-design

name	refine-skill-design
description	Audit and refactor existing SKILLs to meet spec compliance, repository asset boundaries, tool adaptation requirements, and LLM best practices.
description_zh	审计并重构既有 SKILL，使其符合规范、仓库资产边界、工具适配要求与 LLM 最佳实践。
tags	["writing","meta-skill","optimization"]
version	1.5.0
license	MIT
recommended_scope	user
metadata	{"author":"ai-cortex"}
triggers	["refine skill","skill design","audit skill","skill refactor","skill compliance"]
input_schema	{"type":"document-artifact","description":"Existing SKILL.md file to audit and refactor"}
output_schema	{"type":"document-artifact","description":"Optimized SKILL written to source SKILL.md (default) or to temp/new path when user opts out; includes diff summary and version suggestion"}

技能：完善技能设计

目的 (Purpose)

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

---

核心目标（Core Objective）

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

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

1. ✅ 结构兼容：技能遵循标准模板（YAML、目的、用例、行为、输入和输出、限制、自检、示例）
2. ✅ 逻辑清晰：输入→行为→输出链清晰明确
3. ✅ 定义的约束：限制部分涵盖了域中常见的故障模式
4. ✅ 资产边界清晰：Skill 不内嵌应由 Spec / Protocol / Rule 承载的权威定义；必要时改为引用或提出拆分建议
5. ✅ 执行适配明确：外部工具、MCP 工具、运行环境和缺失能力均有发现、映射、失败处理路径
6. ✅ 仓库契约合规：遵守 AGENTS.md、术语定义、外部链接、语言和资产优先级规则
7. ✅ 示例全面：至少提供 2 个示例，包括一种边缘情况或具有挑战性的场景
8. ✅ 记录的更改：差异摘要列出了所有更改以及部分、描述和原因
9. ✅ 建议版本：SemVer 建议并提供理由

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

---

范围边界

本技能负责：

• 审查现有技能草稿的质量和合规性
• 重构技能结构和内容以满足规范
• 审计 Skill / Spec / Protocol / Rule 边界，避免把结构契约、交互协议或单点规则埋进 Skill
• 审计工具适配层，确保 MCP / CLI / API 工具的发现、能力映射和缺失处理可执行
• 审计仓库本地契约，确保优化后的 Skill 遵守 AGENTS.md 和本地术语定义
• 提高逻辑清晰度和指令精度
• 添加缺失部分或加强薄弱区域
• 提供差异摘要和版本建议

本技能不负责：

• 从头开始创建新技能（使用人类/技能中的“技能创建者”）
• 运行包脚本或初始化工作流（使用 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. 资产边界：Skill 是否在定义事物结构（Spec）、多方消息序列（Protocol）或原子禁令（Rule）？若是，保留执行编排，将权威定义改为引用现有资产或提出拆分位置。
7. 执行适配：Skill 是否依赖 MCP / CLI / API / 外部服务？若依赖，是否说明如何发现可用工具、建立能力映射、处理工具缺失、避免硬编码不存在的工具名？
8. 仓库契约：若在 AI Cortex 仓库内优化，必须读取并应用 AGENTS.md 与 docs/architecture/terminology.md；不得默认抓取外部 HTTP/HTTPS 链接，除非上下文显式声明 allow_external_fetch=true。
9. 触发器（可选）：对于高可发现性技能，可以考虑在前面添加“触发器”（3-5 个英语短语），以实现快速调用匹配。

优化流程

1. 结构：应用标准模板（YAML、目的、用例、行为、I/O、限制、自检、示例）。
2. 动词：使用精确、明确的动词（例如“处理”→“解析”、“转换”、“修剪”）。
3. 交互：对于复杂的逻辑，添加“确认后再继续”或“选择选项”。与规范交互策略保持一致（默认优先，首选选择）。
4. 边界：把权威结构定义、消息序列和原子规则从 Skill 正文中降级为引用；若现有资产缺失，在差异摘要中列出建议新增的 Spec / Protocol / Rule，不要在本技能内凭空创建无关资产。
5. 适配：为工具依赖添加“发现 → 映射 → 执行 → 缺失处理”步骤；工具名以当前运行时实际暴露为准，示例工具名只能作为能力提示。
6. 本地契约：检查外链、raw URL、语言、资产优先级和本地路径优先策略；违反时改为本地引用或条件化说明。
7. 元数据：将标签与 INDEX.md 对齐；建议高可发现性技能的 triggers；建议合理的 SemVer。
8. 应用更改：除非用户明确要求空运行/临时细化文件，否则将细化内容直接回写到源 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 引用而未实际创建 Spec / Protocol / Rule，必须在输出中说明“建议拆分”，不能声称资产已存在。
• 不要绕过本地契约：在禁止默认外部抓取的仓库中，不得把外部 URL 写成执行必需来源；只能作为条件允许时的参考来源。
• 尽量减少散文：更喜欢列表和表格而不是长自述文件样式的文本。
• 多个示例：不要只保留一个“幸福之路”示例；包括至少一个具有挑战性或极端情况的示例。

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

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

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

何时停止并交接：

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

---

自检（Self-Check）

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

• 结构兼容：技能遵循标准模板（YAML、目的、用例、行为、输入和输出、限制、自检、示例）
• 逻辑清晰：输入→行为→输出链清晰明确
• 定义的约束：限制部分涵盖了域中的常见故障模式
• 资产边界：Skill 未承载应由 Spec / Protocol / Rule 承载的权威定义；必要拆分已说明
• 执行适配：外部工具和 MCP 工具具备发现、能力映射、缺失处理路径
• 仓库契约：已应用 AGENTS.md、术语定义、外部链接和语言规则
• 示例全面：至少提供 2 个示例，包括一种边缘情况或具有挑战性的场景
• 记录的更改：差异摘要列出了所有更改以及部分、描述和原因
• 建议版本：提供 SemVer 建议并说明理由

流程质量检查

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

验收测试

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

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

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

---

示例（示例）

之前

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

之后

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

---

技能：拼写和术语

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

行为

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

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

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

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