# 重构技能结构重构超出 500 行限制或出现结构问题的 SKILL.md。该技能将扩展代码示例提取到“references/EXAMPLES.md”，将复合过程拆分为重点子过程，添加交叉引用以进行渐进公开，并验证该技能在重组后仍然完整且有效。 ## 何时使用 * 技能超过 CI 强制执行的 500 行限制 * 单个过程步骤包含多个不相关的操作，这些操作应该是单独的步骤 * 超过 15 行的代码块在 SKILL.md 中占主导地位并且可以被提取 * 该技能积累了打破标准六部分结构的临时部分 * 内容更新后，技能突破线路限制 * 技能审查标记了超出内容质量的结构问题 ## 输入 * **必需** ：要重构的 SKILL.md 文件的路径 * **可选**：目标行数（默认：目标为 500 行限制的 80%，即 ~400 行） * **可选** : 是否创建 `references/EXAMPLES.md` （默认值：是，如果存在可提取的内容） * **可选** : 是否拆分为多个技能（默认：否，优先提取） ## 程序 ### 步骤 1：测量当前行数并识别膨胀源阅读技能并创建逐节的行预算，以确定膨胀的位置。 # 总行数 wc -l <技能/<技能名称>/SKILL.md # 每个部分的行数（大约） grep -n "^## \|^### " 技能/<技能名称>/SKILL.md 对膨胀源进行分类： * **可提取**：代码块 >15 行、完整配置示例、多变量示例 * **Splittable** ：执行 2 个以上不相关操作的复合过程步骤 * **可修剪**：冗余解释，过于冗长的上下文句子 * **结构** ：不属于标准六部分结构的临时部分 **预期：** 行预算显示哪些部分尺寸过大以及每个部分适用哪种膨胀类别。最大的部分是主要的重构目标。 **失败时：** 如果该技能低于 500 行并且没有明显的结构问题，则可能不需要该技能。在继续之前验证重构请求是否合理。 ### 步骤 2：将代码块提取到引用/EXAMPLES.md 将超过 15 行的代码块移至“references/EXAMPLES.md”文件，在主 SKILL.md 中留下简短的内联片段（3-10 行）。 1. 创建引用目录： mkdir -p Skills/<技能名称>/references/ 2. 对于每个可提取的代码块： * 将完整代码块复制到描述性标题下的“references/EXAMPLES.md” * 将 SKILL.md 中的代码块替换为简短的 3-5 行片段 * 添加交叉引用：“请参阅 [EXAMPLES.md](references/EXAMPLES.md#heading) 了解完整配置。” 3. 结构 `references/EXAMPLES.md` 具有清晰的标题： # 例子 ## 示例 1：完整配置 [context]的完整配置文件： \````yaml # ...完整配置在这里... \```` ## 示例 2：多变体设置 ### 变体 A：开发 \````yaml # ... 开发配置 ... \```` ### 变体 B：生产 \````yaml # ... 产品配置 ... \```` **预期：** 提取所有 >15 行的代码块。主要的 SKILL.md 保留了简短的内联片段以提高可读性。交叉引用链接到提取的内容。 `references/EXAMPLES.md` 组织良好，带有描述性标题。 **失败时：** 如果提取代码块没有充分减少行数（仍超过 500），请继续执行步骤 3 进行过程拆分。如果该技能的代码块很少（例如，自然语言技能），请重点关注步骤 3 和 4。 ### 步骤 3：将复合程序拆分为有重点的步骤识别执行多个不相关操作的过程步骤并将它们分开。复合步骤的迹象： * 步骤标题包含“和”（例如“配置数据库并设置缓存”） * 该步骤有多个 Expected/On failure 块（或应该有） * 步骤超过 30 行 * 该步骤可以跳过，也可以按照与其子部分不同的顺序完成对于每个复合步骤： 1. 识别步骤中的不同操作 2. 为每个操作创建一个新的`### Step N:` 3. 重新编号后续步骤 4. 确保每个新步骤都有自己的预期和失败块 5. 在新步骤之间添加转换上下文 **预期：** 每个过程步骤只做一件事。任何步骤都不超过 30 行。步数可能会增加，但每个步骤都是可独立验证的。 **失败时：** 如果拆分步骤会产生过于细化的步骤（例如，总共 20 个以上步骤），请考虑将相关的微步骤分组到单个步骤下，并使用编号的子步骤。最佳点是 5-12 个程序步骤。 ### 步骤 4：将 SKILL.md 中的交叉引用添加到提取的内容确保主 SKILL.md 在提取后保持可读性和可发现性。对于每次提取： 1. SKILL.md 中的内联代码片段对于常见情况应该是自给自足的 2. 交叉引用应解释哪些附加内容可用 3. 使用相对路径：`[EXAMPLES.md](references/EXAMPLES.md#section-anchor)` 交叉引用模式： * 在简短的代码片段之后：“请参阅 [EXAMPLES.md](references/EXAMPLES.md#full-configuration) 了解包含所有选项的完整配置。” * 对于多变体示例：“请参阅 [EXAMPLES.md](references/EXAMPLES.md#variants) 了解开发、暂存和生产变体。” * 对于扩展故障排除：“请参阅 [EXAMPLES.md](references/EXAMPLES.md#troubleshooting) 了解其他错误场景。” **预期：** 每个提取都有相应的交叉引用。读者可以按照常见案例的主要 SKILL.md 进行操作，并深入参考参考资料以了解详细信息。 **失败时：** 如果交叉引用使文本流畅，请在过程步骤结束时将多个引用合并为一个注释：“有关包括 [X]、[Y] 和 [Z] 的扩展示例，请参阅 [EXAMPLES.md](references/EXAMPLES.md)。” ### 步骤 5：重构后验证行数所有更改后重新测量 SKILL.md 行数。 # 查看主要技能.md 行=$(wc -l <技能/<技能名称>/SKILL.md) [ "$lines" -le 500 ] && echo "SKILL.md: OK ($lineslines)" || echo "SKILL.md: 仍然结束 ($lines 行)" # 检查引用文件是否已创建 if [ -f Skills/<技能名称>/references/EXAMPLES.md ];然后 ref_lines=$(wc -l <技能/<技能名称>/references/EXAMPLES.md) echo "EXAMPLES.md: $ref_lines 行" 菲 # 总内容 echo "总内容: $((lines + ${ref_lines:-0})) 行" **预期：** SKILL.md 少于 500 行。最好在 400 行以下，为未来的增长留出空间。 `references/EXAMPLES.md` 没有行数限制。 **失败时：**如果提取拆分后仍然超过500行，请考虑是否将该技能分解为两个单独的技能。涵盖太多领域的技能是范围蔓延的标志。使用“create-skill”来创作第二个技能并更新这两个技能中的相关技能交叉引用。 ### 步骤 6：验证所有部分仍然存在重构后，验证该技能仍然具有所有必需的部分并且前面的内容完好无损。运行“review-skill-format”清单： 1. YAML frontmatter 正确解析 2. 存在所有六个必需部分（何时使用、输入、过程、验证、常见陷阱、相关技能） 3. 每个过程步骤都有 Expected 和 On failure 块 4. 没有孤立的交叉引用（所有链接都解析） # 快速部分检查对于“## 何时使用”“## 输入”“## 过程”“## 常见陷阱”“## 相关技能”中的部分；做 grep -q "$section" Skills/<技能名称>/SKILL.md && echo "$section: OK" ||回显“$部分：丢失” 完成 grep -qE "## 验证（检查表）？" Skills/<技能名称>/SKILL.md && echo "验证：OK" || echo“验证：缺失” **预期：** 所有部分均存在。提取过程中没有意外删除任何内容。 SKILL.md 中的交叉引用解析为 EXAMPLES.md 中的实际标题。 **失败时：** 如果某个部分被意外删除，请从 git 历史记录中恢复它： `git diff Skills//SKILL.md` 以查看发生了什么变化。如果交叉引用被破坏，请验证 Examples.md 中的标题锚点是否与 SKILL.md 中的链接匹配（GitHub 风格的 Markdown 锚点规则：小写、空格连字符、去掉标点符号）。 ## 验证 * SKILL.md 行数为 500 或更少 * SKILL.md 中的所有代码块不超过 15 行 * 提取的内容位于带有描述性标题的“references/EXAMPLES.md”中 * 每个提取在主 SKILL.md 中都有交叉引用 * 不再保留复合过程步骤（每个步骤只做一件事） * 重构后所有六个必需部分都存在 * 每个过程步骤都有 **预期：** 和 **失败：** 块 * YAML frontmatter 完整且可解析 * 交叉引用链接解析为 EXAMPLES.md 中的实际标题 * `review-skill-format` 验证传递了重构的技能 ## 常见陷阱 * **过于激进地提取**：将所有代码移至引用会使主 SKILL.md 不可读。对于常见情况，保持 3-10 行片段内联。仅提取>15行或显示多个变体的块。 * **损坏的锚链接**：GitHub 风格的 Markdown 锚在某些渲染器中区分大小写。在 EXAMPLES.md 中使用小写标题并在交叉引用中完全匹配。使用 `grep -c "heading-text"references/EXAMPLES.md` 进行测试。 * **在拆分期间丢失预期/失败**：拆分复合步骤时，确保每个新步骤都有自己的预期和失败块。拆分后很容易在没有这些块的情况下离开一步。 * **创建太多小步骤**：拆分应产生 5-12 个过程步骤。如果你最终得到 15+，那么你分裂得太激进了。将相关的微步骤合并回逻辑组。 * **忘记更新引用/EXAMPLES.md 标题** ：如果重命名 EXAMPLES.md 中的某个部分，则必须更新 SKILL.md 中的所有交叉引用锚点。 Grep 查找旧锚点名称以捕获所有引用。 ## 相关技能 * `review-skill-format` — 重构后运行格式验证以确认技能仍然兼容 * `update-skill-content` - 当内容更新超出行限制时，内容更新通常会触发结构重构 * `create-skill` — 在决定如何组织提取的内容时参考规范结构 * `evolve-skill` - 当一项技能需要分成两个单独的技能时，使用进化来创建衍生技能

重构技能结构

包含技能