技能文档重构实录：将大型SKILL.md拆分为引用骨架

技能文档重构实录：将大型SKILL.md拆分为引用骨架

卡点：500行限制与完整性的矛盾

"Refactor /Users/apple64/.agent/skills/jianfei-codex/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"

这是用户提出的需求。表面上是一个简单的重构任务：把一个可能超过500行的 SKILL.md 缩减到500行以内。但真正的卡点在于：如何在缩减行数的同时，不丢失任何关键信息？

如果直接删除内容，会导致技能定义不完整；如果简单压缩，会让文档变得难以阅读。用户给出的解法是："sink to references"模式——把详细内容"下沉"到引用文件中，SKILL.md 只保留骨架和引用链接。

用户如何提问：精确的模式复用指令

注意用户的提问方式："exactly as already applied to jianfei-ceo/jianfei-plan/jianfei-pc"。这不是一个模糊的"帮我重构"请求，而是一个精确的指令：

1. 指定了重构模式："sink to references"（下沉到引用）
2. 指定了约束条件：lint limit 500 lines
3. 指定了参考案例：jianfei-ceo、jianfei-plan、jianfei-pc 这三个技能已经用同样的方法重构过了
4. 指定了核心要求：content-preserving（保持内容完整性）

这种提问方式的精妙之处在于：用户不需要解释什么是"sink to references"模式，因为 Agent 可以去读取那三个已经重构过的技能文件，直接学习模式。

Agent 如何查源头：从参考案例中学模式

面对这个任务，Agent 的执行链应该是：

第一步：读取参考案例

Agent 需要先去读取 jianfei-ceo、jianfei-plan、jianfei-pc 的 SKILL.md，看看它们被重构后的样子。通过对比重构前（可能存储在 git history 中）和重构后的版本，Agent 可以总结出"sink to references"模式的具体做法。

假设 Agent 读取了 jianfei-ceo 的 SKILL.md，发现重构后的结构是：

# jianfei-ceo SKILL

## Overview
（简要描述，5-10行）

## Core Workflow
（核心工作流，20-30行）

## Detailed Guides
- [Setup Guide](./guides/setup.md)
- [Advanced Usage](./guides/advanced.md)
- [Troubleshooting](./guides/troubleshooting.md)

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

原来的 SKILL.md 可能有 800+ 行，详细的使用指南、API 参考、配置说明都写在同一个文件里。重构后，详细内容被"下沉"到 guides/ 和 reference/ 子目录中的独立 .md 文件里，SKILL.md 只保留骨架（概述、核心工作流、引用链接），总行数控制在 500 行以内。

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

Agent 读取 /Users/apple64/.agent/skills/jianfei-codex/SKILL.md，分析它的结构：

• 哪些章节是"骨架"（必须保留在 SKILL.md 中的核心信息）？
• 哪些章节是"详细内容"（可以下沉到引用文件中的）？
• 当前的行数是多少？需要削减多少？

假设 jianfei-codex SKILL.md 当前有 1200 行，包含以下内容：

• Overview（50行）
• Installation（100行）
• Core Commands（200行）
• Advanced Configuration（300行）
• Troubleshooting（150行）
• API Reference（250行）
• Examples（150行）

第三步：应用"sink to references"模式

根据从参考案例中学习到的模式，Agent 需要：

1. 保留在 SKILL.md 中的内容（骨架，约 200-300 行）：

   • Overview（精简到 10-15 行）
   • Core Commands（保留核心命令，精简到 50-80 行）
   • 引用链接（指向详细内容）

2. 下沉到引用文件中的内容（详细内容，约 900-1000 行）：

   • Installation → ./guides/installation.md
   • Advanced Configuration → ./guides/advanced-config.md
   • Troubleshooting → ./guides/troubleshooting.md
   • API Reference → ./reference/api.md
   • Examples → ./examples/README.md

3. 在 SKILL.md 中添加引用链接：

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

第四步：验证重构结果

重构完成后，Agent 需要验证：

1. 行数检查：SKILL.md 是否在 500 行以内？
2. 内容完整性检查：所有原来有的信息，是否都能通过引用链接找到？
3. 链接有效性检查：所有引用链接是否都指向存在的文件？
4. 可读性检查：SKILL.md 作为"骨架"，是否足够清晰，让人能快速理解技能的核心用法？

如何定位问题：当重构失败时的排查思路

如果用户发现重构后的 SKILL.md 有问题（比如丢失了关键信息、引用链接失效、或者行数仍然超标），排查思路应该是：

问题1：行数仍然超标

可能原因：Agent 没有充分应用"sink to references"模式，仍然在 SKILL.md 中保留了太多详细内容。

解决方法：重新审查 SKILL.md 的每一章节，问自己："这部分内容是'必须立即看到'的核心信息，还是'需要时可以查阅'的详细信息？"如果是后者，就应该下沉到引用文件中。

问题2：引用链接失效

可能原因：Agent 创建了引用文件，但路径写错了；或者引用文件被创建在了错误的位置。

解决方法：检查 SKILL.md 中的引用链接路径，与实际文件系统进行对比。确保相对路径是正确的（考虑到 SKILL.md 的位置）。

问题3：内容丢失

可能原因：Agent 在重构时，把某些内容"下沉"到了引用文件中，但在 SKILL.md 中没有添加对应的引用链接；或者 Agent 误删了某些内容。

解决方法：对比重构前后的 SKILL.md（可以从 git history 中恢复旧版本），逐章节检查是否有内容丢失。

判断转向点：用户没有要求直接改稿

这个场景的一个关键判断转向点是：用户没有要求 Agent "直接重构"，而是要求 Agent "先理解模式，再应用模式"。

用户的指令是："using a content-preserving 'sink to references' pattern, exactly as already applied to jianfei-ceo/jianfei-plan/jianfei-pc"。这句话的含义是：

1. 不要自己发明重构方法
2. 先去查看那三个已经重构过的技能
3. 学习它们的模式
4. 把同样的模式应用到 jianfei-codex

这种提问方式，体现了用户对 Agent 能力的精准理解：Agent 擅长"学习和应用模式"，而不是"从头发明新方法"。通过提供参考案例，用户降低了 Agent 出错的概率，也减少了反复沟通的成本。

结尾判断

技术内容（如何拆分文件、如何写引用链接）只是材料，提问过程（如何指定模式、如何提供参考案例、如何要求内容完整性）才是结构。好的重构不是"让文件变小"，而是"在变小的前提下，保持信息的可访问性和完整性"。

这次协作的经验，下一次可以直接复用：当你需要让 Agent 执行一个复杂的重构任务时，不要只描述目标，还要提供"已经做好的参考案例"，让 Agent 先学模式，再执行任务。