AI 热点监控工具的 Skill 封装走过三段路：早期把流程硬写进系统提示，中期拆成独立提示但共享外部依赖，收尾时收敛为每个 Skill 自带脚本与资源的自包含文件夹。胜出的不是某个框架，而是「一个技能一个目录、目录内自洽」这条原则——它同时解决了上下文膨胀、依赖漂移、跨环境不可移植三件事。下文复盘每版的问题与转折点。
一、三版方案的演进对比
| 版本 | 形态 | 优点 | 致命问题 |
|---|---|---|---|
| v1 内联提示 | 流程全写在系统提示里 | 零额外加载 | 上下文爆、改一处全崩 |
| v2 外链拆分 | 提示拆文件，引用共享库 | 提示变短 | 共享依赖漂移、路径易断 |
| v3 自包含 | 每技能自带脚本与资源 | 可移植、可版本化 | 目录略多，需约定规范 |
二、v1：内联提示的坍塌
项目刚起步时，抓热点、判趋势、做摘要全写进同一条系统提示。跑通快，但话题一多，提示被前段规则占满，后段「风险分级」约束常被模型忽略。更糟的是，任何一处微调都要重发整段提示，回归成本高。
- 所有环节共用一份长提示，无隔离；
- 模型靠后环节注意力被稀释，约束失效；
- 改动牵一发动全身，迭代风险高。
三、v2：外链拆分留下依赖债
中期把各环节提示拆成文件，按阶段加载，上下文压力缓解。但团队把「打分脚本」「摘要模板」抽成全局共享模块，各 Skill 用相对路径去引用。问题在共享模块：某次改了 shared/score.py 的接口，三个 Skill 同时报错；另一个 Skill 被挪目录后，引用路径断掉，加载即失败。拆分减了提示体积，却背上了隐性依赖债。
3.1 v2 的典型断裂写法
# grade-risk/SKILL.md 里写：
# 请调用 ../../shared/score.py 进行打分
# 一旦 shared 被改名或移动，这条指令就悬空这种「跨目录指别人家东西」的结构，在多人协作与跨环境迁移时尤其脆弱。
四、v3：自包含文件夹收口
收尾方案对齐开放标准的 Skill 形态：每个技能是一个自包含目录，SKILL.md 描述流程，所需脚本落在自己的 scripts/，阈值与模板落在自己的 resources/，不向外伸手。调度层只认目录约定，不认全局共享。
skills/
grade-risk/
SKILL.md
scripts/score.py # 自带，不依赖外部
resources/thresholds.json
summary/
SKILL.md
resources/prompt.json # 自带模板自包含带来四点实打实的收益：
- 可移植：整个目录打包挪到任意支持该标准的平台即可跑，不带走外部包袱；
- 可版本化：一个 Skill 一个仓库或子目录，改
grade-risk不影响summary； - 确定性稳：打分脚本随技能走，结果不随运行环境漂移；
- 加载轻：调度层先扫
SKILL.md元信息做匹配，命中才读全文与资源，上下文占用可控。
4.1 调度层只认目录约定
def load_skill(root: str, name: str) -> dict:
skill_dir = os.path.join(root, name) # 只信目录内
md = os.path.join(skill_dir, "SKILL.md")
script = os.path.join(skill_dir, "scripts", "main.py")
return {"meta": read_front(md), "script": script if os.path.isfile(script) else None}路径解析全部基于本目录，外部共享库被彻底剔除，断链风险归零。
五、为什么是「自包含」而非「更重的标准」
有人会问：干脆上更重的插件框架不行吗？对监控工具这类中等规模系统，自包含文件夹的复杂度刚好——比内联提示可控，比插件平台轻。它把「知识封装」和「连接外部系统」彻底分开：前者交给自带资源的 Skill，后者留给 MCP 之类的协议。职责清晰，迭代才不互相拖累。
更重的插件框架往往自带生命周期、依赖注入与中心化注册表，接入成本随之上升。监控工具的核心诉求很朴素：环节能拆、改动能隔离、换平台能带走。自包含文件夹恰好压在这条需求线上——没有注册表要维护，没有中心服务要起，一个目录拷贝即迁移。当系统规模还没到需要插件平台那一层治理时，过早引入反而把简单问题复杂化。
v3 的选择不是「技术先进」，而是「和当前规模契合」：用精简约定换高度可控。它没去追框架的完备性，只守住了「目录自洽、加载即用时、迁移不丢依赖」三条底线。这也是它能在团队里长期存活、没被下一版推翻的原因——一个方案若每次重构都要推倒重来，说明它解决的是表面问题；自包含方案胜出，胜在和项目真实体量对齐。
六、落地时的规范约定
自包含不是「随便建目录」，需要几条约定把松散文件夹收成可维护的资产。
- 命名用动词短句：
grade-risk、summary比skill_v2好定位、好搜索； SKILL.md的description统一写「当……时调用」，提升语义匹配命中率；- 脚本只依赖目录内
resources/，禁止import跨技能或全局共享模块； - 每个 Skill 单独版本化，改动发版前补一个基础测试用例；
- 调度层只认目录约定，不写死任何具体技能路径，新增技能零改主干。
这几条把「自包含」从理念落成纪律。新成员加一个热点分类 Skill，只要按约定建目录、写好 SKILL.md 与自带脚本，调度器扫一遍就能接入，主干代码一行不用动。正是这种「加能力不碰主干」的特性，让 v3 在团队协作下越跑越稳，也彻底埋掉了 v2 的依赖债。
常见问题（FAQ）
Q1：自包含会增加目录数量吗？
会，但每个目录自洽，维护成本反而低于共享依赖。
Q2：v2 外链拆分错在哪？
错在跨目录共享，模块一变多处断裂、路径易悬空。
Q3：自包含和 MCP 冲突吗？
不冲突。Skill 管流程封装，连外部系统仍交给 MCP。
