最近 AI 編程圈里Superpowers 這個詞出現的頻率突然高了起來。如果你在折騰 Codex CLI或者用 Trae Work 中文版寫代碼大概率刷到過“codex cli 安裝 superpowers”“trae work cn 安裝 superpowers skill”這類熱詞。不少朋友以為 Superpowers 是某個新模型或者獨立 IDE其實不對。它更像一組打包好的“技能包Skill Pack”里面裝著系統性的提示詞、任務模板和工作流規則給 AI 編碼代理裝上后能讓它從“你說一句、它寫一段”的助手變成“自己拆任務、自己驗證、自己修 bug”的初級工程師。我花了一周時間在 Codex CLI 和 Trae 里反復裝、反復跑實際做完一個多文件重構和一輪單測修復最直觀的感受是這套東西最值錢的不是讓 AI 寫出更多代碼而是逼著它建立起“先規劃、再執行、后驗證”的可靠工作習慣。這篇文章就圍繞 Superpowers 的安裝和使用把我踩過的坑和驗證過的步驟完整寫出來。1. Superpowers 到底是什么一段給 AI 編程助手的“內功心法”1.1 原生編碼代理的三個結構性短板用過 Codex CLI 原版工作流的朋友大概都遇到過類似場景你讓它“給用戶注冊接口加個郵箱驗證”它啪一下把代碼改完直接告訴你“搞定”。但你稍微追問一句“影響面有沒有確認原有測試跑過沒有”它就開始支支吾吾甚至改一個變量名把另外三個文件帶崩。這不是模型能力不夠而是原生的編碼代理缺少三層約束。第一層是上下文管理AI 只能看到有限上下文經常改著改著就把最初的約束忘了。第二層是目標拆解它默認你會把任務講得足夠細可實際項目里一個需求往往牽扯多個文件、多個模塊沒人替它把步驟拆好。第三層是驗證閉環很多原生代理“寫代碼”和“驗證代碼”是割裂的它不會主動去跑測試也不會在測試掛了之后做最小化修復。這三個短板疊加起來就是大家常說的“AI 生成代碼一時爽合并之后火葬場”。Superpowers 這類技能包解決的就是這件事。它不改變底層模型而是通過一組結構化的指令文件在每次任務開始之前先給 AI 注入一套完整的工作協議。簡單說別人是讓 AI 直接答題Superpowers 是要求 AI 先把解題步驟寫出來、每步做完驗算、最后再交卷。這也是為什么很多人裝完之后覺得“AI 變聰明了”——本質不是模型升級而是行為流程被規范了。1.2 Superpowers 的核心模塊拆解、執行、驗證、收尾我實際把技能包解壓開看了一眼目錄結構比想象中清晰。通常最外層是一個主入口文件一般叫SKILL.md里面定義了整體工作流下面再掛幾個子技能目錄比如plan/、test/、debug/、review/。每個子技能都是獨立的 Markdown 指令文件專門負責某一類動作。以我手頭這個版本為例主流程分四步。第一步是規劃Plan它要求 AI 在寫任何代碼之前先輸出一份任務清單每條任務必須標注影響到的文件和執行完要跑哪個測試。第二步是執行Execute要求 AI 嚴格按照清單逐項實現不許跳步。第三步是驗證Verify每個子任務完成后必須運行相應測試不允許用“我覺得沒問題”代替測試結果。第四步是收尾Wrap-up要求 AI 更新相關文檔、檢查是否有臨時調試代碼、提交時寫清楚變更范圍。這套流程聽起來并不復雜但關鍵在于它是“強制”的。技能文件里通常會有類似“除非用戶明確要求否則禁止跳過驗證步驟如果測試失敗禁止直接重寫整個模塊必須先定位最小問題集”這樣的約束。模型在執行時會把這條規則當成最高優先級于是很多原本被忽略的驗證動作就變成了標準動作。1.3 一個最簡單的 SKILL.md 長什么樣為了讓大家對“技能包”有直觀印象我摘一段核心協議片段這基本是所有 Superpowers 變體都會包含的內容# Superpowers Core Protocol ## 1. Plan First Before writing any code, output a task checklist in this exact format: - [ ] Task: 具體任務描述 - Files affected: 涉及文件用絕對或相對路徑 - Tests to run after completion: 測試命令或文件 ## 2. Execute In Order - Complete tasks one by one; do not skip. - Do not batch changes across multiple modules unless the checklist explicitly includes them. ## 3. Verify Each Step - After each task, run the listed tests. - If the test fails, do NOT rewrite the whole file. Follow this loop: 1. Read the failure message. 2. Trace it to the smallest possible root cause. 3. Fix only the necessary lines. 4. Re-run the failing test. - If tests pass, move to the next task. ## 4. Wrap Up - Update README or inline comments if interface changed. - Scan for debug statements, TODO placeholders, and dead code. - Summarize the change in the final response.你別小看這幾段話。把它塞進 AI 的上下文之后效果立竿見影。我自己試過同一臺機器、同一個 Codex CLI沒裝技能前讓它重構一個 utils 模塊它直接丟給我一份改完的代碼裝完技能后它先列出 7 個子任務然后一項項執行每完成一項就自動跑單測中間掛了兩次每次都是通過定位失敗日志里的具體報錯去修而不是無腦回滾。就沖這個變化我認為 Superpowers 的價值被很多人低估了。2. 安裝前的準備Codex CLI 與 Trae 環境差異2.1 Codex CLI安裝、登錄、目錄結構想在 Codex CLI 里安裝 Superpowers先把基礎環境弄干凈。Codex CLI 是 OpenAI 官方的命令行編碼代理最常用的安裝方式就是通過 npm 全局安裝。如果你還沒裝直接執行npm install -g openai/codex裝完驗證版本codex --version我建議至少用支持 skills 機制的較新版本老版本對自定義指令的支持很弱裝了也白裝。登錄認證方面Codex CLI 通常需要配置 API Key 或者走官方登錄流程具體命令如下codex login或者設置環境變量OPENAI_API_KEY。這一步跑通之后你要清楚 Codex CLI 的配置目錄在哪里。默認情況下用戶在~/.codex/下會有一個配置目錄里面可以放全局指令文件、技能目錄、以及歷史記錄。項目級配置則放在當前工作目錄下的AGENTS.md里。這里有個容易踩坑的地方很多人把技能文件直接丟進項目根目錄但在 Codex CLI 的項目目錄里AI 并不是自動掃描所有 Markdown 文件。它通常只會讀取AGENTS.md以及明確通過指令引用的文件。所以后續安裝 Superpowers 時一定要在AGENTS.md里寫明“去哪個路徑讀取技能”否則文件放得再整齊也沒用。2.2 Trae Work 中文版找到工作區和技能目錄Trae 是字節跳動推出的 AI IDE國內用戶大多數用的是 Trae Work 中文版。它內置了比較完整的“技能Skill”機制和 Codex CLI 那種偏命令行的加載方式不太一樣。Trae 的項目級技能目錄是.trae/skills/你可以把它理解為 IDE 自己定義的一個擴展目錄只要把符合規范的文件放進去AI 在對話中就能自動感知到。我在 Trae Work 中文版里試了半天總結下來有幾點關鍵。第一技能目錄必須放在當前項目的根目錄下命名結構是.trae/skills/技能名/SKILL.md。第二Trae 對 SKILL.md 的 frontmatter 有要求需要在文件開頭寫上技能名稱和描述這樣 AI 才會在合適的場景下主動調用。第三如果你用的是“Work 工作區”模式最好把技能目錄放在工作區根目錄而不是某個子模塊目錄里否則 AI 可能掃描不到。需要注意Trae 中文版和英文版的配置目錄并不完全一樣但.trae/skills這個約定是通用的。所以你在網上看到英文教程里的路徑在中文版項目里同樣適用不需要額外改。2.3 兩者的共同邏輯技能包本質是“指令文件”很多人同時用 Codex CLI 和 Trae以為要分別準備兩套不同格式的 Superpowers。其實沒必要。技能包的本質是一組 Markdown 指令文件只要目錄結構和 frontmatter 符合目標工具的約定同一個SKILL.md可以在這兩個工具間復用。區別主要在加載方式。Codex CLI 更多依賴AGENTS.md去“建議”模型讀取某個文件而 Trae 則直接在 IDE 層主動解析.trae/skills目錄把技能描述注入到模型上下文中。理解了這層邏輯你在安裝時就不會被表面的差異帶偏放在 Trae 里的技能文件重點要寫好 frontmatter放在 Codex CLI 里的技能文件重點要寫好AGENTS.md的引用。后面兩章我分別給出完整步驟。3. 實操在 Codex CLI 中安裝 Superpowers 的完整步驟3.1 方式一用 git clone 導入現成技能包目前社區里有很多 Superpowers 的分支版本有的是完整技能集合有的是精簡版。最省事的方式是直接把技能倉庫克隆到本地然后復制到 Codex CLI 的技能目錄。以我自己為例我習慣把技能統一放在~/.codex/skills/下這樣所有項目都能復用。git clone 你關注的技能倉庫地址 superpowers-temp mkdir -p ~/.codex/skills cp -r superpowers-temp/skills/* ~/.codex/skills/這里有個小細節技能倉庫里的skills/目錄可能包含多個子技能文件夾比如plan、test、debug。你要保證復制到~/.codex/skills/后每個子技能文件夾下面都有獨立的SKILL.md。復制完可以檢查一下ls -R ~/.codex/skills如果看到類似~/.codex/skills/debug/SKILL.md這樣的結構說明文件放對了。但如果你只復制了倉庫根目錄下的SKILL.md而漏掉子技能目錄后面 AI 調用子技能時會找不到文件出現“技能未定義”的報錯。3.2 方式二從零手寫 Superpowers 核心技能如果你不想折騰 git clone完全可以通過手動創建目錄和文件把第一節那個核心協議寫進去。這個方法最大的好處是你可以按自己的團隊規范定制內容不受社區版本限制。mkdir -p ~/.codex/skills/superpowers cat ~/.codex/skills/superpowers/SKILL.md EOF --- name: superpowers description: 強制 AI 在編碼任務中執行“規劃-執行-驗證-收尾”的完整工作流。 --- # Superpowers Core Protocol 這里寫前面摘錄的四步協議內容 EOF寫完這個主文件之后我建議再補一個簡單的調試子技能mkdir -p ~/.codex/skills/debug cat ~/.codex/skills/debug/SKILL.md EOF --- name: debug description: 當測試失敗時按最小化修復原則定位問題。 --- # Debug Protocol 1. Read the full failure output. 2. Find the failing function and its input. 3. Trace data flow backward from the failure. 4. Modify only the minimum lines required. 5. Re-run the exact failed test before proceeding. EOF手動創建的好處是你能清楚地知道每一行指令在干什么出了問題也容易排查。壞處是技能少了覆蓋場景有限。對新手我更推薦先用方式一裝社區完整版跑通之后再慢慢改出自己的版本。3.3 在 AGENTS.md 中聲明技能并驗證文件放好之后最關鍵的一步是讓 Codex CLI 知道這些技能的存在。你需要在當前項目根目錄下創建或修改AGENTS.md在里面明確寫出加載指令# Agent Instructions ## Skills - 處理代碼任務前必須讀取 ~/.codex/skills/superpowers/SKILL.md 并嚴格遵循其中的流程。 - 當測試失敗時必須讀取 ~/.codex/skills/debug/SKILL.md 并按照調試協議執行。 ## Constraints - 禁止在未完成任務清單中所有步驟的情況下向用戶報告“完成”。 - 涉及多文件修改時必須先輸出影響文件列表。這里需要提醒的是AGENTS.md和AGENTS.md在不同項目里可能被覆蓋尤其是多個工具同時管理它時。我的習慣是把全局技能聲明放在~/.codex/config.toml或 Codex CLI 的全局指令里把項目相關的約束放在項目AGENTS.md里避免每次克隆新項目都要重新配置。配置完成后啟動 Codex CLI輸入你有哪幾個技能分別是在什么場景下使用如果 AI 能準確說出 superpowers 和 debug 技能的名字并簡單描述用途說明加載成功。如果它只回答“我沒有技能”或者“我不確定”大概率是AGENTS.md路徑寫錯或者技能文件里的 frontmatter 缺失。4. 實操在 Trae 中安裝 Superpowers Skill 的兩種方式4.1 通過項目內.trae/skills目錄安裝在 Trae Work 中文版里安裝我推薦直接用項目內.trae/skills目錄步驟非常直白。先在項目根目錄創建技能目錄mkdir -p .trae/skills/superpowers然后把前面寫好的SKILL.md放進這個文件夾。如果你的 Superpowers 里還有其他子技能比如debug就再建一個mkdir -p .trae/skills/debug放好之后Trae 會自動掃描項目中的.trae/skills目錄。注意這里的 skill 描述非常重要。Trae 會把SKILL.md中 frontmatter 里的name和description傳給模型幫助它判斷“什么時候該調用這個技能”。所以描述要寫得具體一點別寫“這是一個編碼輔助技能”這種廢話而應該寫“當用戶要求實現新功能或重構代碼時先調用此技能進行任務規劃和驗證”。我實際測試過把技能文件放到.trae/skills后不重啟 IDE 也能在較短時間內被識別到。但如果你的 Trae 版本比較老可能需要重啟一下工作區或者重新打開項目讓索引刷新。4.2 通過 Trae CLI / 命令面板導入除了手動建目錄Trae 還支持通過命令面板導入。在 Trae 里按下CmdShiftP或CtrlShiftP輸入“skills”關鍵詞一般能看到“Import Skill”或“安裝技能”之類的選項。選擇該項后會彈出一個文件選擇窗口直接指向你下載好的 Superpowers 文件夾即可。這個方法適合從網上下載了技能包壓縮包的朋友。解壓之后壓縮包里通常有一個包含多個子技能目錄的根文件夾你選擇那個根文件夾導入Trae 會把它自動復制到當前項目的.trae/skills目錄下。省去了手動敲mkdir和cp的麻煩。如果你習慣用命令行也可以打開 Trae 的終端執行類似trae skills install ./superpowers的命令。不過這個命令在不同版本里差異較大我試過的兩個中文版版本一個支持一個不支持。所以最穩妥的判斷方法是先看 IDE 底部的狀態欄有沒有提示“檢測到技能”如果沒有就用命令面板導入。4.3 驗證 Trae 是否加載成功安裝完成后打開 Trae 的 AI 對話面板直接問當前項目里有哪些可用技能簡單描述每個技能的用途。如果 Trae 正確返回了 superpowers 和 debug 技能說明安裝成功。如果它回答“沒有發現技能”先確認目錄是否在項目根目錄以及SKILL.md是否以---開頭包含 frontmatter。另外Trae 有一個好處是AI 在回答時會顯示“正在使用技能 xxx”的標識。你實際讓它實現一個小功能比如“幫我寫一個讀取 CSV 并去重的函數”如果它開始輸出任務清單說明 superpowers 的技能協議已經被激活。這一步驗證效果比直接問更真實。5. 使用進階Superpowers 實際項目中的工作流5.1 實戰案例用 Superpowers 規劃“用戶注冊接口”光裝完不算完真正有價值的是把它用到實際任務里。我拿一個最常見的“用戶注冊接口”作為例子看看裝上 Superpowers 之后的 Codex CLI 是怎么工作的。我把需求發給它“實現一個用戶注冊接口需要校驗郵箱格式、密碼長度、用戶名唯一注冊成功返回 token。”在沒有技能時它很可能直接生成一個register.ts文件附帶幾行校驗邏輯然后結束。但有了 Superpowers 之后它第一步輸出的是任務清單 - [ ] Task: 創建用戶數據模型和數據庫表結構 Files affected: src/models/user.ts, migrations/xxx.sql Tests to run after completion: npm run test:model - [ ] Task: 實現郵箱格式和密碼長度校驗 Files affected: src/validators/auth.ts Tests to run after completion: npm run test:validators - [ ] Task: 實現用戶名唯一檢查 Files affected: src/services/user.ts Tests to run after completion: npm run test:service - [ ] Task: 生成 token 并構造響應 Files affected: src/controllers/auth.ts Tests to run after completion: npm run test:controllers然后它真的會按照這個順序逐個文件執行。執行完第一個任務它自動跑模型測試第二個任務完成再跑校驗器測試。中間有一次因為數據庫表字段寫錯導致測試失敗它沒有重置整個遷移文件而是讀取失敗日志定位到“外鍵約束缺失”只給遷移文件加了一行索引再重新跑測試通過后才繼續下一個任務。整個過程保持了很好的節奏。5.2 實戰案例讓 AI 自己完成“重構回歸測試”另一個典型場景是重構。我試了一個有 8 個文件的 Python 工具庫需求是把所有requests.get調用統一封裝成HttpClient。如果用原版代理它會全局搜索替換看起來很高效但經常漏掉異常處理不一致的問題。Superpowers 模式下的處理方式完全不同。它先掃描所有引用requests的模塊列出 8 個文件各自的調用方式有的用了timeout參數有的沒設置異常捕獲有的直接返回response.json()。然后它把任務清單分成三類第一類是提取公共HttpClient類第二類是分別適配 8 個模塊的調用點第三類是跑全量測試并對比返回結果。執行到第三個模塊時遇到一個很隱蔽的坑那個模塊里的函數依賴requests.get返回的原始 response 對象改成HttpClient之后返回值類型變了導致后續.status_code屬性取不到。如果按傳統方式AI 可能會在調用點硬塞一個response變量。但 debug 技能起作用了它讀跑了失敗測試的 traceback定位到是返回值類型不匹配然后手動修改HttpClient增加一個raw_response屬性同時保持封裝一致性。這個細節讓我覺得技能包真正值回票價。5.3 經驗如何讓技能包適配你的團隊規范社區默認的 Superpowers 流程可以滿足通用需求但每個團隊的代碼庫都有自己的約束。我建議在裝完基礎包之后往SKILL.md里追加團隊專屬規則。比如你們要求所有接口必須寫 OpenAPI 文檔那就在 Wrap-up 階段加一條“接口變更后必須同步更新docs/openapi.yaml。”比如你們要求測試命名必須用test_前綴那就在 Verify 階段寫明“測試命令只識別匹配test_*.py的用例”。這個方法比寫一堆口頭提示詞要穩得多因為技能文件是每次都會注入上下文的相當于把團隊規范寫進了 AI 的“入職手冊”。我后來把公司里常用的 commit 規范、環境變量命名規范都寫了進去AI 生成的代碼風格明顯更貼近老員工手筆。6. 常見問題與排查技巧實錄6.1 問題速查表下面是我在 Codex CLI 和 Trae 里安裝 Superpowers 過程中遇到過的典型問題整理成表方便排查?，F象可能原因解決方案技能文件放了但 AI 不讀沒有在AGENTS.md里引用技能路徑在AGENTS.md中顯式寫出SKILL.md的絕對路徑Trae 對話里說“沒有技能”SKILL.md缺少 frontmatter 或描述太長確保文件以---開頭description控制在 50 字左右AI 只在部分任務中使用 Superpowers技能描述寫的場景不夠具體模型沒匹配到修改description明確觸發條件比如“當任務涉及多文件修改時”安裝后 Codex CLI 報“找不到文件”復制文件時缺少子技能目錄用ls -R ~/.codex/skills檢查目錄結構測試失敗后 AI 無限重寫代碼技能文件里的 debug 協議沒有被加載單獨聲明debug/SKILL.md強調“禁止重寫整文件”Trae 中文版導入技能后不生效導入到了項目根目錄但 IDE 沒有刷新索引重啟 Trae 工作區或手動重開項目同一份 SKILL.md 在 Codex 和 Trae 里效果不同兩個工具對 frontmatter 和加載機制的解析不同分別配置Codex 偏重路徑引用Trae 偏重目錄掃描6.2 獨家避坑技巧最后分享幾個不太容易在網上看到的小經驗。第一技能文件里盡量不要出現“必須”“永遠”這類絕對化詞匯疊太多。模型是概率輸出的有的版本會過度遵循指令導致 AI 在簡單問答場景也強行拆解任務顯得很笨拙。解決辦法是在SKILL.md里加一句“如果用戶請求的是簡單事實問答或與代碼無關則不啟動編碼協議”。這樣既能保留技能優勢又不會把簡單對話復雜化。第二Codex CLI 里AGENTS.md的優先級很容易被項目本身的 README 影響。我發現如果 README 里寫了“run npm install npm test”AI 在驗證階段會傾向于直接執行整個測試套件而不是按子任務跑單文件測試。這會導致執行時間飆升。我后來在AGENTS.md里明確寫了“驗證依賴必須寫在任務清單中禁止自行擴大測試范圍”癥狀立刻緩解。第三如果你在 Trae 里同時裝了很多技能AI 可能因為描述沖突而不知道調用哪個。建議每個SKILL.md的description第一句話就點出觸發場景就像“當用戶要求創建新接口時使用”這樣不要泛泛而談“編碼技能”。實測泛化描述會讓 AI 選擇困難反而降低效率。第四版本升級問題。Codex CLI 和 Trae 都會頻繁更新技能加載機制偶爾會變。我遇到過 Trae 升級后需要到設置里重新分類技能目錄的情況。所以裝完技能后不要急著刪安裝包先保留原始壓縮包一周等確認所有功能穩定后再清理可以省去重新下載的麻煩。我自己裝了 Superpowers 之后最大的變化不是 AI 寫的代碼突然變牛了而是它做事的方式確實更像一個知道輕重緩急的同事先確認范圍再動手做完還自動給我一份變更說明。這種工作流帶來的安心感比單純生成代碼的爽感要重要得多。如果你手頭正好有 Codex CLI 或者 Trae建議先拿一個小功能跑一遍感受一下“被規范過的 AI”是什么手感。等你熟悉了流程再慢慢往里加自己的規則把它調成屬于你的開發搭子。 Superpowers技能包安裝指南：為Codex CLI和Trae打造規范AI編程工作流
最近 AI 編程圈里Superpowers 這個詞出現的頻率突然高了起來。如果你在折騰 Codex CLI或者用 Trae Work 中文版寫代碼大概率刷到過“codex cli 安裝 superpowers”“trae work cn 安裝 superpowers skill”這類熱詞。不少朋友以為 Superpowers 是某個新模型或者獨立 IDE其實不對。它更像一組打包好的“技能包Skill Pack”里面裝著系統性的提示詞、任務模板和工作流規則給 AI 編碼代理裝上后能讓它從“你說一句、它寫一段”的助手變成“自己拆任務、自己驗證、自己修 bug”的初級工程師。我花了一周時間在 Codex CLI 和 Trae 里反復裝、反復跑實際做完一個多文件重構和一輪單測修復最直觀的感受是這套東西最值錢的不是讓 AI 寫出更多代碼而是逼著它建立起“先規劃、再執行、后驗證”的可靠工作習慣。這篇文章就圍繞 Superpowers 的安裝和使用把我踩過的坑和驗證過的步驟完整寫出來。1. Superpowers 到底是什么一段給 AI 編程助手的“內功心法”1.1 原生編碼代理的三個結構性短板用過 Codex CLI 原版工作流的朋友大概都遇到過類似場景你讓它“給用戶注冊接口加個郵箱驗證”它啪一下把代碼改完直接告訴你“搞定”。但你稍微追問一句“影響面有沒有確認原有測試跑過沒有”它就開始支支吾吾甚至改一個變量名把另外三個文件帶崩。這不是模型能力不夠而是原生的編碼代理缺少三層約束。第一層是上下文管理AI 只能看到有限上下文經常改著改著就把最初的約束忘了。第二層是目標拆解它默認你會把任務講得足夠細可實際項目里一個需求往往牽扯多個文件、多個模塊沒人替它把步驟拆好。第三層是驗證閉環很多原生代理“寫代碼”和“驗證代碼”是割裂的它不會主動去跑測試也不會在測試掛了之后做最小化修復。這三個短板疊加起來就是大家常說的“AI 生成代碼一時爽合并之后火葬場”。Superpowers 這類技能包解決的就是這件事。它不改變底層模型而是通過一組結構化的指令文件在每次任務開始之前先給 AI 注入一套完整的工作協議。簡單說別人是讓 AI 直接答題Superpowers 是要求 AI 先把解題步驟寫出來、每步做完驗算、最后再交卷。這也是為什么很多人裝完之后覺得“AI 變聰明了”——本質不是模型升級而是行為流程被規范了。1.2 Superpowers 的核心模塊拆解、執行、驗證、收尾我實際把技能包解壓開看了一眼目錄結構比想象中清晰。通常最外層是一個主入口文件一般叫SKILL.md里面定義了整體工作流下面再掛幾個子技能目錄比如plan/、test/、debug/、review/。每個子技能都是獨立的 Markdown 指令文件專門負責某一類動作。以我手頭這個版本為例主流程分四步。第一步是規劃Plan它要求 AI 在寫任何代碼之前先輸出一份任務清單每條任務必須標注影響到的文件和執行完要跑哪個測試。第二步是執行Execute要求 AI 嚴格按照清單逐項實現不許跳步。第三步是驗證Verify每個子任務完成后必須運行相應測試不允許用“我覺得沒問題”代替測試結果。第四步是收尾Wrap-up要求 AI 更新相關文檔、檢查是否有臨時調試代碼、提交時寫清楚變更范圍。這套流程聽起來并不復雜但關鍵在于它是“強制”的。技能文件里通常會有類似“除非用戶明確要求否則禁止跳過驗證步驟如果測試失敗禁止直接重寫整個模塊必須先定位最小問題集”這樣的約束。模型在執行時會把這條規則當成最高優先級于是很多原本被忽略的驗證動作就變成了標準動作。1.3 一個最簡單的 SKILL.md 長什么樣為了讓大家對“技能包”有直觀印象我摘一段核心協議片段這基本是所有 Superpowers 變體都會包含的內容# Superpowers Core Protocol ## 1. Plan First Before writing any code, output a task checklist in this exact format: - [ ] Task: 具體任務描述 - Files affected: 涉及文件用絕對或相對路徑 - Tests to run after completion: 測試命令或文件 ## 2. Execute In Order - Complete tasks one by one; do not skip. - Do not batch changes across multiple modules unless the checklist explicitly includes them. ## 3. Verify Each Step - After each task, run the listed tests. - If the test fails, do NOT rewrite the whole file. Follow this loop: 1. Read the failure message. 2. Trace it to the smallest possible root cause. 3. Fix only the necessary lines. 4. Re-run the failing test. - If tests pass, move to the next task. ## 4. Wrap Up - Update README or inline comments if interface changed. - Scan for debug statements, TODO placeholders, and dead code. - Summarize the change in the final response.你別小看這幾段話。把它塞進 AI 的上下文之后效果立竿見影。我自己試過同一臺機器、同一個 Codex CLI沒裝技能前讓它重構一個 utils 模塊它直接丟給我一份改完的代碼裝完技能后它先列出 7 個子任務然后一項項執行每完成一項就自動跑單測中間掛了兩次每次都是通過定位失敗日志里的具體報錯去修而不是無腦回滾。就沖這個變化我認為 Superpowers 的價值被很多人低估了。2. 安裝前的準備Codex CLI 與 Trae 環境差異2.1 Codex CLI安裝、登錄、目錄結構想在 Codex CLI 里安裝 Superpowers先把基礎環境弄干凈。Codex CLI 是 OpenAI 官方的命令行編碼代理最常用的安裝方式就是通過 npm 全局安裝。如果你還沒裝直接執行npm install -g openai/codex裝完驗證版本codex --version我建議至少用支持 skills 機制的較新版本老版本對自定義指令的支持很弱裝了也白裝。登錄認證方面Codex CLI 通常需要配置 API Key 或者走官方登錄流程具體命令如下codex login或者設置環境變量OPENAI_API_KEY。這一步跑通之后你要清楚 Codex CLI 的配置目錄在哪里。默認情況下用戶在~/.codex/下會有一個配置目錄里面可以放全局指令文件、技能目錄、以及歷史記錄。項目級配置則放在當前工作目錄下的AGENTS.md里。這里有個容易踩坑的地方很多人把技能文件直接丟進項目根目錄但在 Codex CLI 的項目目錄里AI 并不是自動掃描所有 Markdown 文件。它通常只會讀取AGENTS.md以及明確通過指令引用的文件。所以后續安裝 Superpowers 時一定要在AGENTS.md里寫明“去哪個路徑讀取技能”否則文件放得再整齊也沒用。2.2 Trae Work 中文版找到工作區和技能目錄Trae 是字節跳動推出的 AI IDE國內用戶大多數用的是 Trae Work 中文版。它內置了比較完整的“技能Skill”機制和 Codex CLI 那種偏命令行的加載方式不太一樣。Trae 的項目級技能目錄是.trae/skills/你可以把它理解為 IDE 自己定義的一個擴展目錄只要把符合規范的文件放進去AI 在對話中就能自動感知到。我在 Trae Work 中文版里試了半天總結下來有幾點關鍵。第一技能目錄必須放在當前項目的根目錄下命名結構是.trae/skills/技能名/SKILL.md。第二Trae 對 SKILL.md 的 frontmatter 有要求需要在文件開頭寫上技能名稱和描述這樣 AI 才會在合適的場景下主動調用。第三如果你用的是“Work 工作區”模式最好把技能目錄放在工作區根目錄而不是某個子模塊目錄里否則 AI 可能掃描不到。需要注意Trae 中文版和英文版的配置目錄并不完全一樣但.trae/skills這個約定是通用的。所以你在網上看到英文教程里的路徑在中文版項目里同樣適用不需要額外改。2.3 兩者的共同邏輯技能包本質是“指令文件”很多人同時用 Codex CLI 和 Trae以為要分別準備兩套不同格式的 Superpowers。其實沒必要。技能包的本質是一組 Markdown 指令文件只要目錄結構和 frontmatter 符合目標工具的約定同一個SKILL.md可以在這兩個工具間復用。區別主要在加載方式。Codex CLI 更多依賴AGENTS.md去“建議”模型讀取某個文件而 Trae 則直接在 IDE 層主動解析.trae/skills目錄把技能描述注入到模型上下文中。理解了這層邏輯你在安裝時就不會被表面的差異帶偏放在 Trae 里的技能文件重點要寫好 frontmatter放在 Codex CLI 里的技能文件重點要寫好AGENTS.md的引用。后面兩章我分別給出完整步驟。3. 實操在 Codex CLI 中安裝 Superpowers 的完整步驟3.1 方式一用 git clone 導入現成技能包目前社區里有很多 Superpowers 的分支版本有的是完整技能集合有的是精簡版。最省事的方式是直接把技能倉庫克隆到本地然后復制到 Codex CLI 的技能目錄。以我自己為例我習慣把技能統一放在~/.codex/skills/下這樣所有項目都能復用。git clone 你關注的技能倉庫地址 superpowers-temp mkdir -p ~/.codex/skills cp -r superpowers-temp/skills/* ~/.codex/skills/這里有個小細節技能倉庫里的skills/目錄可能包含多個子技能文件夾比如plan、test、debug。你要保證復制到~/.codex/skills/后每個子技能文件夾下面都有獨立的SKILL.md。復制完可以檢查一下ls -R ~/.codex/skills如果看到類似~/.codex/skills/debug/SKILL.md這樣的結構說明文件放對了。但如果你只復制了倉庫根目錄下的SKILL.md而漏掉子技能目錄后面 AI 調用子技能時會找不到文件出現“技能未定義”的報錯。3.2 方式二從零手寫 Superpowers 核心技能如果你不想折騰 git clone完全可以通過手動創建目錄和文件把第一節那個核心協議寫進去。這個方法最大的好處是你可以按自己的團隊規范定制內容不受社區版本限制。mkdir -p ~/.codex/skills/superpowers cat ~/.codex/skills/superpowers/SKILL.md EOF --- name: superpowers description: 強制 AI 在編碼任務中執行“規劃-執行-驗證-收尾”的完整工作流。 --- # Superpowers Core Protocol 這里寫前面摘錄的四步協議內容 EOF寫完這個主文件之后我建議再補一個簡單的調試子技能mkdir -p ~/.codex/skills/debug cat ~/.codex/skills/debug/SKILL.md EOF --- name: debug description: 當測試失敗時按最小化修復原則定位問題。 --- # Debug Protocol 1. Read the full failure output. 2. Find the failing function and its input. 3. Trace data flow backward from the failure. 4. Modify only the minimum lines required. 5. Re-run the exact failed test before proceeding. EOF手動創建的好處是你能清楚地知道每一行指令在干什么出了問題也容易排查。壞處是技能少了覆蓋場景有限。對新手我更推薦先用方式一裝社區完整版跑通之后再慢慢改出自己的版本。3.3 在 AGENTS.md 中聲明技能并驗證文件放好之后最關鍵的一步是讓 Codex CLI 知道這些技能的存在。你需要在當前項目根目錄下創建或修改AGENTS.md在里面明確寫出加載指令# Agent Instructions ## Skills - 處理代碼任務前必須讀取 ~/.codex/skills/superpowers/SKILL.md 并嚴格遵循其中的流程。 - 當測試失敗時必須讀取 ~/.codex/skills/debug/SKILL.md 并按照調試協議執行。 ## Constraints - 禁止在未完成任務清單中所有步驟的情況下向用戶報告“完成”。 - 涉及多文件修改時必須先輸出影響文件列表。這里需要提醒的是AGENTS.md和AGENTS.md在不同項目里可能被覆蓋尤其是多個工具同時管理它時。我的習慣是把全局技能聲明放在~/.codex/config.toml或 Codex CLI 的全局指令里把項目相關的約束放在項目AGENTS.md里避免每次克隆新項目都要重新配置。配置完成后啟動 Codex CLI輸入你有哪幾個技能分別是在什么場景下使用如果 AI 能準確說出 superpowers 和 debug 技能的名字并簡單描述用途說明加載成功。如果它只回答“我沒有技能”或者“我不確定”大概率是AGENTS.md路徑寫錯或者技能文件里的 frontmatter 缺失。4. 實操在 Trae 中安裝 Superpowers Skill 的兩種方式4.1 通過項目內.trae/skills目錄安裝在 Trae Work 中文版里安裝我推薦直接用項目內.trae/skills目錄步驟非常直白。先在項目根目錄創建技能目錄mkdir -p .trae/skills/superpowers然后把前面寫好的SKILL.md放進這個文件夾。如果你的 Superpowers 里還有其他子技能比如debug就再建一個mkdir -p .trae/skills/debug放好之后Trae 會自動掃描項目中的.trae/skills目錄。注意這里的 skill 描述非常重要。Trae 會把SKILL.md中 frontmatter 里的name和description傳給模型幫助它判斷“什么時候該調用這個技能”。所以描述要寫得具體一點別寫“這是一個編碼輔助技能”這種廢話而應該寫“當用戶要求實現新功能或重構代碼時先調用此技能進行任務規劃和驗證”。我實際測試過把技能文件放到.trae/skills后不重啟 IDE 也能在較短時間內被識別到。但如果你的 Trae 版本比較老可能需要重啟一下工作區或者重新打開項目讓索引刷新。4.2 通過 Trae CLI / 命令面板導入除了手動建目錄Trae 還支持通過命令面板導入。在 Trae 里按下CmdShiftP或CtrlShiftP輸入“skills”關鍵詞一般能看到“Import Skill”或“安裝技能”之類的選項。選擇該項后會彈出一個文件選擇窗口直接指向你下載好的 Superpowers 文件夾即可。這個方法適合從網上下載了技能包壓縮包的朋友。解壓之后壓縮包里通常有一個包含多個子技能目錄的根文件夾你選擇那個根文件夾導入Trae 會把它自動復制到當前項目的.trae/skills目錄下。省去了手動敲mkdir和cp的麻煩。如果你習慣用命令行也可以打開 Trae 的終端執行類似trae skills install ./superpowers的命令。不過這個命令在不同版本里差異較大我試過的兩個中文版版本一個支持一個不支持。所以最穩妥的判斷方法是先看 IDE 底部的狀態欄有沒有提示“檢測到技能”如果沒有就用命令面板導入。4.3 驗證 Trae 是否加載成功安裝完成后打開 Trae 的 AI 對話面板直接問當前項目里有哪些可用技能簡單描述每個技能的用途。如果 Trae 正確返回了 superpowers 和 debug 技能說明安裝成功。如果它回答“沒有發現技能”先確認目錄是否在項目根目錄以及SKILL.md是否以---開頭包含 frontmatter。另外Trae 有一個好處是AI 在回答時會顯示“正在使用技能 xxx”的標識。你實際讓它實現一個小功能比如“幫我寫一個讀取 CSV 并去重的函數”如果它開始輸出任務清單說明 superpowers 的技能協議已經被激活。這一步驗證效果比直接問更真實。5. 使用進階Superpowers 實際項目中的工作流5.1 實戰案例用 Superpowers 規劃“用戶注冊接口”光裝完不算完真正有價值的是把它用到實際任務里。我拿一個最常見的“用戶注冊接口”作為例子看看裝上 Superpowers 之后的 Codex CLI 是怎么工作的。我把需求發給它“實現一個用戶注冊接口需要校驗郵箱格式、密碼長度、用戶名唯一注冊成功返回 token。”在沒有技能時它很可能直接生成一個register.ts文件附帶幾行校驗邏輯然后結束。但有了 Superpowers 之后它第一步輸出的是任務清單 - [ ] Task: 創建用戶數據模型和數據庫表結構 Files affected: src/models/user.ts, migrations/xxx.sql Tests to run after completion: npm run test:model - [ ] Task: 實現郵箱格式和密碼長度校驗 Files affected: src/validators/auth.ts Tests to run after completion: npm run test:validators - [ ] Task: 實現用戶名唯一檢查 Files affected: src/services/user.ts Tests to run after completion: npm run test:service - [ ] Task: 生成 token 并構造響應 Files affected: src/controllers/auth.ts Tests to run after completion: npm run test:controllers然后它真的會按照這個順序逐個文件執行。執行完第一個任務它自動跑模型測試第二個任務完成再跑校驗器測試。中間有一次因為數據庫表字段寫錯導致測試失敗它沒有重置整個遷移文件而是讀取失敗日志定位到“外鍵約束缺失”只給遷移文件加了一行索引再重新跑測試通過后才繼續下一個任務。整個過程保持了很好的節奏。5.2 實戰案例讓 AI 自己完成“重構回歸測試”另一個典型場景是重構。我試了一個有 8 個文件的 Python 工具庫需求是把所有requests.get調用統一封裝成HttpClient。如果用原版代理它會全局搜索替換看起來很高效但經常漏掉異常處理不一致的問題。Superpowers 模式下的處理方式完全不同。它先掃描所有引用requests的模塊列出 8 個文件各自的調用方式有的用了timeout參數有的沒設置異常捕獲有的直接返回response.json()。然后它把任務清單分成三類第一類是提取公共HttpClient類第二類是分別適配 8 個模塊的調用點第三類是跑全量測試并對比返回結果。執行到第三個模塊時遇到一個很隱蔽的坑那個模塊里的函數依賴requests.get返回的原始 response 對象改成HttpClient之后返回值類型變了導致后續.status_code屬性取不到。如果按傳統方式AI 可能會在調用點硬塞一個response變量。但 debug 技能起作用了它讀跑了失敗測試的 traceback定位到是返回值類型不匹配然后手動修改HttpClient增加一個raw_response屬性同時保持封裝一致性。這個細節讓我覺得技能包真正值回票價。5.3 經驗如何讓技能包適配你的團隊規范社區默認的 Superpowers 流程可以滿足通用需求但每個團隊的代碼庫都有自己的約束。我建議在裝完基礎包之后往SKILL.md里追加團隊專屬規則。比如你們要求所有接口必須寫 OpenAPI 文檔那就在 Wrap-up 階段加一條“接口變更后必須同步更新docs/openapi.yaml。”比如你們要求測試命名必須用test_前綴那就在 Verify 階段寫明“測試命令只識別匹配test_*.py的用例”。這個方法比寫一堆口頭提示詞要穩得多因為技能文件是每次都會注入上下文的相當于把團隊規范寫進了 AI 的“入職手冊”。我后來把公司里常用的 commit 規范、環境變量命名規范都寫了進去AI 生成的代碼風格明顯更貼近老員工手筆。6. 常見問題與排查技巧實錄6.1 問題速查表下面是我在 Codex CLI 和 Trae 里安裝 Superpowers 過程中遇到過的典型問題整理成表方便排查?，F象可能原因解決方案技能文件放了但 AI 不讀沒有在AGENTS.md里引用技能路徑在AGENTS.md中顯式寫出SKILL.md的絕對路徑Trae 對話里說“沒有技能”SKILL.md缺少 frontmatter 或描述太長確保文件以---開頭description控制在 50 字左右AI 只在部分任務中使用 Superpowers技能描述寫的場景不夠具體模型沒匹配到修改description明確觸發條件比如“當任務涉及多文件修改時”安裝后 Codex CLI 報“找不到文件”復制文件時缺少子技能目錄用ls -R ~/.codex/skills檢查目錄結構測試失敗后 AI 無限重寫代碼技能文件里的 debug 協議沒有被加載單獨聲明debug/SKILL.md強調“禁止重寫整文件”Trae 中文版導入技能后不生效導入到了項目根目錄但 IDE 沒有刷新索引重啟 Trae 工作區或手動重開項目同一份 SKILL.md 在 Codex 和 Trae 里效果不同兩個工具對 frontmatter 和加載機制的解析不同分別配置Codex 偏重路徑引用Trae 偏重目錄掃描6.2 獨家避坑技巧最后分享幾個不太容易在網上看到的小經驗。第一技能文件里盡量不要出現“必須”“永遠”這類絕對化詞匯疊太多。模型是概率輸出的有的版本會過度遵循指令導致 AI 在簡單問答場景也強行拆解任務顯得很笨拙。解決辦法是在SKILL.md里加一句“如果用戶請求的是簡單事實問答或與代碼無關則不啟動編碼協議”。這樣既能保留技能優勢又不會把簡單對話復雜化。第二Codex CLI 里AGENTS.md的優先級很容易被項目本身的 README 影響。我發現如果 README 里寫了“run npm install npm test”AI 在驗證階段會傾向于直接執行整個測試套件而不是按子任務跑單文件測試。這會導致執行時間飆升。我后來在AGENTS.md里明確寫了“驗證依賴必須寫在任務清單中禁止自行擴大測試范圍”癥狀立刻緩解。第三如果你在 Trae 里同時裝了很多技能AI 可能因為描述沖突而不知道調用哪個。建議每個SKILL.md的description第一句話就點出觸發場景就像“當用戶要求創建新接口時使用”這樣不要泛泛而談“編碼技能”。實測泛化描述會讓 AI 選擇困難反而降低效率。第四版本升級問題。Codex CLI 和 Trae 都會頻繁更新技能加載機制偶爾會變。我遇到過 Trae 升級后需要到設置里重新分類技能目錄的情況。所以裝完技能后不要急著刪安裝包先保留原始壓縮包一周等確認所有功能穩定后再清理可以省去重新下載的麻煩。我自己裝了 Superpowers 之后最大的變化不是 AI 寫的代碼突然變牛了而是它做事的方式確實更像一個知道輕重緩急的同事先確認范圍再動手做完還自動給我一份變更說明。這種工作流帶來的安心感比單純生成代碼的爽感要重要得多。如果你手頭正好有 Codex CLI 或者 Trae建議先拿一個小功能跑一遍感受一下“被規范過的 AI”是什么手感。等你熟悉了流程再慢慢往里加自己的規則把它調成屬于你的開發搭子。