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