Perplexity內部工程文檔揭示的5個Agent Skills設計反直覺原則，第3個最容易被忽略
整理版優先睇
Perplexity內部文檔揭示5個Agent Skills設計反直覺原則：意圖描述、成本控制、路由觸發、品味注入與反面案例
呢篇文章係由一位13年後端開發經驗嘅作者蒼一整理，佢睇咗Perplexity最近公開嘅內部工程文檔，詳細講解Agent Skills庫嘅設計思路、迭代方法同維護策略。文檔提出咗5個反直覺嘅原則，強調技能文檔唔係寫畀模型嘅說明書，而係要提供模型學唔到嘅判斷同品味。整體結論係：開發者應該將技能設計成「人類經驗嘅載體」，而唔係操作手冊。
第一個原則係「意圖優於指令」：與其列出一串git命令，不如用自然語言描述目標，例如「將指定提交移到一個乾淨嘅分支上」，咁樣模型反而更靈活，唔會喺出錯時卡死。第二個原則係「上下文嘅三層成本結構」：索引層每次對話都佔用約100 token，正文層理想限5000 token，運行層按需加載。設計技能時要考慮呢啲成本，避免浪費。
第三個原則係「描述係路由觸發器」：技能描述應該模擬用戶嘅真實表述，例如「當用戶想確保某個合併請求順利落地時加載」，而唔係列功能。第四個原則係「經驗同品味係模型學唔到嘅」：例如字體規範入面嘅視覺感受，模型可以講參數但判斷唔到邊個字體顯得廉價。第五個原則係「反面案例比正面規則更有效」：維護技能時只增不改，每次出錯就追加反面案例，信息密度更高。另外，新增技能可能影響現有技能表現，所以一定要做回歸測試。
- 結論：技能文檔唔係寫畀模型嘅說明書，而係提供模型學唔到嘅判斷同品味。
- 方法：用「意圖」取代「指令」，描述目標而唔係步驟，畀模型自主決策，靈活應對變化。
- 差異：上下文有三層成本結構（索引、正文、運行），設計技能要考慮token開銷，避免浪費上下文空間。
- 啟發：描述字段係路由觸發器，應該模擬用戶嘅真實表述，而唔係列功能，咁樣模型先會正確觸發。
- 可行動點：維護技能時「只增不改」，追加反面案例比正面規則更有效；新增技能後一定要做回歸測試，防止幹擾。
技能文檔唔係說明書
Perplexity最近公開咗一份內部工程文檔，詳細講咗Agent Skills庫嘅設計思路。文檔開篇引用《Python之禪》，但直接指出呢啲哲學喺寫技能時唔成立——如果一段描述容易寫出嚟，即係模型已經識得，寫咗都係浪費上下文。
如果一段描述很容易寫出來，說明模型早就掌握了呢啲知識
意圖優於指令：用目標代替步驟
用一個代碼合併嘅場景對比：傳統寫法列出git命令序列，Perplexity推薦用自然語言描述意圖，例如「將指定提交移到一個乾淨嘅分支上，衝突時保留原始意圖」。
意圖式描述把決策權交還給模型
後者睇起嚟更模糊，但模型實際表現更好。過於具體嘅指令序列會喺出錯時令模型陷入僵局，而意圖式描述讓模型根據實際情況靈活調整路徑。
上下文嘅三層成本結構
- 1 索引層：每個技能名稱同描述每次對話都佔用約100 token，乘以技能數量同用戶規模，累積開銷好可觀。
- 2 正文層：技能主體理想控制在5000 token以內，一次對話通常加載三到五個技能，成本疊加。冗餘描述會壓縮其他技能嘅可用空間。
- 3 運行層：腳本文件、參考文檔等按需加載，原則上冇上限，因為只有需要時先讀取。
上下文嘅三層成本結構：索引層、正文層、運行層
理解呢個成本結構，先知道點樣取捨——每加一個技能，都係從用戶嘅上下文預算度扣錢。
描述係路由觸發器，唔係功能表
技能嘅描述字段承擔路由觸發功能，模型根據呢段文字決定係咪加載技能。Perplexity要求格式以「當某情況發生時加載」開頭，50詞以內，用用戶實際會講嘅話。
觸發式描述：「當用戶想確保某個合併請求順利落地、或者擔心流水線掛掉時加載」
功能式描述就變咗「監控代碼合併請求嘅狀態」，前者匹配用戶行為，後者描述技能能力。模型路由時匹配關鍵詞密度，覆蓋嘅表述方式越多，觸發成功率越高。
經驗品味同反面案例
Perplexity設計負責人為設計類技能寫咗詳細字體規範，包括用咩字體、避免咩字體，同埋每種字體嘅視覺感受。呢個「感受」係審美判斷，模型可以講Helvetica嘅參數，但判斷唔到佢喺某個場景下係咪顯得廉價。
模型無法判斷字體係咪顯得廉價
維護技能時，Perplexity提出明確迭代原則：只增不改，主要往反面案例區域追加內容。每次模型出錯就加一條反面案例，唔好修改描述或新增規則。
- 只增不改：唔好改原本描述，只喺反面案例區域加新內容。
- 每次出錯就加一條反面案例，唔好寫新規則。
- 新增技能後一定要回歸測試，檢查其他技能有冇被幹擾。
大家好，我係蒼一，做咗13年後端開發，而家探索緊AI編程，由產品到開發嘅全生命週期最佳實踐，如果你有興趣，歡迎關注👇，睇我點樣自我革命。
技能文檔唔係寫畀模型睇嘅說明書
Perplexity最近公開咗一篇內部工程文檔，詳細講咗Agent Skills庫嘅設計思路、迭代方法同維護策略。結論幾乎條條反直覺，但仔細諗返又覺得理所當然。
文檔開頭借用咗《Python之禪》嘅哲學，但呢啲原則喺寫技能嘅時候唔成立。Perplexity嘅工程團隊直接指出：如果一段描述好容易寫得出，就代表模型已經掌握咗呢啲知識，寫佢只係浪費上下文空間。
大多數開發者嘅本能係將技能寫成操作手冊。列出命令、詳述步驟、標註注意事項。問題在於呢啲內容模型本身就會，寫咗冇增量價值，反而溝淡咗真正重要嘅信息，擠佔有限嘅上下文窗口。
意圖優於指令：用目標描述取代步驟清單
用一個代碼合併嘅場景嚟對比。傳統寫法列出具體git命令序列：先log揾提交，再checkout主分支，開新分支，cherry-pick。Perplexity推薦嘅做法係用自然語言描述意圖：將指定提交搬去一個乾淨嘅分支，衝突時保留原始意圖，真係合唔埋就解釋原因。
後者睇起嚟比較模糊，但模型實際表現反而更好。太具體嘅指令序列會喺出錯時令模型陷入僵局。而意圖式描述將決策權交返畀模型，等佢根據實際情況靈活調整路徑。
上下文嘅三層成本結構
1️⃣ 索引層：每次對話都要畀嘅固定成本
每個技能嘅名稱同描述，無論用戶問咩，都會佔用上下文空間。Perplexity畀每個技能嘅預算大約100個token。乘埋技能數量、用戶規模同每日對話次數，累積開銷好嚇人。
2️⃣ 正文層：壓縮前嘅核心負載
技能主體內容理想情況下要控制喺5000 token以內。一次對話通常會同時加載三到五個技能，成本疊加之後好可觀。正文入面嘅冗餘描述唔單止浪費自己嘅空間，仲會壓縮其他技能嘅可用空間。
3️⃣ 運行層：按需加載嘅附屬資源
腳本文件、參考文檔、輸出模板等，只有當模型真係需要嗰陣先會被讀取。呢一層原則上冇上限，因為全部都係按需加載。
描述係路由觸發器，唔係功能說明
技能嘅描述字段負責路由觸發嘅功能。模型會根據呢段文字決定係咪要加載呢個技能。Perplexity嘅格式要求：以「當某情況發生時加載」開頭，控制喺50個詞以內，用用戶實際會講嘅嘢嚟寫。
功能式描述：「監控代碼合併請求嘅狀態，支援睇進度同審查結果。」觸發式描述：「當用戶想確保某個合併請求順利落地，或者擔心流水線出事嗰陣加載。」
前者描述技能能力，後者描述用戶行為。模型喺路由時匹配嘅係用戶輸入入面嘅關鍵詞同埋佢哋嘅密度，覆蓋嘅表達方式越多，技能被正確觸發嘅機率就越高。
經驗同品味係模型學唔到嘅
Perplexity嘅設計負責人為設計類技能寫咗詳細嘅字體規範，包括用邊啲字體、避開邊啲字體，同每種字體帶嚟嘅視覺感受。呢個「感受」係審美判斷，唔係知識條目。
模型可以準確描述Helvetica字體嘅歷史同參數，但判斷唔到呢個字體喺特定場景下會唔會顯得好廉價。技能嘅最大價值唔係教模型做佢已經識嘅嘢，而係將人類大腦入面嗰啲模糊但準確嘅判斷，轉化為模型可用嘅上下文。
反面案例比正面規則更有效
喺技能維護方面，Perplexity提出咗明確嘅迭代原則：只加唔改，主要向反面案例區域追加內容。每次模型出錯就加一條反面案例，唔好修改描述，唔好加新規則。
反面案例直接標記已知嘅死路，喺有限上下文入面傳遞嘅信息密度比正面規則更高。
除此之外仲有一個容易忽略嘅副作用：新增技能可能導致現有技能表現下降。索引層嘅描述喺爭奪模型注意力，兩個描述相似嘅技能會互相干擾。所以每次新增技能之後都要做回歸測試。
最後返到根本判斷標準：如果模型冇呢個技能都做得啱，咁呢個技能就唔需要存在。
如果嫌文章太長、怕之後走失，可以關注下面嘅ima知識號，等呢篇文章成為你嘅知識顧問，隨時隨地等你提問。
知識號入面嘅內容會以筆記形式分享，可以根據大家嘅反饋同實測情況，實時更新，保證最新方案穩定、可用。
【ima 知識庫】
大家好，我是蒼一，一個幹了13年的後端開發，正在探索AI編程，從產品到開發的全生命週期最佳實踐，如果您感興趣，歡迎關注👇，看我如何自我革命。
技能文檔不是寫給模型看的說明書
Perplexity最近公開了一篇內部工程文檔，詳細闡述了Agent Skills庫的設計思路、迭代方法和維護策略。結論幾乎條條反直覺，但仔細推敲後又覺得理所當然。
文檔開篇借用了《Python之禪》的哲學，但這些原則在編寫技能時並不成立。Perplexity的工程團隊直接指出：如果一段描述很容易寫出來，說明模型早就掌握了這些知識，寫它只是在浪費上下文空間。
大多數開發者的本能是把技能寫成操作手冊。羅列命令、詳述步驟、標註注意事項。問題在於這些內容模型本身就會，寫了沒有增量價值，反而稀釋掉真正重要的信息，擠佔有限的上下文窗口。
意圖優於指令：用目標描述替代步驟清單
用一個代碼合併的場景來對比。傳統寫法列出具體git命令序列：先log找提交，再checkout主分支，建新分支，cherry-pick。Perplexity推薦的做法是用自然語言描述意圖：把指定提交移到一個乾淨的分支上，衝突時保留原始意圖，實在合不進去就說明原因。
後者看起來更模糊，但模型實際表現反而更好。過於具體的指令序列會在出錯時讓模型陷入僵局。而意圖式描述把決策權交還給模型，讓它根據實際情況靈活調整路徑。
上下文的三層成本結構
1️⃣ 索引層：每次對話都在付的固定成本
每個技能的名稱和描述，無論用戶問了什麼，都佔用上下文空間。Perplexity給每個技能的預算約100個token。乘以技能數量、用戶規模和每日對話次數，累積開銷非常可觀。
2️⃣ 正文層：壓縮前的核心負載
技能主體內容理想情況下控制在5000 token以內。一次對話通常同時加載三到五個技能，成本疊加後相當可觀。正文裏的冗餘描述不僅浪費自身空間，還會壓縮其他技能的可用餘地。
3️⃣ 運行層：按需加載的附屬資源
腳本文件、參考文檔、輸出模板等，只有在模型真正需要時才被讀取。這一層原則上沒有上限，因為都是按需加載。
描述是路由觸發器，不是功能說明
技能的描述字段承擔路由觸發的功能。模型根據這段文字決定是否加載該技能。Perplexity的格式要求：以"當某情況發生時加載"開頭，控制在50詞以內，用用戶實際會說的話來寫。
功能式描述："監控代碼合併請求的狀態，支持查看進度和審查結果。"觸發式描述："當用戶想確保某個合併請求順利落地、或者擔心流水線掛掉時加載。"
前者描述技能能力，後者描述用戶行為。模型在路由時匹配的是用戶輸入中的關鍵詞及其密度，覆蓋的表述方式越多，技能被正確觸發的概率越高。
經驗和品味是模型學不到的
Perplexity的設計負責人為設計類技能撰寫了詳細的字體規範，包括使用哪些字體、避免哪些字體，以及每種字體帶來的視覺感受。這個"感受"是審美判斷，不是知識條目。
模型可以準確描述Helvetica字體的歷史和參數，但無法判斷這個字體在特定場景下是否顯得廉價。技能的最大價值不在於教模型做它已經會的事，而在於把人類大腦中那些模糊但準確的判斷，轉化為模型可用的上下文。
反面案例比正面規則更有效
在技能維護方面，Perplexity提出了明確的迭代原則：只增不改，主要往反面案例區域追加內容。每次模型出錯就追加一條反面案例，不要修改描述，不要新增規則。
反面案例直接標記已知的死路，在有限上下文中傳遞的信息密度比正面規則更高。
此外還有一個容易被忽略的副作用：新增技能可能導致已有技能表現下降。索引層的描述在爭奪模型注意力，兩個描述相近的技能會產生干擾。因此每次新增技能後都需要回歸測試。
最後回到根本判斷標準：如果模型在沒有這個技能的情況下也能做對，那這個技能就不需要存在。
如果嫌文章太長、怕後面走丟，可以關注下面的ima知識號，讓這篇文章成為你的知識顧問，隨時隨地等候你的提問。
知識號中內容會以筆記形式分享，可以根據大家反饋和實測情況，實時更新，保證最新方案的穩定、可用。
【ima 知識庫】