统一技能文档规范：多SKILL文件的一致性重构实践

统一技能文档规范：多SKILL文件的一致性重构实践

卡点：当多个SKILL.md需要同时重构

"Refactor /Users/apple64/.agent/skills/jianfei-kimi/SKILL.md (lint limit 500 lines) using a content-preserving 'sink to references' pattern, exactly as already applied to jianfei-ceo/jianfei-plan/jianfei-pc"

这个场景与重构单个 SKILL.md 的最大区别在于：这是一次"多 SKILL 一致性重构"的任务链中的一环。用户不是在孤立地重构 jianfei-kimi，而是在重构一系列 jianfei-* 技能，要求它们采用相同的文档结构和引用模式。

真正的卡点不是"如何重构一个 SKILL.md"，而是：如何确保多个 SKILL.md 在重构后，保持文档结构的一致性？当协作者或 Agent 阅读不同技能的文档时，能否快速建立统一的心理模型？

用户如何提问：隐式的批量重构指令

注意用户的提问方式："exactly as already applied to jianfei-ceo/jianfei-plan/jianfei-pc"。这句话的关键词是"already applied"——说明这三个技能已经完成了重构，jianfei-kimi 是下一个。

用户的完整意图是：

1. 批量重构任务：不止重构 jianfei-kimi，而是重构所有 jianfei-* 技能
2. 一致性要求：所有重构后的 SKILL.md 必须采用相同的模式
3. 参考标准：jianfei-ceo/jianfei-plan/jianfei-pc 是已经完成的参考标准
4. 逐步执行：先重构 jianfei-kimi，后续可能还有 jianfei-codex、jianfei-xxx...

这种提问方式的精妙之处在于：用户不需要重复解释重构模式，因为参考标准已经存在。Agent 只需要"学习参考标准 → 应用到新技能"即可。

Agent 如何查源头：从多个参考案例中抽象通用模式

面对"多 SKILL 一致性重构"任务，Agent 的执行链应该是：

第一步：读取所有参考案例，抽象通用模式

不是只读取一个参考案例，而是读取所有已经重构完成的技能（jianfei-ceo、jianfei-plan、jianfei-pc），对比它们的结构，抽象出通用模式。

假设 Agent 读取了三个参考案例，发现它们的 SKILL.md 都遵循以下结构：

# {Skill Name} SKILL

## Overview
（10-15行，简要描述技能用途、适用场景、核心能力）

## Quick Start
（20-30行，最简单的使用示例，让用户30秒内知道怎么用）

## Core Workflow
（50-80行，核心工作流，分步骤说明）

## Detailed Guides
- [Installation](./guides/installation.md)
- [Configuration](./guides/configuration.md)
- [Advanced Usage](./guides/advanced-usage.md)
- [Troubleshooting](./guides/troubleshooting.md)

## Reference
- [API Reference](./reference/api.md)
- [Command List](./reference/commands.md)
- [Configuration Options](./reference/config-options.md)

## Examples
- [Basic Examples](./examples/basic/README.md)
- [Advanced Examples](./examples/advanced/README.md)

Agent 需要总结出：

1. 必需的章节：Overview、Quick Start、Core Workflow（必须保留在 SKILL.md 中）
2. 可选的章节：Detailed Guides、Reference、Examples（内容下沉到引用文件，SKILL.md 中只保留引用链接）
3. 文件组织规范：
   • 详细指南放在 ./guides/ 目录
   • 参考文档放在 ./reference/ 目录
   • 示例放在 ./examples/ 目录
4. 行数控制目标：SKILL.md 控制在 300-500 行以内

第二步：分析 jianfei-kimi SKILL.md 的当前结构

Agent 读取 /Users/apple64/.agent/skills/jianfei-kimi/SKILL.md，分析：

1. 当前行数：是否超过 500 行？
2. 当前结构：是否已经有 Overview、Quick Start、Core Workflow 等章节？
3. 内容分布：哪些内容可以下沉到引用文件中？
4. 与参考案例的差异：当前结构与参考案例的标准结构有哪些不一致的地方？

假设 jianfei-kimi SKILL.md 当前有 900 行，结构是：

# jianfei-kimi SKILL

## 简介（对应 Overview，但写得太长，有 80 行）
## 安装方法（对应 Installation，100 行）
## 配置说明（对应 Configuration，200 行）
## 核心功能（对应 Core Workflow，但只有 30 行，不够详细）
## API 文档（对应 API Reference，250 行）
## 常见问题（对应 Troubleshooting，但混在配置说明里）
## 示例代码（对应 Examples，但直接写在 SKILL.md 里，150 行）

第三步：应用通用模式，重构 jianfei-kimi

根据从参考案例中抽象出的通用模式，Agent 需要：

1. 调整章节顺序：按照参考案例的标准结构重新组织章节（Overview → Quick Start → Core Workflow → Detailed Guides → Reference → Examples）

2. 精简必需章节：

   • Overview 从 80 行精简到 15 行
   • 添加 Quick Start 章节（原来缺失）
   • Core Workflow 从 30 行扩充到 60 行（原来写得不够详细）

3. 下沉详细内容：

   • 安装方法 → ./guides/installation.md
   • 配置说明 → ./guides/configuration.md
   • 常见问题 → ./guides/troubleshooting.md
   • API 文档 → ./reference/api.md
   • 示例代码 → ./examples/README.md

4. 添加引用链接：

   ## Detailed Guides
   - [Installation Guide](./guides/installation.md)
   - [Configuration Guide](./guides/configuration.md)
   - [Troubleshooting](./guides/troubleshooting.md)
   
   ## Reference
   - [API Reference](./reference/api.md)
   
   ## Examples
   - [Usage Examples](./examples/README.md)
   

5. 验证行数：确保重构后的 SKILL.md 在 500 行以内

第四步：验证一致性

重构完成后，Agent 需要验证 jianfei-kimi 的 SKILL.md 与参考案例的一致性：

1. 结构一致性：章节顺序、章节名称是否与参考案例一致？
2. 文件组织一致性：引用文件的目录结构（guides/、reference/、examples/）是否与参考案例一致？
3. 风格一致性：标题格式、代码块格式、链接格式是否与参考案例一致？
4. 内容完整性：所有原来有的信息，是否都能通过引用链接找到？

如何定位问题：多SKILL重构中的常见陷阱

陷阱1：模式不一致

问题描述：Agent 重构了 jianfei-kimi，但结构与 jianfei-ceo 不一样（比如章节名称不同、文件组织方式不同）。

为什么会发生：Agent 只读取了一个参考案例，或者没有抽象出通用模式，而是照搬了某个参考案例的特定写法。

解决方法：在重构前，先读取所有参考案例，对比它们的结构，抽象出通用模式，写成一个"重构规范文档"（比如 ./docs/skill-refactoring-standard.md），然后再按照规范执行重构。

陷阱2：内容丢失或变形

问题描述：下沉到引用文件中的内容，在转移过程中丢失了某些信息，或者格式发生了变化（比如代码块的语言标记丢失）。

为什么会发生：Agent 在复制内容时，没有仔细核对；或者引用文件的格式与 SKILL.md 的格式有差异。

解决方法：在重构完成后，用 diff 工具对比"原 SKILL.md 中的内容"和"引用文件中的内容"，确保信息完整、格式正确。

陷阱3：引用链接失效或路径不一致

问题描述：SKILL.md 中的引用链接指向了错误的路径；或者不同 SKILL 的引用链接路径格式不一致（比如有的是 ./guides/installation.md，有的是 guides/installation.md）。

为什么会发生：Agent 在写引用链接时，没有遵循统一的路径规范。

解决方法：制定引用链接路径规范（比如"所有引用链接必须使用相对路径，以 ./ 开头"），并在重构后检查所有引用链接的有效性。

判断转向点：一致性优于局部优化

这个场景的一个关键判断转向点是：用户要求的不是"把 jianfei-kimi 重构到最好"，而是"把 jianfei-kimi 重构得与 jianfei-ceo/jianfei-plan/jianfei-pc 一致"。

这意味着：

1. 一致性优于局部优化：如果 jianfei-kimi 有某些特殊需求，导致它"最优"的结构与参考案例不一样，也应该优先保持一致，而不是局部优化。
2. 参考案例是标准：Agent 不应该"发明"新的结构，而应该"学习并应用"已有的标准。
3. 批量任务需要规范：当任务从"重构一个"变成"重构一系列"时，首先需要制定或学习"重构规范"，而不是每个都重新设计。

与mac-08的角度差异

文章8（技能文档重构实录）侧重的是"如何重构单个 SKILL.md"，核心是"sink to references"模式的应用技巧。

文章9（本文）侧重的是"如何一致性地重构多个 SKILL.md"，核心是"从参考案例中抽象通用模式，并确保所有重构结果符合该模式"。

简单来说：

• 文章8的问题是："如何把一个大文件拆小？"
• 文章9的问题是："如何把多个大文件拆小，且确保拆完后的结构一致？"

结尾判断

技术内容（如何拆分文件、如何写引用链接、如何验证一致性）只是材料，提问过程（如何指定参考标准、如何要求一致性、如何隐式表达批量任务）才是结构。好的多 SKILL 重构不是"每个都重构到最好"，而是"所有重构结果遵循相同的规范，让协作者能建立统一的心理模型"。

这次协作的经验，下一次可以直接复用：当你需要让 Agent 执行批量重构任务时，先提供一个"参考标准"（已经完成重构的案例），要求 Agent 先学习并抽象出通用模式，再应用到剩余的任务中。