我现在越来越不太相信很多团队嘴里的“我们已经把经验沉淀成 Skill 了”。不少时候，他们做的事情其实很简单：把原来聊天框里那段已经很长的 system prompt，挪进一个叫 SKILL.md、agent.md、workflow.md 的文件里，然后继续往里面堆规则、堆例外、堆工具说明、堆输出格式，最后给自己一种“我们已经工程化了”的幻觉。

这个判断可能不太讨喜，但我确实觉得，文件名变了，不等于能力边界变了；目录结构有了，也不等于系统就更可维护了。 如果一套 Skill 的本体仍然只是“一大段越来越长、没人敢改的说明文字”，那它本质上还是 prompt，只不过换了个更像工程资产的外壳。

我为什么会越来越警惕这种伪工程化

因为现在行业里的产品叙事，确实在把 Skill 往“可组合、可扩展、可维护的执行单元”那个方向推。Anthropic 对 Claude Code Skills 的官方描述很明确：Skill 是一个目录，入口是 SKILL.md，但它可以继续带模板、示例、参考文档、脚本，甚至用 ${CLAUDE_SKILL_DIR} 去调用同目录下的辅助程序。OpenAI 这边虽然产品形态不同，但也一直在把 instructions、files、actions、version history、workspace sharing 放到同一个工程对象里讲。

这背后的意思其实很清楚：平台方想推动的，不是“把提示词换个地方放”，而是“把做事方法拆成可以被引用、调用、升级和治理的部件”。所以如果你最后交出来的仍然是一坨 800 行文字说明，那你只是占了 Skill 这个词，没有拿到 Skill 这套工程收益。

真正的分界线，不是文件名，是可拆分性

我现在判断一个东西是不是“像样的 Skill”，不会先看它有没有 SKILL.md，而是看它能不能拆。

• 核心说明是不是保持在相对短小的范围，只负责导航和决策；
• 详细规则是不是挪到了单独的 reference 文件，而不是永远和主说明绑死；
• 可执行动作是不是由脚本承担，而不是让模型在 prompt 里“想象自己执行了脚本”；
• 输出格式是不是有模板或示例，而不是靠一大段自然语言反复描述；
• 工具边界是不是单独声明，而不是散落在各段说明里；
• 改一个局部规则时，需不需要重读整份大文档才能知道会不会炸别的地方。

Anthropic 的官方文档其实已经把这件事写得很直白了：SKILL.md 是入口，其他文件是可选支持材料；大块参考文档、API 规格和示例应该拆出去，需要时再加载；脚本可以被执行，而不是直接塞进上下文。甚至它还明确建议把 SKILL.md 控制在 500 行以内，因为一旦 Skill 被加载，这些内容会留在上下文里持续消耗 token。

my-skill/
├── SKILL.md          # 只放入口说明、触发条件、导航
├── reference.md      # 详细规则
├── examples.md       # 示例输出
└── scripts/
    └── helper.py     # 真正执行的逻辑

如果你的“Skill”长这样，我会更愿意承认它开始有工程形态。因为它至少体现出三个意识：主说明要瘦身、细节要分层、动作要可执行。

伪 Skill 最常见的症状

我最近看到最典型的反例，通常长这样：

• 一个 300 到 1000 行的总说明文件；
• 里面同时混着角色设定、业务规则、异常处理、工具说明、输出格式、few-shot 示例；
• 没有单独脚本，只有“如果需要请执行以下步骤”；
• 没有版本边界，所有人都直接改同一个大文件；
• 一旦行为不稳定，团队第一反应是继续往里加一条规则。

这套模式最大的问题不是丑，而是它会把系统慢慢推向一种很糟糕的维护状态：谁都知道它不干净，但谁也不敢动，因为每次修改都像在拆炸弹。

你很快会看到几个熟悉症状：

• 同样的问题改了三次，旧 bug 还是会回来；
• 新同事根本搞不清哪几段规则是关键、哪几段只是历史遗留；
• 上下文越来越长，但成功率并没有同步提升；
• 一旦工具 schema 或业务流程变了，整份说明文档都要重新梳；
• 评估时只能看最后结果，根本说不清它到底是靠什么成功或失败的。

为什么“继续加规则”几乎总是条坏路

因为长 prompt 最容易制造一种错觉：系统不稳定，不是结构有问题，只是规则还不够细。所以团队会本能地往里继续补：

- 如果字段 A 缺失，先尝试字段 B
- 如果字段 B 也缺失，先去查日志
- 如果日志里有 legacy 标记，跳过摘要
- 但如果是 enterprise 客户，仍然要生成 fallback 版本
- 输出时禁止使用表格，除非用户明确要求
- 但周报场景允许例外...

这类补丁一开始看起来都合理，最后却会把主说明变成一个既像策略表、又像 runbook、还掺着格式约束的混合怪物。问题不在于每条规则单独看对不对，而在于它们被塞进了同一个层级，导致系统没有结构，只有累积。

真正该做的，往往不是继续加规则，而是先问一句：这到底是导航规则、参考资料、模板约束，还是应该下沉成脚本的操作逻辑？不先分层，越修越乱几乎是必然的。

一个更像工程系统的拆法

如果我来收拾这类系统，我通常不会先重写 prompt，而是先拆责任：

• 把“何时触发、先看什么、什么时候停手”留在主说明；
• 把长篇业务规则挪到 reference 文档；
• 把固定输出样式挪到模板文件；
• 把数据清洗、格式转换、校验这些动作交给脚本；
• 把工具权限单独列清楚，不要让模型自己猜边界。

这样做的好处不是“更优雅”，而是你终于能回答几个过去答不出来的问题：到底是哪一层出了问题？是规则过时了，还是模板不对，还是脚本挂了，还是工具权限错了？只要责任边界出来了，维护才开始像维护系统，而不是维护一段神秘文字。

个人开发者别一上来就学最重的那套

不过我也不建议个人开发者看完这些就开始给自己的每个 AI 工作流都建目录、写 frontmatter、配脚本。那样很容易本末倒置。

对个人开发者来说，更现实的做法是只抓住最值钱的那部分：先识别重复任务，再做最小拆分。 也就是：

• 高频任务才值得封装；
• 先把主说明压短，再决定要不要拆 reference；
• 只有当某个动作重复、稳定、明确时，才值得写成脚本；
• 别把“我现在还没想清楚”伪装成“先写进 Skill 以后再说”。

很多一人项目其实不缺 Skill，缺的是最小稳定流程。流程没稳定之前，任何“工程化包装”都很可能只是增加维护负担。

如果你只花半天排查一次

我会建议你做一件很实在的事：打开你现在最常用的那份长说明，把每一段都标成四类之一：

• 入口导航；
• 参考规则；
• 输出模板；
• 应该下沉成脚本的执行逻辑。

如果你标完以后发现，大部分内容其实都挤在“入口导航”里，那说明你现在做的多半还不是 Skill，只是一个不断变长的 prompt 容器。

我的判断

Skill 这套东西真正有价值的地方，从来不是名字更高级，也不是目录更像工程项目。它的价值在于把经验从一段不可分析、不可拆分、不可局部修改的长提示词，转成有层次、有边界、能执行、能维护的结构化资产。

所以我现在会用一个很粗暴但很有效的标准来判断：如果你删掉文件夹和前置术语，这套东西还只剩下一大段说明文字，那它大概率还不是 Skill。它只是 prompt，写得更长了而已。

参考来源类型：Anthropic 官方 Claude Code Skills 文档、Anthropic Engineering 关于 Agent Skills 的文章、OpenAI 官方 GPTs / Actions / Workspace Agents 帮助文档。