1. 從“superpowers”這個(gè)熱詞說起它到底指什么第一次看到“superpowers”這個(gè)詞掛在熱搜上我下意識(shí)以為是某部新上映的超級(jí)英雄電影或者是某個(gè)游戲里新出的技能系統(tǒng)。翻了一圈討論才發(fā)現(xiàn)大家嘴里的“superpowers”其實(shí)指向一個(gè)很具體的東西——一套給 AI 編程助手用的技能擴(kuò)展框架。它的核心思路特別樸素把那些你反復(fù)要跟 AI 解釋的流程、規(guī)范、檢查清單提前寫成一份份“技能包”等真正干活的時(shí)候AI 自己按需調(diào)用而不是每次都要你從頭交代一遍。這個(gè)定位很關(guān)鍵。很多人第一次接觸它腦子里想的是“裝個(gè)插件讓 AI 變聰明”但實(shí)際用下來會(huì)發(fā)現(xiàn)它解決的不是“聰明不聰明”的問題而是“穩(wěn)不穩(wěn)定、聽不聽話”的問題。你讓 AI 寫代碼它可能這次記得跑測(cè)試下次就忘了這次按你的命名規(guī)范來下次又自由發(fā)揮。superpowers 想干的事就是把這些“應(yīng)該做但容易忘”的動(dòng)作固化下來變成一套可復(fù)用、可組合的技能體系。那“想要安裝 superpowers”這個(gè)訴求背后用戶到底在找什么我觀察下來大致分三類人。第一類是已經(jīng)在用 AI 輔助寫代碼的開發(fā)者被“每次都要重復(fù)交代上下文”折磨得夠嗆想找個(gè)辦法把常用流程沉淀下來。第二類是團(tuán)隊(duì)里負(fù)責(zé)規(guī)范落地的人希望把代碼審查、提交規(guī)范、測(cè)試要求這些東西變成 AI 能自動(dòng)執(zhí)行的技能減少人為遺漏。第三類是純粹被熱詞吸引過來的新手想搞清楚這玩意兒到底值不值得折騰。這篇文章我打算按“先搞懂它是什么、再動(dòng)手裝、裝完怎么用、用的時(shí)候踩哪些坑”這條線來寫。不管你是哪一類人看完應(yīng)該都能判斷出這東西適不適合自己的場(chǎng)景以及如果適合具體該怎么落地。我會(huì)盡量把每一步背后的“為什么”講清楚而不是甩一堆命令讓你照抄——因?yàn)檫@類工具最大的坑往往就藏在“照抄但沒理解”里面。2. superpowers 的底層邏輯技能包機(jī)制到底怎么運(yùn)轉(zhuǎn)2.1 它和普通插件、提示詞模板的本質(zhì)區(qū)別要理解 superpowers得先把它和兩個(gè)容易混淆的東西區(qū)分開普通插件和提示詞模板。普通插件通常是往工具里加功能比如加個(gè)新命令、接個(gè)新模型。提示詞模板則是你手動(dòng)復(fù)制粘貼一段話給 AI。superpowers 介于兩者之間但機(jī)制完全不同——它是一套按需加載的技能庫。每個(gè)技能是一個(gè)獨(dú)立文件里面寫清楚了“什么情況下用這個(gè)技能”“用的時(shí)候按什么步驟走”“做完之后怎么驗(yàn)證”。AI 在干活的過程中會(huì)根據(jù)當(dāng)前任務(wù)自動(dòng)判斷該不該調(diào)用某個(gè)技能而不是你每次手動(dòng)喂給它。這個(gè)“自動(dòng)判斷”是它最值錢的地方也是最容易出問題的地方。因?yàn)?AI 判斷“該不該用某個(gè)技能”靠的是技能描述里的觸發(fā)條件如果描述寫得含糊它要么該用的時(shí)候不用要么不該用的時(shí)候亂用。我后面會(huì)專門講怎么寫好這個(gè)觸發(fā)描述。2.2 技能文件里到底裝了什么一個(gè)典型的技能文件結(jié)構(gòu)上大致包含這幾塊內(nèi)容。第一塊是元信息包括技能名稱、一句話描述、適用場(chǎng)景。這塊決定了 AI 能不能在正確的時(shí)機(jī)想起它。第二塊是執(zhí)行步驟也就是這個(gè)技能被調(diào)用后AI 應(yīng)該按什么順序做什么事。第三塊是約束條件比如“不要修改測(cè)試文件”“提交前必須跑 lint”這類硬性要求。第四塊是驗(yàn)證方式告訴 AI 做完之后怎么確認(rèn)自己沒搞砸。我拿一個(gè)真實(shí)場(chǎng)景舉例。假設(shè)你有個(gè)技能叫“新增 API 接口”那它的執(zhí)行步驟可能是先看現(xiàn)有接口的目錄結(jié)構(gòu)再按同樣的模式建文件然后補(bǔ)上路由注冊(cè)接著寫對(duì)應(yīng)的測(cè)試用例最后跑一遍測(cè)試確認(rèn)通過。約束條件可能是“不要?jiǎng)右延械慕涌谖募薄皽y(cè)試用例必須覆蓋正常和異常兩種情況”。驗(yàn)證方式就是“測(cè)試全綠才算完成”。這套結(jié)構(gòu)看起來簡(jiǎn)單但真正寫起來難點(diǎn)在于步驟的顆粒度。寫太粗AI 自由發(fā)揮的空間太大等于沒約束寫太細(xì)又變成死板的腳本遇到稍微不一樣的情況就卡住。我的經(jīng)驗(yàn)是步驟寫到“一個(gè)動(dòng)作一個(gè)意圖”這個(gè)層級(jí)比較合適具體怎么實(shí)現(xiàn)留給 AI 判斷。2.3 為什么“按需加載”比“全量塞入”更靠譜有人可能會(huì)想那我干脆把所有規(guī)范、所有流程一次性寫進(jìn)系統(tǒng)提示詞里不就行了何必搞什么按需加載這個(gè)問題我實(shí)測(cè)過。把一大堆規(guī)范全塞進(jìn)上下文有兩個(gè)直接后果。一是上下文被占滿真正跟當(dāng)前任務(wù)相關(guān)的信息反而被擠到邊緣AI 的注意力被稀釋。二是規(guī)則之間會(huì)打架比如你同時(shí)寫了“提交前必須跑全量測(cè)試”和“小改動(dòng)快速提交”AI 遇到具體情況時(shí)不知道該聽誰的。按需加載的好處就在這兒每個(gè)技能只在它該出現(xiàn)的時(shí)候出現(xiàn)上下文干凈規(guī)則之間也不會(huì)互相干擾。代價(jià)是你得把技能的觸發(fā)條件寫準(zhǔn)否則該加載的時(shí)候加載不出來那就白搭了。這其實(shí)是一種權(quán)衡——用“寫清楚觸發(fā)條件”的成本換“運(yùn)行時(shí)上下文干凈”的收益。3. 安裝前的環(huán)境盤點(diǎn)別急著敲命令3.1 先確認(rèn)你的 AI 助手支持技能擴(kuò)展superpowers 不是獨(dú)立運(yùn)行的程序它依附在某個(gè) AI 編程助手之上。所以安裝前第一件事是確認(rèn)你用的助手支不支持這類技能擴(kuò)展機(jī)制。不同助手的支持程度差別很大有的原生支持有的需要借助配置文件有的壓根不支持。怎么確認(rèn)最直接的辦法是翻你所用助手的官方文檔搜“技能”“擴(kuò)展”“自定義指令”這類關(guān)鍵詞。如果文檔里明確提到了技能目錄、技能文件格式那基本就沒問題。如果翻遍了都找不到那可能得換個(gè)思路或者考慮換一個(gè)支持該機(jī)制的助手。我見過不少人卡在這一步裝了半天發(fā)現(xiàn)助手根本不認(rèn)白折騰。所以這一步別省花十分鐘確認(rèn)清楚比后面返工強(qiáng)。3.2 目錄結(jié)構(gòu)規(guī)劃技能放哪兒、怎么分類確認(rèn)支持之后接下來是規(guī)劃技能存放的目錄。這里有個(gè)容易被忽略的點(diǎn)技能目錄的位置和結(jié)構(gòu)直接影響 AI 能不能正確找到并加載技能。常見的做法是在項(xiàng)目根目錄下建一個(gè)專門的技能目錄比如.skills或者skills然后在里面按類別分子目錄。比如coding放編碼相關(guān)技能review放審查相關(guān)技能deploy放部署相關(guān)技能。分子目錄不是為了好看而是為了讓技能列表在加載時(shí)更有層次AI 在檢索時(shí)也更容易定位。這里有個(gè)實(shí)操細(xì)節(jié)技能文件的命名要能自解釋。別用skill1.md、skill2.md這種用add-api-endpoint.md、run-integration-test.md這種一看就知道干什么的名字。因?yàn)?AI 在判斷該不該加載某個(gè)技能時(shí)文件名和描述都是重要線索命名清晰能顯著提高觸發(fā)準(zhǔn)確率。3.3 版本與依賴那些文檔里不會(huì)寫的坑環(huán)境盤點(diǎn)里還有一塊是版本和依賴。這塊官方文檔通常寫得比較簡(jiǎn)略但實(shí)際踩坑最多。第一個(gè)坑是助手版本。技能擴(kuò)展機(jī)制在不同版本里可能有差異老版本可能不支持某些字段新版本可能改了文件格式。裝之前先確認(rèn)你的助手版本然后對(duì)照文檔看這個(gè)版本支持哪些特性。如果版本太老可能得先升級(jí)。第二個(gè)坑是技能文件里的路徑引用。如果你的技能步驟里寫了“讀取./config/settings.json”這種相對(duì)路徑那這個(gè)路徑是相對(duì)于項(xiàng)目根目錄還是相對(duì)于技能文件所在目錄不同助手的行為可能不一樣。這個(gè)必須實(shí)測(cè)確認(rèn)否則技能執(zhí)行時(shí)會(huì)找不到文件。第三個(gè)坑是編碼和換行符。技能文件如果是 Windows 下編輯的可能帶 BOM 頭或者 CRLF 換行某些助手解析時(shí)會(huì)出問題。建議統(tǒng)一用 UTF-8 無 BOM、LF 換行保存。這個(gè)坑很隱蔽出問題時(shí)往往報(bào)錯(cuò)信息也不明確排查起來費(fèi)勁。4. 一步步把 superpowers 裝起來4.1 獲取技能文件自己寫還是用現(xiàn)成的安裝 superpowers 的第一步是搞到技能文件。這里有兩條路用別人寫好的現(xiàn)成技能或者自己從零寫。現(xiàn)成技能的好處是省事壞處是不一定貼合你的項(xiàng)目。別人的技能里可能寫了他自己的目錄結(jié)構(gòu)、命名規(guī)范、測(cè)試框架直接拿來用AI 會(huì)按那套規(guī)范干活跟你的項(xiàng)目對(duì)不上。所以我的建議是現(xiàn)成技能可以拿來當(dāng)參考但真正要用還是得按自己項(xiàng)目的情況改一遍。自己寫的好處是貼合度高壞處是前期投入大。不過這個(gè)投入是值得的因?yàn)閷懠寄艿倪^程本身就是把你腦子里那些“隱性規(guī)范”顯性化的過程。很多人寫著寫著才發(fā)現(xiàn)原來自己團(tuán)隊(duì)里對(duì)“什么叫完成”都沒有統(tǒng)一標(biāo)準(zhǔn)。4.2 技能文件的最小可用模板下面給一個(gè)最小可用的技能文件模板你可以直接拿去改。注意這是通用結(jié)構(gòu)具體字段名可能因助手而異以你所用助手的文檔為準(zhǔn)。--- name: add-api-endpoint description: 當(dāng)需要新增一個(gè) API 接口時(shí)使用此技能包括建文件、注冊(cè)路由、寫測(cè)試 trigger: 用戶要求新增接口、添加路由、創(chuàng)建 endpoint --- ## 執(zhí)行步驟 1. 查看現(xiàn)有接口目錄結(jié)構(gòu)確認(rèn)文件組織方式 2. 按現(xiàn)有模式創(chuàng)建新的接口文件 3. 在路由注冊(cè)文件中添加對(duì)應(yīng)路由 4. 編寫測(cè)試用例覆蓋正常和異常情況 5. 運(yùn)行測(cè)試確認(rèn)全部通過 ## 約束條件 - 不要修改已有的接口文件 - 測(cè)試用例必須包含至少一個(gè)異常場(chǎng)景 - 提交前必須運(yùn)行 lint ## 驗(yàn)證方式 - 測(cè)試全部通過 - lint 無報(bào)錯(cuò)這個(gè)模板里trigger字段是最關(guān)鍵的。它決定了 AI 在什么情況下會(huì)想起這個(gè)技能。寫得太窄該用的時(shí)候用不上寫得太寬不該用的時(shí)候亂用。我的經(jīng)驗(yàn)是把用戶可能說的幾種典型表述都列進(jìn)去覆蓋常見說法。4.3 讓助手識(shí)別技能配置與驗(yàn)證技能文件寫好后得讓助手知道去哪兒找。這一步通常需要在助手的配置文件里指定技能目錄路徑。具體配置方式因助手而異有的是在設(shè)置里填路徑有的是在項(xiàng)目配置文件里寫。配置完之后一定要驗(yàn)證。驗(yàn)證方法是給助手一個(gè)明確會(huì)觸發(fā)某個(gè)技能的任務(wù)看它會(huì)不會(huì)自動(dòng)加載并執(zhí)行。比如你有個(gè)“新增接口”的技能那就讓助手“幫我加一個(gè)查詢用戶列表的接口”觀察它是不是按你寫的步驟走。如果沒觸發(fā)先檢查三件事技能目錄路徑對(duì)不對(duì)、技能文件的元信息格式對(duì)不對(duì)、觸發(fā)描述是不是太窄。這三個(gè)是最常見的原因。4.4 第一次跑通用一個(gè)簡(jiǎn)單任務(wù)驗(yàn)證全流程別一上來就拿復(fù)雜任務(wù)試。找個(gè)最簡(jiǎn)單的、你閉著眼睛都能做對(duì)的任務(wù)比如“給現(xiàn)有函數(shù)加個(gè)參數(shù)校驗(yàn)”讓助手帶著技能跑一遍。跑的時(shí)候重點(diǎn)觀察三件事。第一技能有沒有被加載。第二步驟有沒有被遵循。第三約束有沒有被遵守。這三件事里任何一件出問題都說明技能文件需要調(diào)整。我第一次跑通的時(shí)候發(fā)現(xiàn)助手確實(shí)加載了技能但步驟執(zhí)行到一半就跳步了。后來發(fā)現(xiàn)是步驟描述里用了“然后”“接著”這種模糊的連接詞AI 理解成了可選步驟。改成明確的編號(hào)列表之后就正常了。這種細(xì)節(jié)不實(shí)際跑一遍根本發(fā)現(xiàn)不了。5. 裝完之后怎么用才不白裝5.1 技能的組合與嵌套讓多個(gè)技能協(xié)同工作單個(gè)技能能解決的問題有限superpowers 真正的威力在于技能組合。比如你有一個(gè)“新增接口”的技能一個(gè)“寫測(cè)試”的技能一個(gè)“代碼審查”的技能。理想情況下新增接口時(shí)自動(dòng)觸發(fā)寫測(cè)試寫完測(cè)試自動(dòng)觸發(fā)審查形成一條流水線。但組合有個(gè)前提技能之間的邊界要清晰。如果兩個(gè)技能都聲稱自己負(fù)責(zé)“寫測(cè)試”那 AI 就懵了。所以設(shè)計(jì)技能時(shí)要明確每個(gè)技能的職責(zé)范圍避免重疊。嵌套則是另一個(gè)層面的問題。有的技能步驟里會(huì)引用另一個(gè)技能比如“新增接口”的步驟里寫“調(diào)用代碼審查技能”。這種嵌套要小心因?yàn)槿绻灰玫募寄苡|發(fā)條件沒寫清楚可能導(dǎo)致無限遞歸或者加載失敗。我的做法是嵌套層級(jí)不超過兩層再深就容易出問題。5.2 觸發(fā)時(shí)機(jī)調(diào)優(yōu)為什么你的技能該用的時(shí)候沒動(dòng)靜技能該觸發(fā)卻沒觸發(fā)這是最常見的問題。原因通常有三個(gè)。第一個(gè)是觸發(fā)描述太窄。比如你寫的是“當(dāng)用戶說‘新增接口’時(shí)觸發(fā)”但用戶實(shí)際說的是“加個(gè) API”那就匹配不上。解決辦法是把常見同義表述都列進(jìn)去。第二個(gè)是技能描述和當(dāng)前任務(wù)的相關(guān)度不夠。AI 判斷該不該加載某個(gè)技能靠的是語義相關(guān)度。如果你的技能描述寫得太泛比如“用于處理代碼相關(guān)任務(wù)”那它跟任何任務(wù)的相關(guān)度都不高自然不會(huì)被優(yōu)先加載。描述要具體最好帶上領(lǐng)域關(guān)鍵詞。第三個(gè)是技能數(shù)量太多導(dǎo)致競(jìng)爭(zhēng)。如果你有幾十個(gè)技能每個(gè)的描述都差不多AI 在檢索時(shí)就會(huì)猶豫。這時(shí)候要么精簡(jiǎn)技能數(shù)量要么把技能分組讓 AI 先選組再選技能。5.3 技能失效的排查鏈路技能突然不工作了怎么排查我總結(jié)了一條鏈路按順序走基本能定位問題。第一步確認(rèn)技能文件還在、沒被誤刪或改名。聽起來很蠢但確實(shí)發(fā)生過。第二步確認(rèn)配置文件里的路徑?jīng)]變。有時(shí)候項(xiàng)目結(jié)構(gòu)調(diào)整了路徑?jīng)]跟著改。第三步確認(rèn)技能文件的格式?jīng)]被破壞。比如元信息里的引號(hào)沒閉合、縮進(jìn)亂了都會(huì)導(dǎo)致解析失敗。第四步確認(rèn)觸發(fā)條件還能匹配當(dāng)前任務(wù)。如果任務(wù)描述變了可能就不觸發(fā)了。第五步看助手的日志。大多數(shù)助手在加載技能失敗時(shí)會(huì)打日志日志里通常有具體原因。這一步最直接但很多人忘了看。5.4 團(tuán)隊(duì)協(xié)作場(chǎng)景技能庫怎么共享和維護(hù)如果是一個(gè)人用技能庫怎么放都行。但如果是團(tuán)隊(duì)用就得考慮共享和維護(hù)的問題。共享方面技能庫最好跟代碼一起進(jìn)版本控制。這樣每個(gè)人拉下來都是同一套技能不會(huì)出現(xiàn)“你那兒能跑我這兒不能跑”的情況。維護(hù)方面得有個(gè)負(fù)責(zé)人。技能庫跟代碼一樣會(huì)隨著項(xiàng)目演進(jìn)而過時(shí)。如果沒人維護(hù)半年后技能里寫的規(guī)范可能早就跟實(shí)際不符了AI 按過時(shí)規(guī)范干活反而添亂。我的建議是把技能庫的更新納入代碼審查流程改規(guī)范的時(shí)候順手把對(duì)應(yīng)技能也改了。6. 那些我踩過的坑和總結(jié)出的經(jīng)驗(yàn)6.1 技能寫太細(xì)反而不好用剛開始寫技能的時(shí)候我恨不得把每個(gè)動(dòng)作都寫死比如“打開文件 A在第 10 行插入代碼 B”。結(jié)果發(fā)現(xiàn)只要項(xiàng)目結(jié)構(gòu)稍微一變技能就失效了。后來我改成寫意圖而不是寫動(dòng)作比如“在路由注冊(cè)文件中添加對(duì)應(yīng)路由”具體在哪個(gè)文件、哪一行讓 AI 自己判斷。這樣靈活度高很多適應(yīng)性也強(qiáng)。這個(gè)經(jīng)驗(yàn)的核心是技能應(yīng)該描述“做什么”和“為什么”而不是“怎么做”。怎么做留給 AI因?yàn)?AI 比你更了解當(dāng)前代碼的具體情況。6.2 約束條件寫太硬會(huì)卡死流程約束條件是必要的但寫太硬會(huì)出問題。我寫過一個(gè)約束叫“提交前必須跑全量測(cè)試”結(jié)果有次改了個(gè)注釋AI 也老老實(shí)實(shí)跑了半小時(shí)全量測(cè)試。后來我改成“提交前必須跑與改動(dòng)相關(guān)的測(cè)試”效率高多了。約束條件的度怎么把握我的標(biāo)準(zhǔn)是約束應(yīng)該防的是“錯(cuò)誤行為”而不是“所有行為”。跑全量測(cè)試防的是“沒測(cè)試就提交”但改注釋這種情況本來就不需要全量測(cè)試約束不該一刀切。6.3 技能版本管理改了之后怎么回滾技能文件也是代碼改了之后可能出問題所以需要版本管理。最土的辦法是每次改之前手動(dòng)備份一份但太麻煩。正規(guī)做法是跟代碼一起進(jìn) Git每次改動(dòng)都有記錄出問題直接回滾。這里有個(gè)細(xì)節(jié)技能文件的改動(dòng)最好單獨(dú)提交別跟業(yè)務(wù)代碼混在一起。這樣回滾的時(shí)候不會(huì)誤傷業(yè)務(wù)代碼排查問題也清晰。6.4 什么時(shí)候該放棄某個(gè)技能不是所有技能都值得保留。如果一個(gè)技能滿足下面任意一條我會(huì)考慮刪掉它觸發(fā)率極低、每次觸發(fā)都要手動(dòng)糾正、維護(hù)成本高于收益、跟其他技能功能重疊。技能庫跟代碼庫一樣需要定期清理。留著不用的技能不僅占地方還會(huì)干擾 AI 的判斷。我一般每個(gè)月過一遍技能庫把一個(gè)月內(nèi)沒觸發(fā)過的技能標(biāo)記出來連續(xù)兩個(gè)月沒觸發(fā)就刪掉。6.5 給新手的三個(gè)務(wù)實(shí)建議如果你剛開始接觸 superpowers我給三個(gè)建議。第一從一個(gè)小技能開始別一上來就搞一套完整的技能體系。先寫一個(gè)你每天都要重復(fù)交代的流程跑通了再擴(kuò)展。第二技能描述用你自己的話寫別抄別人的。因?yàn)?AI 匹配的是語義用你自己的表述習(xí)慣寫觸發(fā)準(zhǔn)確率更高。第三每次技能沒按預(yù)期工作都當(dāng)成一次學(xué)習(xí)機(jī)會(huì)。記錄下當(dāng)時(shí)的情況、你的預(yù)期、實(shí)際結(jié)果積累多了你就能摸清 AI 的脾氣寫出來的技能也越來越準(zhǔn)。這套東西說到底不是讓 AI 變聰明而是讓你自己把那些模糊的、隱性的工作規(guī)范想清楚、寫下來。寫技能的過程其實(shí)是在梳理你自己的工作方法。這個(gè)價(jià)值可能比技能本身還大。