我用 3 個月才感受到Skill 的價值｜一個文件讓初級員工半天寫出生產級 Agent
整理版優先睇
本文介紹如何透過 SKILL.md 文件將資深開發者的經驗轉化為 AI 可執行的指令，讓初級員工能在半天內搭建出複雜的 LangGraph Agent。
- 傳統培訓與文檔傳遞經驗效率低且易出損耗，Skill 模式則讓 AI 成為方法論的容器引導新手執行。
- 針對 Dify/Coze 等拖拽平台在處理複雜邏輯、狀態管理及容錯機制上的不足，LangGraph 提供更精確的代碼控制。
- 一套成熟的 Skill 應包含主控指令、代碼模板及方法論知識庫，將「老手的直覺」標準化為開發流程。
- 透過「業務建模、搭建骨架、閉環注入」三階段六步法，可有效避免開發中常見的類型不匹配與測試陷阱。
內容片段
🗺️ 第一階段：業務建模（只動腦，不寫核心代碼） 步 1：畫出可視化藍圖 → 產出：流程圖 步 2：推導數據契約 → 產出：state.py🏗️ 第二階段：搭建骨架（看圖翻譯，不碰大模型） 步 3：招募假打工人 → 產出：dummy nodes.py 步 4：鋪設傳送帶 → 產出：graph.py🚀 第三階段：閉環與注入靈魂 步 5：Dry Run 驗證 → 產出：測試日誌 ✅ 步 6：增量注入血肉 → 產出：生產級 nodes.py為什麼低代碼平台不再夠用？
雖然 Dify 和 Coze 適合快速驗證想法，但面對複雜需求如循環分支、人工介入審核、狀態恢復及多 Agent 協同，拖拽式工具會顯得力不從心。
當 Agent 需要處理異常、容錯並在生產環境穩定運行時，必須回歸代碼層面，利用 LangGraph 將邏輯圖譜化。
Skill：最小的能力傳遞單元
一個完整的 Skill 包含 SKILL.md（操作手冊）、examples（參考範例）及 resources（設計原理），確保 AI 每次都按同樣的高標準執行任務。
LangGraph 建築師的六步法
為了讓新手不踩坑，這套 Skill 強制執行三階段開發流程，將思考與編碼解耦：
第一階段：業務建模（畫流程圖、定義數據契約）；第二階段：搭建骨架（編寫假節點與圖結構）；第三階段：注入靈魂（Dry Run 驗證後替換真實邏輯）。
這種方式能自動防禦常見錯誤，例如假數據類型不符、人工介入導致測試掛起，以及只測試正常路徑而忽略異常分支的問題。
如何將個人技能轉化為 Skill？
要把「只有你能幹的事」變成團隊戰力，可以遵循以下四步：首先在實戰中驗證三次以上以總結規律；其次抽象出關鍵步驟與檢查點；接著撰寫 SKILL.md 定義 AI 行為；最後讓新手試跑並持續迭代優化。
上週，我的一個同事用了半天時間，從零搭出了他人生中第一個 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.md | 主控指令（做什麼、怎麼做、什麼時候暫停等人確認） | 流水線的操作手冊 |
| examples/ | 代碼模板和參考示例 | 師傅做過的樣品 |
| resources/ | 方法論和知識庫 | 背後的設計原理 |
關鍵點在於：Skill 不是替代人，而是把"老手的直覺"變成新手也能跟着走的流程。
⠀
我的 langgraph-architect Skill 長什麼樣
這個 Skill 的核心是一套三階段、六步法——我從多個實戰項目裏（播客製作 Agent、合同審查 Agent、Q&A 智能體）總結出來的。
核心理念很簡單：先畫圖想清楚 → 再用假代碼驗證架構 → 最後才碰 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 幫你的團隊，用你的方式幹。