superpowers 這個名字第一次看到時我以為是某個效率玄學工具直到在 Codex 工作流里真正連續(xù)用了一周才確認它并不是包裝出來的概念而是真的能把 AI 編程 Agent 的產(chǎn)出質量往前推一截的東西。它不是腳手架也不是一鍵生成項目的代碼生成器而是一套面向 AI 編程 Agent 的技能包。技能兩個字不是比喻是字面意義上的文件一個文件夾、一個 SKILL.md、若干輔助腳本和示例組合成一件可復用的行為協(xié)議。如果你已經(jīng)在用 Codex CLI、Claude Code或者任何兼容 skills 目錄的 AI 編程工具這篇就是給你寫的。我會把 superpowers 的使用指南、安裝過程、核心原理、Java 項目接入經(jīng)驗一次講完也會把我在真實開發(fā)里踩過的坑直接攤開。后面你搜superpowers 安裝superpowers 使用教程codex superpowers之類關鍵詞時看到的基本就是這套東西落地后的實際狀態(tài)。1. 先搞清楚superpowers 是給誰用的技能包1.1 它的核心單元是 SKILL.md很多人在第一次接觸 superpowers 時會有一個錯覺覺得它是一個大而全的框架裝完以后 Agent 就自動變強。這種理解基本是反的。superpowers 放在你項目里的是一堆技能目錄每個技能目錄里最關鍵的文件是 SKILL.md里面用 Markdown 寫清楚了這件事的觸發(fā)條件、執(zhí)行步驟、驗收清單和禁止事項。用我自己熟悉的目錄結構舉例skills/ plan/ SKILL.md examples/ review/ SKILL.md scripts/ test/ SKILL.md refactor/ SKILL.mdAgent 在執(zhí)行任務時會先看用戶是否提到某個技能名或技能觸發(fā)詞。一旦命中它就會把對應目錄里的 SKILL.md 作為一段強上下文讀進當前會話然后按照里面寫的步驟走。表面上看技能像是命令本質上它是一種動態(tài)提示詞注入你平時寫在對話里重復叮囑的內(nèi)容被固化成了文件。這也是為什么 superpowers 能解決同樣的要求每次都要重新說一遍的痛點。比如代碼審查這件事如果沒有技能文件Agent 可能看到代碼就直接改改完你才發(fā)現(xiàn)它沒有看邊界條件。有了 review 技能它會先掃描文件、列出風險點、輸出審查結論最后才動手修改而且這一步是寫在技能流程里的不是靠你碰運氣。1.2 為什么只靠提示詞撐不住大部分團隊讓 AI 編程 Agent 干活的方式是這樣的在項目根目錄放一個 AGENTS.md把編碼規(guī)范、常用命令、禁用事項寫在里面然后就開始對話。這種做法不是沒用但它有個天然上限一份全局說明只能描述大部分場景很難把不同任務的工作流拆細。你今天讓 Agent 做新功能明天讓它修 bug后天讓它做重構任務類型完全不同。如果用一份 AGENTS.md 強行覆蓋所有情況要么寫得特別長導致 Agent 抓不住重點要么寫得特別短導致每次執(zhí)行質量全看運氣。superpowers 的應對思路很直白把任務類型的差異拆成獨立技能用目錄結構做隔離通過觸發(fā)詞做路由。這有點像一個團隊不能只靠一本員工手冊運轉還得有評審流程、測試流程、發(fā)布流程。每套流程單獨成文需要時再拿出來而不是讓所有人把全書背下來。superpowers 就是把評審流程、測試流程、重構流程單獨成文Agent 按需加載。1.3 誰適合用誰不適合我用了幾天之后對適用人群有了一個比較清楚的判斷。它適合兩類人一類是已經(jīng)在用 Codex CLI 這類工具、但對輸出質量不太滿意的開發(fā)者另一類是帶小團隊、想讓 AI 成員按統(tǒng)一工作流干活的技術負責人。因為它本質上是把流程寫成文件組里每個人都能看到、都能改也都能審。反過來如果你是剛接觸 AI 編程的純新手連項目里生成了什么文件都還沒搞清楚我建議先別急著上 superpowers。它假設你已經(jīng)對基礎命令和項目結構有基本概念它的價值是約束和增強而不是替代基礎能力。把基礎對話磨明白再回來你會更容易體會到它好在哪。2. 從零開始安裝 superpowers 的 15 分鐘實操2.1 裝之前要準備什么安裝前你先確認兩件事第一你已經(jīng)有一個能正常發(fā)起 AI 編程會話的工具常見的就是 Codex CLI開源生態(tài)里也有不少支持 skills 目錄的同類產(chǎn)品第二你了解這個工具讀取項目配置和工作目錄的基本方式至少要知道它是在哪個目錄下啟動的。前置工具這一塊要看具體倉庫的要求不同版本差別比較大。我傾向于不在博客里寫死某個運行時版本因為項目更新得很快寫死了隔兩個月就誤導別人。你只需要在安裝后跑一次冒煙測試能觸發(fā)第一個技能就說明當前環(huán)境是兼容的。另外想提醒一點如果你的項目代碼比較多最好在本地新建一個臨時目錄來練習安裝不要一上來就把技能包直接塞進生產(chǎn)項目。我第一次就是這么干的結果技能路徑跟項目配置糾纏在一起排查了半天才弄清楚是加載順序的問題。2.2 標準安裝流程克隆、放目錄、指路徑第一步是把技能源碼拿到本地。打開終端創(chuàng)建一個專門放技能的目錄然后克隆倉庫。我習慣放在用戶目錄下而不是項目目錄里這樣多個項目可以共用而不會因為某個項目刪了影響全局。mkdir -p ~/.superpowers cd ~/.superpowers git clone superpowers倉庫地址倉庫地址以項目主頁為準我不在這里貼寫死的鏈接避免傳著傳著就變成非官方鏡像。你自己搜索superpowers skills agent就能找到官方入口克隆后先看一眼 README再動手。第二步是讓 Agent 能看到這些技能。不同工具提供的方式不一樣最常見的兩種是在項目根目錄的配置里聲明 skills 根路徑在會話開場時主動說明skills 目錄在哪。我自己的經(jīng)驗是能寫進配置就寫進配置不要靠每次手輸。因為你會忘。把路徑寫死在項目配置中等于每次會話自動加載省心很多。# 以常見配置示例表示具體字段名以你使用的工具為準 skills_path ~/.superpowers/superpowers/skills2.3 安裝后必做的冒煙測試裝完別急著丟大任務進去。先做一次兩分鐘冒煙測試確認技能真的被加載了。具體做法是隨便選一個你知道肯定存在的技能例如review然后給 Agent 發(fā)一條簡短指令使用 review 技能對當前項目 README 做一次結構審查。正常情況下Agent 會回一段結構化的審查結論而不是上來就大改文件。如果它完全無視技能名直接輸出一段通用回答那說明技能沒有被正確加載。這個時候去檢查兩件事路徑有沒有寫對以及當前工作目錄是不是 Agent 實際讀取的那個目錄。我見過最多的坑是路徑看起來沒問題、實際差了層級。你寫的是相對路徑但 Agent 從另一個目錄啟動技能就撲空了。解決方法是統(tǒng)一用絕對路徑或者寫一個啟動腳本把工作目錄固定住。2.4 版本迭代帶來的安裝差異superpowers 這個項目的迭代速度不算慢不同版本之間可能會有目錄結構變動。比如早期版本把技能集中放在根目錄后面對應不同 Agent 體系拆分成了多個子目錄。遇到這種變化不用慌還是以 README 為準。我的建議是把 README 當作安裝指南的第一手資料而不是只看網(wǎng)上的教程。網(wǎng)上教程適合幫你建立概念真正裝的時候照著官方目錄結構來少踩很多坑。你在搜索時看到的所有superpowers 安裝文章本質上都是某次迭代的切片不保證現(xiàn)在仍然適用。3. 核心技能拆解這些超能力到底給了 Agent 什么3.1 先從一張常用技能表說起不同版本的 superpowers 會自帶或社區(qū)提供大量技能你完全不用全裝。下面這張表是我實際使用頻率最高的幾個技能以及它們適用的場景技能名觸發(fā)場景核心作用plan新需求、不確定時先拆解任務、列出約束、輸出執(zhí)行計劃review已完成代碼、合并前掃描風險點、檢查邊界輸出審查結論test需要驗證行為時閱讀現(xiàn)有測試、規(guī)劃用例、執(zhí)行測試命令refactor感覺代碼混亂時先分析依賴和影響范圍再分步重構root-causebug 反復出現(xiàn)時不急著修復先定位根本原因每個技能目錄里都有具體的步驟說明內(nèi)容比我這里列的自然要細得多。重點不在于你記住這些名字而在于理解它們的共性所有技能都會在動手之前增加一個分析環(huán)節(jié)。3.2 為什么用 Markdown 而不是 JSON 配置我第一次打開技能文件時愣了一下這項目居然用 Markdown 描述行為協(xié)議而不是用 JSON 或者 YAML。后來想明白了這是有意為之。Agent 本身就是用自然語言訓練的Markdown 對它來說是一種非常自然的指令載體幾乎不需要額外解析。用 JSON 寫規(guī)則優(yōu)點是機器可讀但缺點是你得維護一套 schema聲明條件、步驟、例外情況這套東西寫出來很像編程。用 Markdown 寫規(guī)則優(yōu)點是不需要編譯不需要復雜格式校驗誰打開都能改。你甚至可以讓 Agent 自己根據(jù)新經(jīng)驗更新技能文件。這就像一個團隊的流程手冊用 Word 寫還是用純文本寫純文本顯然更適合文檔的持續(xù)演化。superpowers 選 Markdown本質上是把給機器看的格式降級成給人寫的文本換取更高的可維護性。3.3 動手寫一個最小技能示例與其只講概念不如直接給你看一個我能跑通的最小技能文件。假設你經(jīng)常需要 Agent 做空指針風險審查你可以自己建一個技能--- name: null-check description: 當用戶要求檢查空指針風險時使用 --- ## 執(zhí)行步驟 1. 先掃描目標文件的方法簽名列出所有外部輸入。 2. 標記可能為 null 的變量、參數(shù)、返回值。 3. 輸出風險清單逐個說明觸發(fā)條件和影響。 4. 在你的風險清單得到用戶確認前不要修改任何代碼。 ## 驗收標準 - 每個風險點都有代碼位置 - 每個風險點都有觸發(fā)前提 - 沒有跳過聲明文件只檢查業(yè)務代碼的情況這個技能很簡單但在真實會話里非常有用。你把文件放到技能目錄后Agent 一看到空指針風險這個描述就會加載它。你會發(fā)現(xiàn)它不再直接改代碼而是先輸出清單你再決定哪些要修。這個模式的威力在于它把沉默的代碼改動變成了透明的決策過程。3.4 多個技能之間怎么串起來superpowers 的進階用法不是單個技能單打獨斗而是讓技能之間形成流水線。比如 Agent 接到一個新功能需求時可以先加載 plan 技能拆分任務拆完以后用 review 技能審查當前代碼基礎再用 test 技能確認預期行為最后才是寫實現(xiàn)代碼。實際操作中你不需要手動切換Agent 會根據(jù)上下文自動連續(xù)調用多個技能前提是技能描述寫得足夠清晰。我見過比較麻煩的情況是技能描述寫得太寬泛Agent 一個任務里加載了七八個技能上下文被塞滿反而輸出了一些無關內(nèi)容。后來我把技能描述改成僅在……時使用情況好了很多。做技能配置時觸發(fā)條件越收窄路由越準確。4. 在 Java 項目里用 superpowers 的實操記錄4.1 Java 項目為什么更吃這一套Java 項目和那種幾十行的腳本項目不太一樣它的結構性更強從包名、注解、依賴管理到測試框架都有既定慣例。AI 編程 Agent 在 Java 項目里的最大問題不是不會寫代碼而是經(jīng)常忽略項目約束寫出了風格完全不一致、甚至編譯不過的東西。superpowers 對這種場景的約束價值特別大。以 Spring Boot 項目為例一個處理訂單的 Service 類Agent 如果直接上手改很容易忽略事務邊界、忽略 null 校驗、忽略已有測試。但如果你讓它先調用 review 技能它會先分析出方法簽名里的空值風險再決定要不要動。我在一個多模塊 Maven 項目里做過一次測試讓 Agent 給訂單模塊新增分頁查詢接口同時要求它使用 review 技能先排查當前實現(xiàn)。它第一輪沒有直接生成代碼而是先輸出了一份風險清單里面準確提到了分頁參數(shù)可能為 null、當前沒有統(tǒng)一異常處理、以及查詢超時時間沒配置。我對這種輸出并不意外因為技能文件里就寫了這些檢查步驟。但它確實比以往的直接生成干凈得多。4.2 實操過程從需求到技能調用的完整鏈路我記錄了一次實際會話過程大致是這樣的第一步我給 Agent 下了一段指令使用 plan 技能拆分這個需求再調用 review 技能檢查訂單模塊現(xiàn)有代碼我確認后你才寫實現(xiàn)。注意這一步的要點是提前說清楚技能順序和確認節(jié)點。第二步Agent 先加載 plan 技能輸出了一個四步計劃梳理現(xiàn)有接口、明確分頁參數(shù)、檢查事務邊界、補充測試。計劃之后它又調用 review 技能把目標文件里所有可能引發(fā)空指針的地方列成了表格。第三步我看了表格確認了兩項修改建議才告訴它可以動手。最終 Agent 生成的改動和計劃完全一致沒有超出我批準的范圍。整個過程像帶了一個非常謹慎的初級開發(fā)而不是一個想到哪寫到哪的自動生成器。這就是技能驅動的意義每一步都有產(chǎn)出物每一段產(chǎn)出物都能被人類審查。4.3 Maven 多模塊項目最容易踩的坑Java 項目里最常見的報錯不是代碼問題而是命令執(zhí)行位置不對。Maven 多模塊項目里Agent 很容易在根目錄直接跑mvn test結果某個子模塊起不來或者跑了一堆無關模塊的測試。解決思路不是讓 Agent 猜而是在技能文件里寫清楚項目結構和命令模板。以 Maven 為例你可以讓技能在執(zhí)行測試前先讀取根pom.xml的modules列表然后使用-pl和-am參數(shù)指定模塊范圍。mvn -pl order-service -am test這個命令的意思是只構建 order-service 模塊同時構建它所依賴的其他模塊。如果你發(fā)現(xiàn) Agent 在 Java 項目里反復跑錯命令先別急著換工具先檢查是不是技能文件里缺少了識別模塊結構這一步驟。這是我在實戰(zhàn)里最有體感的一條經(jīng)驗。4.4 在WorkBuddy 怎么用 superpowers這類問題上的統(tǒng)一回應很多人在搜索時用worbuddy 怎么用 superpowers其實問的是其他桌面端 AI 編程工具能不能接入技能包。統(tǒng)一答案是能但入口位置不一樣。Codex CLI 這類純命令行工具靠配置文件和啟動參數(shù)桌面端工具多半靠設置面板里的技能根目錄或指令文件路徑選項。你只需要抓住一個核心原則Agent 必須從某個路徑讀到技能文件。至于這個路徑是寫在配置里、填在對話框里、還是設定在面板上都是同一件事的不同實現(xiàn)。如果某個工具界面里找不到技能配置入口你就手動把技能目錄放進項目根目錄然后在會話開頭明確寫一句技能目錄在 ./skills需要時請加載對應技能。這招在絕大多數(shù) GUI 工具里都有效。5. 常見問題與排查技巧實錄5.1 一張拿來即用的問題速查表下面這些是我和群里朋友實戰(zhàn)中遇到過的典型問題整理成速查表癥狀最常見原因解決動作Agent 完全不理會技能名技能路徑?jīng)]被讀取改用絕對路徑檢查啟動目錄技能加載了但執(zhí)行到一半中斷技能步驟太長上下文被占滿拆小技能一個技能只做一件事輸出內(nèi)容天馬行空技能里只有步驟沒有禁止項寫在確認前不要修改代碼這類硬約束Maven 多模塊命令失敗在錯誤目錄執(zhí)行命令在技能里寫死-pl和-am參數(shù)多個技能互相干擾技能描述觸發(fā)條件太寬泛收窄 description限定具體場景這五個問題覆蓋了我見到的大部分使用事故。你會發(fā)現(xiàn)大多數(shù)根因不是 Agent 笨而是技能文件的設計不夠明確。5.2 實操排查法用三分法定位問題當技能沒按預期生效時我有一套固定的排查思路把它叫三分法先分離變量、再定位環(huán)節(jié)、最后重放最小用例。分離變量指的是你一次只改一個東西不要同時改技能內(nèi)容和 Agent 配置。很多人一著急就把好幾個地方都改了結果問題看起來消失了但不知道是誰修好的。定位環(huán)節(jié)指的是判斷問題是出在加載、讀取還是執(zhí)行加載環(huán)節(jié)看技能目錄結構是否正確讀取環(huán)節(jié)看技能描述是否觸發(fā)執(zhí)行環(huán)節(jié)看 SKILL.md 里的步驟是否矛盾。重放最小用例是我最常用的收尾驗證。我建一個空目錄只放一個簡單技能和一份測試代碼跑一次完整流程。如果最小用例能跑通再逐步加入項目內(nèi)容很快就能定位到是項目里什么東西把 Agent 弄暈了。這套辦法跟查網(wǎng)絡問題差不多都是從最小單元開始復現(xiàn)。5.3 一條反直覺的避坑建議有一個建議看起來反直覺但很有用不要一次性導入太多技能。技能不是越多越好每個技能在加載時都會占用上下文窗口技能數(shù)量一旦上去Agent 在每次任務里都可能自我診斷出多個匹配項反而把該干的事擠掉了。我實驗過 20 個技能和 5 個核心技能的差別。后者在 Java 項目里的表現(xiàn)明顯更集中、更可控。你完全可以保留整個技能庫但只在項目配置里啟用當前項目真正用得上的那幾個。這樣既保留了擴展性又不會把 Agent 變成什么都懂、什么都不精的狀態(tài)。5.4 日志是最好的老師如果你用的工具支持輸出調試日志或會話記錄遇到問題時請第一時間翻日志。日志能看到 Agent 到底是加載了技能還是沒加載是加載失敗還是讀取不到文件這比讓它自己解釋原因可靠得多。我遇到過一次奇怪問題技能文件在路徑也對但 Agent 就是不觸發(fā)。翻日志才發(fā)現(xiàn)它讀取的是項目里另一個同名目錄根本不是我以為的那個路徑。這種問題在文件系統(tǒng)層級復雜時特別容易發(fā)生。別相信你在文件管理器里看到的路徑要讓 Agent 自己說出它讀取的路徑或者直接從日志里找證據(jù)。6. 幾個真正改變我使用習慣的體會6.1 先寫驗收標準再談技能我把 superpowers 用順手之后回頭總結出一條判斷標準技能文件前面幾行可以是做什么但真正起約束作用的是最后的驗收標準。沒有驗收標準的技能Agent 很容易出現(xiàn)一種情況——流程走得很完整結果卻完全偏離目標。你在設計技能時要把怎么算做完寫清楚。這不是小事是整個技能是否能落地的關鍵。6.2 Agent 是執(zhí)行流程的人你是定流程的人和它配合幾周后我最大的心態(tài)變化是不再期待 Agent 替我做決策而是把它當成一個嚴格執(zhí)行流程的人。它最大的價值是穩(wěn)定不是創(chuàng)意。你負責把流程定清楚它負責每一步都按流程走。superpowers 恰好提供了一種更舒服的方式讓你把流程寫成文件而不是寫進對話。6.3 最后分享一個小技巧如果你不知道從哪里開始就先拿一個最讓你頭疼的場景寫技能。不要追求全只寫一個能在下一次會話里直接驗證的小技能。我自己的第一個技能就是空指針檢查寫了不到 30 行效果立竿見影。后面每一次碰到新問題就往技能庫里補一條規(guī)則就像是給自己的 AI 同事做持續(xù)培訓。這套模式用久了你會發(fā)現(xiàn)真正沉淀下來的不只是代碼還有你對開發(fā)這件事的理解。