我用 3 个月才感受到Skill 的价值｜一个文件让初级员工半天写出生产级 Agent

推荐语

一个文件让初级员工快速上手生产级Agent开发，揭秘Skill如何成为能力传递的最小单元。

核心内容：
1. 从Dify/Coze到LangGraph的进阶挑战
2. Skill文件如何解决团队能力断层问题
3. 实战案例：半天搭建首个LangGraph Agent

杨芳贤

53AI创始人/腾讯云(TVP)最具价值专家

上周，我的一个同事用了半天时间，从零搭出了他人生中第一个 LangGraph Agent。

他之前写过最复杂的东西，是在 dify 里拖了 20 个节点的工作流。LangGraph？没碰过。Python 代码？能看懂，但从零写一个 Agent 架构？不敢想。

但他确实做到了。不是因为他突然开窍了，而是因为我给了他一个文件。

一个叫 SKILL.md 的文件。

先说痛点：为什么 Dify 和 Coze 不够用了

我们团队最近 Agent 项目突然多了起来。

一开始挺开心的，觉得终于可以大展拳脚。但很快就发现一个要命的问题：大部分同事只会用 Dify 和 Coze 拖工作流。简单的需求没问题——搜索、总结、问答，拖拖拽拽就能搞定。

⠀

但是，当需求变复杂的时候，工作流平台就不行了：

- 需要循环和条件分支？Dify 支持，但稍微复杂一点就变成意大利面条

- 需要人工介入（审核后再继续）？工作流平台做得很别扭

- 需要状态管理（记住之前发生了什么，失败了能从断点恢复）？这基本超纲了

- 需要多个 Agent 协同？Coze 一个 Bot 可以，三个 Bot 联动？算了吧

说白了，Dify/Coze 是"拖拽式的快捷方式"，非常适合验证想法和做简单自动化；但当你的 Agent 需要处理异常、需要容错、需要可靠地在生产环境跑起来的时候——你必须写代码。

⠀

而 LangGraph 就是干这个的。它把 Agent 的执行逻辑变成一张"图"，用代码精确控制每一步该干什么、出错了怎么办、什么时候该停下来等人拍板。

问题来了：谁来写代码？AICoding 时代了，大家都能做吗？

⠀

更大的问题：能力断层

其实，我们团队还有一个很现实的问题：能力断层。

缺中级。

有少数资深的同学能写代码、能搞架构，但人手不够；

还有一批年轻的新人，学习能力强，但经验不足——他们擅长用 Dify 拖工作流，让他们从零写一个 LangGraph Agent？还不少人不太熟悉 AICoding 工具，这中间差了一大截。

⠀

以前的做法是什么？培训。写文档、开课程、手把手带。但说实话，这套方法太慢了。一个人学会 LangGraph 的架构设计，按正常节奏，至少需要几周的项目实战。我们等不起。

所以我在想：有没有一种方式，能把我脑子里的方法论，不通过"教"，而是通过"工具"的方式，直接传递给团队？

⠀

我的发现：Skill 是最小的能力传递单元

先说结论：我找到了。就是 Skill。

什么意思呢？

以前，我们传递经验的方式是这样的：

我的经验 → 写成文档 → 同事读文档 → 同事理解 → 同事执行

每一步都有损耗。文档写不清楚、理解有偏差、执行时遗漏，最后搞出来的东西和我预期的差了十万八千里。

⠀

现在，用 Skill，流程变成了：

我的经验 → 写成 SKILL.md → AI 读取指令 → AI 引导同事一步步执行

AI 成了我的经验的容器和执行者。 同事不需要"先学会我怎么想"，他只需要跟着 AI 的引导走，AI 会按照我的方法论，一步一步带他做。

这就是 Skill 的本质：不是教人方法论，而是把方法论打包成 AI 能执行的指令。

⠀

三分钟讲清楚：什么是 Skill？

Skill 不是一个 Prompt，也不是一篇教程。它是一个标准化的指令文件，让 AI Coding 工具（我用的是 AntiGravity / Claude Code）每次都按照同样的流程执行。

打个比方：

- Prompt = 你口头跟新员工说"帮我做个 Agent"——他可能做出任何东西

- 教程 = 你写了一份 10 页的文档——他可能看完了但做不出来

- Skill = 你给 AI 一份严格的工作指令——AI 带着他一步步做，每一步都有检查点

⠀

一个完整的 Skill 包含三个东西：

关键点在于：Skill 不是替代人，而是把"老手的直觉"变成新手也能跟着走的流程。

⠀

我的 langgraph-architect Skill 长什么样

这个 Skill 的核心是一套三阶段、六步法——我从多个实战项目里（播客制作 Agent、合同审查 Agent、Q&A 智能体）总结出来的。

从玩具到工业级 Agent，你只差一个 LangGraph

核心理念很简单：先画图想清楚 → 再用假代码验证架构 → 最后才碰 AI。 强制把三件事解耦。

⠀

🗺️ 第一阶段：业务建模（只动脑，不写核心代码）
  步 1：画出可视化蓝图  → 产出：流程图
  步 2：推导数据契约    → 产出：state.py

🏗️ 第二阶段：搭建骨架（看图翻译，不碰大模型）
  步 3：招募假打工人    → 产出：dummy nodes.py
  步 4：铺设传送带      → 产出：graph.py

🚀 第三阶段：闭环与注入灵魂
  步 5：Dry Run 验证    → 产出：测试日志 ✅
  步 6：增量注入血肉    → 产出：生产级 nodes.py

但光有方法论不够。我在把它做成 Skill 的过程中，发现了 8 个实际开发中会踩的坑，如果不提前处理，新手一定会掉进去：

⠀

最致命的三个：

⠀

坑 1：假数据类型没约束。 假节点随手返回一个字符串，但 State 定义的是 `List[Dict]`——类型不匹配的 Bug 被掩盖了，到后面才炸。所以 Skill 里强制要求：假数据必须和 State 定义严格对齐。

坑 2：人工介入节点导致测试静默挂起。 带 `interrupt()` 的节点在 Dry Run 时会直接卡死，不报错也不往下走。新手一脸懵。Skill 里写了解法：测试时必须用 MemorySaver + `Command(resume=...)` 模拟人工输入。

坑 3：只测 Happy Path。 只测"一切顺利"的路径，重试分支和打回分支的代码全没跑过。上线就炸。所以 Skill 强制要求：流程图里每一个菱形分支，都必须有对应的测试用例。

这些东西，如果让新人自己摸索，可能要踩坑两三周。但写进 Skill 里，AI 会在对应步骤自动提醒，新手甚至不知道自己被保护了。

⠀

效果：半天从零到一

我的同事拿到这个 Skill 后，打开 AI Coding 工具，输入了一句话：

`/langgraph-architect 我想做一个 M8 HEV 车型的智能问答 Agent`

AI 就自动按照六步法开始引导了：

1. 先问他 6 个场景问题，帮他想清楚需求

2. 生成流程图，等他确认

3. 自动生成 State 定义、Dummy Nodes、Graph 代码

4. 跑 Dry Run，验证架构

5. 一个一个替换真实逻辑

半天时间，他完成了 Agent 的骨架搭建和 Dry Run 验证。虽然真实的 LLM 逻辑还需要后续迭代，但架构已经 100% 稳固了。

他跟我说了一句话，让我印象特别深：

"我感觉不是在学 LangGraph，而是有个老师傅一直在旁边带着我做。"

对，这就是 Skill 的意义。不是教你理论，而是让你在做的过程中，被一套成熟的方法论保护着。

⠀

你也可以做：从任何个人技能到 Skill 的 4 步

这套方法不只适用于 LangGraph。你团队里任何"只有某个人能干"的事，都可以用同样的方式做成 Skill。

第 1 步：先在实战中做 3 次以上。 你不能把没验证过的东西打包成 Skill。至少在 3 个不同的项目里实践过，才能看清楚哪些是通用规律，哪些是特殊情况。

第 2 步：抽象出步骤和检查点。 你每次做这件事，都经过了哪些步骤？哪些地方容易出错？哪些地方必须停下来等人确认？把这些写下来。

第 3 步：写成 SKILL.md。 包含：

- 触发条件（什么时候该激活这个 Skill）

- 每一步的 AI 行为（必须做什么、禁止做什么）

- 强制确认点（哪些步骤必须等人点头）

- 代码模板（如果有的话）

第 4 步：让新手试跑，然后迭代。 Skill 不是一次性的。每次有人用，如果踩了新坑，就更新 SKILL.md。你的 Skill 会越来越强。

⠀

最后说一句

过去，我们传递技能的方式是"教"——开培训、写文档、手把手带。这很好，但太慢了。

⠀

现在，有了 AI Coding 工具，我们有了一种新的方式：把技能打包成 Skill，让 AI 带着新手用你的方式做事。

你团队里一定也有那种"只有你能干"的事。

把它做成 Skill 试试——不是让 AI 替你干，而是让 AI 帮你的团队，用你的方式干。