一次讲透 Skill：分享一个我在公司内训的AI课程（上）

上次分享了我们在企业推进AI研发转型走过的弯路，所以先补充我们内部调研一组数据：我们大概抽样调查了100人，其中90% 成员都安装了 Claude Code，其中 53 人会日常用它做代码问答、片段补全，仅有 18 人尝试封装重复任务为 Skill，最终成功落地可复用半自动化工作流的仅 3 人。

这份上月调研结果我和多位朋友交流过，大家团队现状高度趋同，几乎都是一模一样的转化漏斗：安装工具的人基数很大，日常浅度使用的员工也不少，但能沉淀出标准化自动化流程的人寥寥无几。

单看工具普及率，90% 安装率在软件行业已经很不错，但关键断层出现在「安装工具」到「落地自动化工作流」中间。大量团队只停留在代码补全、临时提问的浅层使用，没能借助 Skill 放大 AI 研发价值。

这个内部 Skill 专项培训，就是为打通这段断裂的落地链路。培训内容先厘清 AI 工具的能力边界，完整拆解 Skill 的运行逻辑、落地方法与编写规范，最后结合真实项目演示从纯人工流程到可稳定运行 Skill 的完整落地全流程。

读完这套内容，大家可以独立搭建适配自身业务的专属任务 Skill，真正把 AI 从辅助工具变成标准化提效载体。

一、工具已经够强了，边界不在模型

先厘清核心前提：当下 AI 编程工具的性能早已不再是落地瓶颈。

以 Claude Code 为代表的工具，读工程、写代码、修改配置、执行命令、查阅文档等单点能力都已十分成熟。放在一年前还很难下这个结论，彼时大模型与配套工具尚不足以覆盖绝大多数研发场景；但经过今年上半年多轮迭代，AI 对研发全流程的覆盖能力实现明显跃升，这也是行业内普遍能感知到的变化。

既然工具能力足够，为何我们 80多份样本中，仅 3 人成功搭建起可稳定运行的自动化工作流？

很多人简单将问题归结为培训不足，但这个说法经不起推敲。我自身就踩过这条弯路：此前采购外部课程、组织集中学习，全力推动团队 AI 转型，最终收效微乎其微。后续调整策略，先由核心人员跑通完整链路再逐层推广，落地效果才逐步好转。不少同行团队也有着相同经历：课程质量过硬、工具性能优秀、团队人员专业能力在线，可 AI 自动化始终无法规模化落地。

落地难的根源，既不在工具本身，也不在于缺少培训课程，而是一个很少被点明的核心差距：区分使用者深浅的，从来不是是否安装 AI 工具，而是能否依托工具沉淀标准化任务流程。工具可以直接采购，但自动化流程需要结合业务场景沉淀搭建，横亘在二者之间的关键解法，正是本次培训要重点讲解的 Skill。

二、为什么需要 Skill，先看三个痛点

那次调研还统计了团队使用 AI 编程时遇到的痛点排名：

第一位，复杂任务下 AI 极易偏离需求，反复修改反而越改越乱；

第二位，AI 缺少项目专属上下文，输出内容脱离实际业务；

第三位，使用者不懂得精准、完整地描述任务需求。

放眼整个技术社区，开发者吐槽 AI 编程的内容，基本逃不开这三类问题。表面看各有成因：有人归咎于模型输出不稳定，有人认为 AI 不熟悉项目代码，也有人觉得是自身提问表达能力不足。但深挖一层就能发现，三者根源是同一个痛点：每次调用 AI 都要重复复述项目背景、开发规范、执行边界、输出标准，只要信息传递有遗漏，最终交付结果就会出现偏差。

日常使用时我们总能感受到这种低效：每次启动任务，都要重新说明项目技术栈、分析流程、交付格式、事实依据要求、风险校验节点等一系列约束条件。这些关键信息每次都靠临时口述，很难完整说清，但凡漏掉一条，AI 就容易产生幻觉、产出不合规内容。

本质上这并非大模型本身能力不足，而是反复传递信息带来的巨大损耗。相当于我们每次工作，都要临时向一位没有长期记忆的同事口头交代全部规则，信息传递天然存在残缺。

三、Skill 是写给 AI 的岗位 SOP

在推广 AI 自动化工具时，经常有人抛出一个疑问：把 Skill 存起来反复调用，和把提示词存在备忘录里复制粘贴使用，二者到底有什么本质差别？

这个问题问到了关键点，也是搞懂 Skill 价值的核心分界。

举个通俗的例子就能分清：带新人有两种截然不同的方式。第一种，每次开展任务前口头临时交代流程、规范与各类注意事项，新人能记下多少全凭当场记忆；第二种，把整套标准整理成固定岗位 SOP，后续遇到同类任务直接对照执行，规则、步骤、校验要求全部标准化留存。

备忘录里的提示词，还是第一种带法，只是把要说的话提前写好了，什么时候说、说哪段、有没有说全，还是靠人自己。而 Skill 是第二种，它把某一类任务的触发条件、执行步骤、参考资料、输出格式、验收标准提前写好，放在一个约定的位置，AI 遇到对应场景时自己翻出来照着干。

一句话，Skill 是写给 AI 的岗位 SOP。

它的工作机制有个专门的说法，叫渐进式披露，分三层。第一层，AI 平时只记着每个 Skill 的名字和一句功能描述，像人记得「公司有哪些 SOP 文档」但不用背下内容。第二层，判断当前任务和某个 Skill 相关了，才去读它的正文，拿到完整指令。第三层，正文里引用的模板、资料、脚本，用到哪个读哪个。

这个机制解释了一个常见疑问，装几十个 Skill 会不会把上下文撑爆。不会，因为常驻的只有名字和描述，正文和资产都是按需加载的。

到这里可以把几个容易混的概念摆在一张桌上了。提示词是临时口头交代，只管当前这一次对话。CLAUDE.md 是常驻的项目说明，每次对话都会加载，适合放少量长期有效的通用规则，像团队的通用规章。Skill 是按场景触发的任务说明，像具体的岗位 SOP。再往外还有两个，Subagent 相当于一个独立岗位，有自己的角色和上下文，适合长流程专项任务。Hooks 是流程门禁，在特定动作前后自动拦一道，比如提交代码前强制跑格式化。

通用规章不能太厚，人人都要读。岗位 SOP 可以很具体，因为只有干这个活的时候才翻。这个分寸感，放在 AI 身上一模一样。

还有一点要说清楚，Skill 不是让 AI 变聪明，是让它在更明确的边界内干活。只说「帮我看看这个项目」，AI 面前有一百条路可以走，它挑哪条全凭运气。Skill 做的事情是收窄路径，先做什么后做什么，哪些不能碰，读哪些材料，输出到哪里，做完怎么验收。路径收窄了，输出自然就稳了。

四、先用起来，再谈写

很多人上手 Skill 第一反应就是从零自研，但更顺滑、稳妥的落地路径应该反过来：先试用现成成熟技能摸清逻辑、建立体感，再结合自身业务定制专属 Skill。

市面上现成 Skill 主要有两大获取渠道：

一是 Anthropic 官方维护的开源仓库anthropics/skills，内置文档处理、前端工程开发等高频通用技能，可直接复用。在 Claude Code 内执行插件命令/plugin marketplace add anthropics/skills，接入官方技能市场后就能按需一键安装；也能直接克隆仓库本地部署使用。

二是第三方社区聚合平台skills.sh，相当于全品类 Skill 应用商店，收录了全球开发者产出的各类细分技能，覆盖开发、文档、测试等更多垂直场景，选择范围更广，包括腾讯的skillhub等。

还有一点值得重点关注：Skill 如今拥有统一的Agent Skills 开放标准，不存在工具绑定锁死的问题。同一份 Skill 配置文件，除 Claude Code 外，Cursor、Codex CLI 等主流 AI 编程工具均已陆续兼容适配。这意味着我们沉淀的技能资产可以跨工具复用，前期投入不会随工具切换作废，大幅拉高了落地 Skill 这件事的投入性价比。

装的时候会遇到一个选择，放哪。位置就两个。

个人级放在用户目录下的 ~/.claude/skills/，对这台机器上的所有项目生效，适合个人高频习惯，比如自己的代码导读方式、日报格式。项目级放在项目仓库里的 .claude/skills/，跟着代码一起提交，团队成员拉下代码就能共享，适合项目统一规范，比如这个项目的 Review 标准、交付文档模板。

判断标准一句话，个人习惯放个人目录，团队规范放项目目录。

触发方式有两种。一种是自动的，AI 根据你说的话判断该不该用某个 Skill，这也是 Skill 的主要用法。另一种是手动的，直接输入斜杠加技能名，强制调用。自动触发靠不靠谱，取决于 Skill 的描述写得好不好，这个马上讲到。

五、拆开看，一个 Skill 长什么样

一个 Skill 的物理形态简单到有点意外，一个文件夹，加一个必须存在的 SKILL.md 文件。

class="language-text">legacy-code-guide/├── SKILL.md       "color:#6a9955"># 核心说明文件，唯一必需├── templates/     "color:#6a9955"># 输出模板├── references/    "color:#6a9955"># 长规范、背景资料├── scripts/       "color:#6a9955"># 可执行脚本└── assets/        "color:#6a9955"># 样例、辅助材料

最小可用的 Skill 只需要一个 SKILL.md，四个辅助目录都是可选的，用到再加。

打开 SKILL.md，分成两部分。顶部是用三条横线包起来的元数据，最少写两个字段。

class="language-yaml">---name: legacy-code-guidedescription: 老项目代码导读。当用户需要理解陌生项目、接手老代码、进行二次开发前分析时使用。不适用于单文件解释和代码 Review。---

name 是技能名，用小写字母、数字和连字符。description 是整个 Skill 里最重要的一行字，AI 就靠它判断什么时候该用这个 Skill，写得好，该出手时就出手，写得不好，要么装死要么乱入。

元数据下面是正文，管的是触发之后怎么执行。角色定位、工作步骤、输入要求、输出格式、约束条件、验收标准、要读哪些模板和资料，都写在这里。

记住一句话就够了，description 管「何时用」，正文管「怎么干」。

四个辅助目录，各有各的位置。

这张表里藏着一个多数人会踩的坑，把文件放进目录不等于它会被用上。references 里的规范如果正文没有一句「生成文档前先读取某某文件」，AI 很可能根本不看它。目录是仓库，正文才是调度员。

这四类资产怎么组合出威力，下篇会用一个完整案例展开，这里先记住它们的存在。

六、好 Skill 长什么样，五条标准

动手编写 Skill 前，先要建立一套评判逻辑。行业内衡量一套 Skill 是否合格，可归纳为五条核心标准；编写时可对照自查，评审他人产出的 Skill 时，也能以此作为统一衡量标尺。

第一条，触发条件清晰。description 要写清做什么、什么时候用、什么时候不用。看一组对照就明白了。

class="language-yaml">description: 处理文档

这种写法等于没写，AI 不知道处理什么文档，也不知道边界在哪。改成这样，

class="language-yaml">description: 生成项目交付文档。当用户提出「生成交付文档」「编写交付材料」「整理项目交付说明」时使用。不适用于需求文档、设计文档和会议纪要。

做什么、典型触发语句、排除场景，三样都有了，触发就稳了。

第二条，流程简洁明确。SKILL.md 写流程，长资料放 references，模板放 templates，不要把三百行规范全文塞进正文，那会稀释真正重要的任务指令。

第三条，规则说明原因。不要只写禁止事项，要说明约束背后的目的。「不得推测配置项」后面跟一句「因为交付文档中的错误配置会直接导致客户环境事故」，AI 对规则的执行质量是不一样的。

第四条，约束匹配风险。高风险任务强约束，低风险任务给空间。只读分析类的任务，锁住分析顺序和输出格式就够了，不用规定它每步只能读哪个文件。写文件、动配置的任务，就要把边界钉死。

第五条，结果可验收。输出的格式、路径、依据要求、未确认事项，都要能检查。写不出验收标准的 Skill，大概率写的人自己也没想清楚要它干什么。

在套用五条评判标准前，先要分清边界：哪些任务值得封装成 Skill，满足以下三个条件才适合改造：

像存量项目梳理、交付文档撰写、测试用例生成、代码评审、研发周报整理这类工作，完全符合标准，优先做成 Skill；而一次性需求、每次业务逻辑差异极大、重度依赖主观创意与复杂临场判断的工作，没必要封装，直接临时对话处理更高效。

另外有一条落地铁律：先跑通，再固化。

先用普通对话完整跑通一次任务，验证流程顺畅、输出结果达标，再把这套成熟的执行逻辑沉淀为 Skill。如果流程本身就存在漏洞、产出不稳定，强行封装只会持续批量产出不合格内容。Skill 本质是成熟可行工作经验的载体，而非未经验证思路的固化工具。

七、实战，从人工流程到第一个 Skill

理论铺垫完毕，下面结合用一个完整落地的真实项目跑一次完整的流程

就以腾讯开源 RAG 知识库框架 WeKnora 为例：技术栈涵盖 Go 后端、Vue 前端、Python 文档解析服务，运行依赖数据库、缓存、对象存储、向量库全套组件，整体代码量 33 万行，架构、规模和我们日常客户业务系统高度贴近，用来练手具备很强参考价值。

本次要封装的任务也是团队真实高频需求：接手存量项目做二次开发、对接内部自有数据源。这恰好对应前期调研里排名靠前的核心痛点 —— 接手老旧项目、难以读懂陌生代码，也是绝大多数研发人员日常最头疼的场景。

第一步，先别想 Skill，想清楚人是怎么干这活的。

一个有经验的工程师接手陌生项目，通常是这么一套。读 README 和部署说明，搞清项目定位和运行方式。找程序入口，理解启动流程和配置加载。梳理核心目录，判断接口层、业务层、数据层各在哪里。追一条核心业务链路，比如文档从上传、解析、向量化到检索、回答生成，是怎么流过整个系统的。最后记下二次开发的切入点、有风险的配置、没搞清楚的问题。

这套流程不是随机的，是一代代工程师用半天到一天的时间成本换出来的方法。但它有个致命伤，难以沉淀。工程师花一天建立的项目认知，大部分留在脑子里，下一个接手的人，重新再花一天。团队就这样反复支付同一笔认知成本。

第二步，看看直接把任务丢给 AI 会怎样。

直接输入「帮我看看这个项目」，AI 会给你一份概览，技术栈、目录结构、README 复述，都对，但都浅。核心链路在哪，服务之间怎么协作，扩展点在哪，哪些结论有代码依据，哪些只是它的推断，一概没有。这不是 AI 不能做，是任务要求给得不完整。又回到那个病根了，交代不全，结果就偏。

第三步，把人工流程逐条翻译成 Skill 指令。

这是整个构建过程的核心动作，而它简单得可能让你失望。人工会先读 README，Skill 正文就写「第一步，识别项目定位和运行方式」。人工会找程序入口，就写「第二步，定位启动入口和配置加载链路」。人工会看核心目录，就写「第三步，输出模块地图」。人工会追业务链路，就写「第四步，梳理核心数据流，标注跨服务边界」。人工会记风险，就写「第五步，输出二次开发切入点、风险清单和未确认事项」。

写的人没有发明任何东西，只是把已有的经验结构化、文字化了。这就是为什么写 Skill 的门槛比想象中低，难的部分你早就会了，那就是你的专业本身。

description 按五条标准的第一条来写，

class="language-yaml">description: 老项目代码导读，输出结构化项目导读文档。当用户需要「看懂这个项目」「梳理代码结构」「接手老项目」「分析二次开发切入点」时使用。不适用于单文件代码解释、代码 Review 和缺陷修复。

输出格式锁死，要求最终生成一份固定六章的项目导读文档，一句话定位、技术栈与服务清单、核心模块地图、核心业务链路、二次开发指引、风险与未确认事项。约束写三条，所有关键结论必须标注文件路径依据，无法确认的信息必须标「未确认」不得推测，只读分析不许改任何文件。验收标准对着约束一条条列。

因为这是只读分析任务，风险低，所以按第四条标准，约束到这个程度就够了，不用把每一步锁死。

第四步，跑，然后对比。

写完 SKILL.md，中间来回改了几轮，然后用同样一句话触发，「帮我梳理一下这个项目，我要做二次开发」，看它按步骤走完，产出一份导读文档。

这份文档值得说细一点。技术栈清单，Go 15 万行、TypeScript 和 Vue 16 万行、Python 1.5 万行，框架用的 Gin 和 GORM，前端 Vue 3 加 Vite，每一项后面跟着依据来源。业务规则那部分更狠，一条规则、一个代码位置精确到文件和行号、一个置信度标注，「系统同时支持 JWT 和 API Key 两种认证」，后面跟着 auth.go 第 82 行，标注「已验证」。没把握的地方，老老实实写着「推断」和「未确认」。二次开发指引那章，接入自有数据源要动哪几个模块、风险在哪，列得清清楚楚。

同样一句话，没有 Skill 的时候得到一份客气的概览，有 Skill 的时候得到一份可以直接归档交接的团队资产。差异不在模型，模型是同一个，差异在流程有没有被固化下来。

这个案例讲完，上篇要教的动作其实就走完了一整圈。找一个你重复干过很多次的活，把人工流程写下来，逐条翻译成指令，锁定输出格式，加上约束和验收标准，就是你的第一个 Skill。

写在最后

有两句实在话提前说清楚，避免大家上手后产生落差。

第一，你编写的第一个 Skill，效率大概率不如手动操作。封装 Skill 本身存在固定投入，初次搭建时，要反复拆解任务步骤、敲定各类约束规范，这段时间成本没法省去。评估 Skill 的价值不能只看第一次使用，要放到第十次、第五十次长期复用来看 —— 把每次重复交代背景、规则的成本压缩到仅付出一次，这才是 Skill 真正的提效逻辑。

第二，并非所有研发工作都适合做成 Skill。回到前面筛选任务的三条标准：高频重复、每次需同步相同上下文、产出可标准化。不满足条件的需求，直接临时对话处理即可，不必为了沉淀资产强行封装，反而徒增维护负担。

还有一个问题，当团队把资深工程师沉淀的整套分析流程全部封装为 Skill 后，新人接手项目时，会省去独自通读、摸索代码的过程。短期看交付效率确实提升，但新人少了在陌生目录反复试错、自己踩坑摸索出项目体感的成长过程，这份长期能力损耗到底算不算隐性成本，新人怎么成长，目前没有结论。

正因如此，我们这次培训不会只教大家直接调用现成 Skill，核心是教会每个人掌握自主搭建、拆解、编写 Skill 的底层能力，让新人既能借助工具快速落地业务，也能在构建 Skill 的过程中吃透项目逻辑，补齐本该有的深度思考与工程理解。

再回看开篇那组调研数据：90% 安装率与仅 3 人落地工作流的巨大落差，差距根源不在于模型版本、工具订阅成本，更不在于员工学习能力高低，核心区别在于是否懂得把成熟业务流程固化留存。

工程师最核心的价值，藏在脑海里那些未成文的解题思路与项目处理经验。以往这类隐性经验会随着人员离职、项目交接不断流失，而 Skill 提供了一套可运行、可复用的标准化载体，能够完整留存这套经验。

当下各家企业扎堆开展 AI 内部培训，但真正具备长期价值的核心动作，绝非单纯教会员工使用 AI 工具，而是将团队成员脑中零散的隐性经验，转化为企业可沉淀、可传承、可复用的数字资产。

AI 无法自主记忆上一轮对话的全部上下文，却能稳定读取、严格执行你提前定义好的整套标准化流程 SOP，这也是 Skill 相比临时对话、纯人工协作最核心的优势。

附，第一个 Skill 自查清单

下篇预告。

本篇内容主要帮大家跑通从零写出第一个可用 Skill的完整流程，而下一篇，我们将聚焦三个更硬核、更落地的团队规模化难题。

第一，彻底解决 AI 幻觉、杜绝瞎编。通过在 Skill 中固化团队模板、研发规范、标准脚本，搭配强制待确认校验清单，让 AI 在输出文档、代码、配置时，连 IP 地址、参数路径等细节都无法随意编造，输出完全可控可信。

第二，标准化 Skill 调试与修复方法论。Skill 写完不代表能用，我会分享三步验证法、九类异常症状诊断清单、单点最小迭代优化原则，把靠感觉改提示词的低效试错，升级成可复刻的工程化调试方法。

第三，从个人技能沉淀，升级为团队公共能力。拆解复杂 Skill 设计、多 Skill 联动衔接方案，讲解如何将成熟技能打包为插件全员分发复用。同时公开 Anthropic 内部数百条 Skill 的分类标准与规模化运营经验，完整复刻企业级 AI 提效体系。