1. 從“superpowers”說起這套 agentic skills framework 到底在解決什么問題第一次看到 “superpowers” 這個詞很多人會以為是某個超級英雄主題的插件或者游戲模組。但如果你最近在折騰 Claude Code、Codex CLI 這類終端里的 AI 編程助手大概率已經(jīng)在社區(qū)里刷到過它。簡單說superpowers 是一套面向 AI 編程代理的 agentic skills framework同時也是一套圍繞它生長出來的 software development methodology。它要解決的核心痛點非常具體當你把 Claude Code 或 Codex CLI 當成日常開發(fā)搭檔之后會發(fā)現(xiàn)模型本身很聰明但每次都要重新解釋項目規(guī)范、重新教它怎么跑測試、怎么組織提交信息重復勞動特別多。superpowers 的思路就是把這些“重復教”的東西沉淀成可復用的技能包skills讓代理在需要的時候自動加載對應的能力。你可以把它理解成給 AI 編程助手裝了一套“職業(yè)培訓教材加工具箱”寫前端的時候它知道你的組件規(guī)范寫后端的時候它知道你的接口約定做代碼審查的時候它知道你的檢查清單。這套框架不是某個單一工具而是一種組織方式配合 Claude Code、Codex CLI 這類支持技能擴展的代理運行時使用。適合誰來參考三類人最值得花時間一是已經(jīng)把 Claude Code 或 Codex CLI 當主力開發(fā)工具、但覺得“還不夠順手”的開發(fā)者二是團隊里負責制定工程規(guī)范、想讓 AI 代理遵守統(tǒng)一標準的技術負責人三是剛接觸 agentic 編程、想搞清楚“技能框架”到底怎么落地的新手。這篇文章會從設計思路、核心機制、實操配置到常見坑完整拆一遍盡量讓你看完就能動手搭一套自己的 superpowers 工作流。2. 核心設計思路拆解為什么是“技能”而不是“提示詞”2.1 提示詞工程的瓶頸在哪里大部分人用 Claude Code 的起點都是一段長長的系統(tǒng)提示詞或者 CLAUDE.md 文件把項目背景、編碼規(guī)范、常用命令一股腦塞進去。剛開始挺好用但項目一復雜就出問題。提示詞是“全局常駐”的不管你現(xiàn)在是在寫數(shù)據(jù)庫遷移還是在調(diào) CSS模型每次都要讀完所有內(nèi)容token 消耗大不說還容易互相干擾——寫前端的時候被后端的規(guī)范帶偏做重構的時候又被測試規(guī)范分散注意力。更麻煩的是維護。提示詞是一整塊文本改一處要小心翼翼團隊多人協(xié)作時沖突不斷。我試過在一個中型項目里維護一份 800 行的 CLAUDE.md兩個月后已經(jīng)沒人敢動它了因為誰也不知道刪掉哪段會影響什么。這就是提示詞工程的天花板它是線性的、耦合的、難以組合的。2.2 技能框架的三個關鍵設計superpowers 這類 agentic skills framework 的破局點在于把“能力”拆成獨立單元。每個 skill 是一個自包含的目錄里面有說明文檔、觸發(fā)條件、具體步驟甚至附帶腳本和模板。代理在運行時根據(jù)當前任務動態(tài)決定加載哪些 skill。這個設計有三個關鍵好處。第一是按需加載。你在改 React 組件時代理只加載前端相關的 skill你在寫 SQL 時只加載數(shù)據(jù)庫 skill。上下文窗口被用在刀刃上模型注意力更集中輸出質(zhì)量自然更穩(wěn)。第二是可組合。一個“提交代碼”的 skill 可以調(diào)用“運行測試”和“生成提交信息”兩個子 skill像搭積木一樣拼出復雜流程。第三是可版本化。每個 skill 是獨立文件可以進 Git可以 code review可以單獨迭代團隊協(xié)作時沖突面小得多。提示不要把 skill 理解成“更長的提示詞”。它的本質(zhì)是“帶觸發(fā)條件的、可獨立維護的能力模塊”觸發(fā)條件的設計比內(nèi)容本身更重要。2.3 和 Claude Code、Codex CLI 的關系Claude Code 和 Codex CLI 都提供了讓代理讀取本地文件、執(zhí)行終端命令、調(diào)用工具的能力這是技能框架能跑起來的基礎。superpowers 本身更像是一套約定和模板集合告訴你 skill 應該長什么樣、放在哪里、怎么被引用。Claude Code 通過項目根目錄的配置和特定目錄結(jié)構來發(fā)現(xiàn) skillCodex CLI 則有自己的命令體系來管理這些擴展。兩者機制不同但理念一致讓代理在正確的時機拿到正確的知識。這里要澄清一個常見誤解superpowers 不是必須依賴某個特定模型。它是一套方法論加文件組織方式理論上任何支持工具調(diào)用和文件讀取的代理運行時都能用。只不過目前 Claude Code 和 Codex CLI 的生態(tài)最成熟社區(qū)分享的 skill 也最多所以大家默認在這兩個平臺上實踐。3. 核心細節(jié)解析一個 skill 到底由什么組成3.1 目錄結(jié)構與文件約定一個規(guī)范的 skill 通常是一個獨立目錄放在項目約定的 skills 路徑下。目錄名就是 skill 的標識建議用短橫線連接的英文短語比如run-tests、commit-convention、api-design-review。目錄內(nèi)部一般包含這幾個文件主說明文件通常是 markdown描述這個 skill 解決什么問題、什么時候觸發(fā)、具體怎么做可選的腳本文件把重復的命令固化下來可選的模板文件比如提交信息模板、PR 描述模板。主說明文件的結(jié)構很關鍵。開頭要有一段簡短的“觸發(fā)描述”用自然語言寫清楚“當用戶在做 X 的時候使用本 skill”。這段描述會被代理用來判斷是否加載。中間是具體的操作步驟要寫成可執(zhí)行的指令而不是泛泛而談。結(jié)尾可以放注意事項和邊界情況。我見過太多 skill 寫成了“科普文章”模型讀完不知道下一步該干嘛這就是失敗的 skill。3.2 觸發(fā)條件的設計技巧觸發(fā)條件是整個框架里最容易被低估的部分。寫得太寬代理動不動就加載浪費上下文寫得太窄該用的時候用不上。我的經(jīng)驗是圍繞“動作 對象”來寫比如“當需要為新功能編寫單元測試時”“當準備提交代碼到主分支時”。避免用“當涉及測試時”這種模糊表述。還有一個技巧是給觸發(fā)條件加上“反例”。比如在run-tests的說明里寫一句“如果用戶只是詢問測試覆蓋率數(shù)字不需要加載本 skill”。這種負向約束能顯著減少誤觸發(fā)。實測下來加了反例之后誤加載率能降一半以上。3.3 參數(shù)化與復用好的 skill 不是寫死的而是帶參數(shù)的。比如一個“生成 API 端點”的 skill不應該把具體的資源名、字段名寫死而是用占位符表示讓代理在加載時根據(jù)當前任務填充。這樣同一個 skill 能服務幾十個不同的端點復用率極高。參數(shù)化的另一個層面是環(huán)境適配。同一個“運行測試”的 skill在不同項目里命令可能不一樣有的用npm test有的用pytest有的用go test。解決辦法是在 skill 里讀取項目配置文件或者讓 skill 引用一個項目級的變量文件。這樣 skill 本身保持通用項目差異通過配置注入。4. 實操過程從零搭一套可用的 superpowers 工作流4.1 環(huán)境準備與工具安裝先把基礎環(huán)境搭好。Claude Code 的安裝方式根據(jù)系統(tǒng)不同有差異Mac 和 Ubuntu 上通常通過包管理器或官方提供的安裝腳本完成Windows 用戶要注意 64 位兼容性問題部分舊版本會提示與系統(tǒng)不兼容建議直接用較新的安裝包。安裝完成后第一次運行需要處理賬號相關配置社區(qū)里常討論“注冊賬號和不注冊有什么區(qū)別”簡單說注冊后能同步配置和使用云端能力不注冊也能跑本地流程但功能受限。Codex CLI 的安裝類似裝完之后要熟悉幾個高頻命令/compact用來壓縮上下文長會話里特別有用/model切換模型/resume恢復之前的會話。這幾個命令在搭 skill 工作流時會反復用到。如果你在 VS Code 里工作可以裝 Claude Code 的官方插件配置項里能指定 skill 目錄、模型來源等。想接本地模型的話可以通過 LM Studio 暴露本地接口再讓 Claude Code 指向這個接口這樣敏感項目不用出本地。注意安裝過程中如果遇到“組織已禁用訂閱訪問”之類的提示通常是賬號權限或區(qū)域配置問題先檢查賬號狀態(tài)不要急著重裝。4.2 建立 skills 目錄與第一個 skill在項目根目錄下建一個skills文件夾這是社區(qū)最常見的約定。然后在里面建第一個 skill建議從最簡單的開始比如commit-message。目錄結(jié)構如下skills/ commit-message/ SKILL.md template.mdSKILL.md里寫觸發(fā)條件和步驟template.md放提交信息模板。內(nèi)容大致這樣組織觸發(fā)描述寫“當用戶準備提交代碼、需要生成提交信息時使用本 skill”步驟里寫清楚先運行git diff --staged查看暫存區(qū)改動再根據(jù)改動類型套用模板生成信息最后用git commit提交。模板文件里定義好 feat、fix、docs、refactor 等類型的格式。寫完第一個 skill 后在 Claude Code 里測試一下。故意說“幫我提交這些改動”看代理是否自動加載了這個 skill。如果沒有檢查觸發(fā)描述是不是太窄或者 skill 目錄路徑有沒有配對。4.3 逐步擴展技能庫第一個跑通之后按同樣的模式擴展。我建議按開發(fā)流程的順序來建需求分析、接口設計、編碼、測試、審查、提交、部署。每個環(huán)節(jié)建一到兩個 skill。比如測試環(huán)節(jié)建write-unit-test和run-tests審查環(huán)節(jié)建code-review-checklist。擴展時要注意 skill 之間的依賴關系。commit-message可能依賴run-tests先跑通這種依賴要在說明里寫清楚或者干脆做成組合 skill。但不要過度嵌套三層以上就會讓代理困惑。我的經(jīng)驗是保持 skill 扁平組合邏輯交給代理自己判斷而不是硬編碼在 skill 里。4.4 參數(shù)計算與配置示例舉個具體的參數(shù)化例子。假設你要建一個“生成數(shù)據(jù)庫遷移”的 skill涉及表名、字段、索引等參數(shù)。不要把這些寫死而是在 skill 里定義變量占位## 步驟 1. 確認遷移目標表名{{table_name}} 2. 列出需要新增的字段{{fields}} 3. 判斷是否需要索引{{index_decision}} 4. 生成遷移文件命名格式為 {{timestamp}}_{{table_name}}_migration代理在加載時會根據(jù)當前對話填充這些變量。這樣同一個 skill 能處理所有表的遷移維護成本極低。實測下來一個參數(shù)化良好的 skill 能覆蓋 80% 以上的同類任務剩下 20% 的特殊情況再單獨處理。5. 常見問題與排查技巧實錄5.1 skill 不觸發(fā)怎么辦這是最高頻的問題。排查順序是這樣的先看觸發(fā)描述是不是太抽象改成具體的“動作 對象”再看 skill 目錄是否在代理掃描的路徑內(nèi)不同工具的默認路徑不一樣Claude Code 和 Codex CLI 各有約定最后看是否有其他 skill 搶先觸發(fā)多個 skill 觸發(fā)條件重疊時會互相壓制。我踩過的坑是觸發(fā)描述里用了太多同義詞導致代理判斷混亂精簡之后就好了。5.2 上下文被 skill 撐爆skill 加載多了上下文窗口很快就不夠用。解決辦法有三個一是給 skill 說明文件瘦身把詳細內(nèi)容拆到附屬文件里主文件只留觸發(fā)條件和步驟概要二是用/compact命令定期壓縮三是給 skill 設置優(yōu)先級低優(yōu)先級的在上下文緊張時自動跳過。實測把主說明文件控制在 200 行以內(nèi)整體表現(xiàn)最穩(wěn)。5.3 多工具協(xié)同的沖突同時用 Claude Code 和 Codex CLI 的時候兩邊的 skill 目錄和配置可能打架。建議給每個工具獨立的 skill 目錄共享的部分用軟鏈接或者同步腳本處理。另外注意命令差異比如刪除 Codex CLI 的某個指令和 Claude Code 的操作方式不同別搞混了。常見問題排查方向解決技巧skill 不觸發(fā)觸發(fā)描述、目錄路徑、優(yōu)先級改成動作加對象檢查掃描路徑上下文溢出skill 體積、加載數(shù)量瘦身主文件用 compact設優(yōu)先級多工具沖突目錄隔離、命令差異獨立目錄軟鏈接共享注意命令區(qū)別參數(shù)填充錯誤占位符格式、變量來源統(tǒng)一占位符語法明確變量注入方式5.4 團隊協(xié)作中的 skill 管理團隊用的時候skill 庫要進 Git走 code review。但要注意別讓 skill 庫變成新的“大泥球”。我的做法是每個 skill 有明確的 owner改動需要 owner 審核。另外定期清理不再使用的 skill我見過一個團隊攢了 60 多個 skill一半沒人維護反而拖慢了代理的判斷速度。季度清理一次保持精簡。6. 進階玩法把 superpowers 和本地模型、第三方接口結(jié)合6.1 接入本地模型的注意事項有些項目對數(shù)據(jù)敏感不想把代碼發(fā)到云端。這時候可以用 LM Studio 在本地跑模型然后讓 Claude Code 指向本地接口。配置的關鍵是接口地址和模型名稱要對上另外本地模型的工具調(diào)用能力通常弱一些skill 的步驟要寫得更明確減少代理的自由發(fā)揮空間。實測本地模型跑 skill 工作流成功率比云端低一些但通過細化步驟能補回來不少。6.2 第三方接口的接入技巧社區(qū)里也有人用第三方接口接入 DeepSeek、Qwen、GLM 等模型通過 cc switch 這類工具切換。這種玩法的好處是成本可控、模型選擇靈活。要注意的是不同模型的指令遵循能力差異較大同一個 skill 在 A 模型上跑得好換到 B 模型可能就翻車。建議給每個模型單獨調(diào)一版 skill或者至少測試一遍再上生產(chǎn)。6.3 和飛書等協(xié)作工具的連接有團隊把 Claude Code 接到飛書里讓代理在群里響應開發(fā)請求。這種場景下 skill 的設計要更偏向“對話式”觸發(fā)條件要能識別群聊里的自然語言。我的經(jīng)驗是給這類場景單獨建一套 skill不要和本地開發(fā)用的混在一起因為交互模式完全不同。7. 我個人的一些實操體會搭這套東西最深的體會是skill 的質(zhì)量比數(shù)量重要得多。我一開始貪多建了三十多個 skill結(jié)果代理判斷加載哪個都要花不少時間反而變慢。后來砍到十二個每個都打磨得很細整體效率明顯提升。另一個體會是觸發(fā)描述值得反復改我有個 skill 改了七版觸發(fā)描述才穩(wěn)定下來前面六版要么不觸發(fā)要么亂觸發(fā)。還有一點別指望 skill 能解決所有問題。它擅長的是“把重復的、有固定套路的任務固化下來”對于需要創(chuàng)造性判斷的任務還是得靠人。把 skill 用在刀刃上比如代碼規(guī)范檢查、提交信息生成、測試腳手架搭建這些高頻重復場景收益最大。至于復雜的架構設計讓代理參與討論就好別硬塞進 skill 里。最后分享一個小技巧給每個 skill 加一個“最后更新日期”和“適用版本”字段。代理運行時如果發(fā)現(xiàn) skill 太久沒更新或者和當前項目版本不匹配可以主動提醒你。這個小小的元數(shù)據(jù)字段幫我避免了好幾次用過期 skill 導致的翻車。