Perplexity 內部規範公開：Agent Skill 設計迭代維護的 5 個步驟、4 類評測、3 條紅線

作者：AI 啓蒙小夥伴
日期：2026年5月10日 上午1:40
來源：WeChat 原文

✦整理版優先睇

速讀 5 個重點 高亮

Perplexity 公開內部 Agent Skill 設計規範：核心係「寫 Skill 唔係寫代碼」，而係為模型構建上下文，重點喺描述路由同 Gotchas 漸進維護。

整理版摘要

Perplexity Agents 團隊最近公開咗佢哋內部構建 Agent Skills 嘅設計規範、迭代原則同維護之道。呢篇文章係由團隊內部規範整理出嚟嘅公開版，核心論點好反直覺：寫 Skill 唔係寫代碼，而係為模型構建上下文。工程師將寫代碼嘅本能直接套落 Skill 度，幾乎一定會失敗。

作者用「Zen of Python vs. Zen of Skills」做對照，點明思維差異。例如 Python 信條話「Simple is better than complex」，但 Skill 信條係「複雜性係特性」；「Explicit is better than implicit」對應「激活靠隱式模式匹配」；「Sparse is better than dense」對應「每 token 都要榨出最大信號」。核心範式轉變係：Skill 係文件夾，唔係代碼文件；描述係路由觸發器，唔係文檔；Gotchas 係最高價值內容，而唔係特例。

整篇文章嘅結論係：Skill 設計本質係上下文經濟學，每一句話都在同其他 Skill 爭注意力預算。先寫 Evals，後寫 Skill；負例同禁止誤載同等重要。Description 係最難嗰行，要以「Load when...」起手。維護靠 Gotchas 飛輪，從薄起步、隨失敗生長。任何按日/周/季重複嘅工作流都係潛在 Skill。

  • 核心範式轉變：寫 Skill 唔等於寫代碼，要由「指令序列」轉向「意圖陳述＋負例」。
  • 路由優先：Description 係隱式分類器輸入，必須以「Load when...」開頭，≤50 詞準確描述用戶意圖。
  • 構建順序不可調：Step0 先寫 Evals（真實查詢、已知失敗、鄰域混淆），然後先寫 Description，再寫 Body，最後層次化拆文件。
  • Gotchas 係最高價值：從薄起步，Agent 犯錯就加 gotcha，誤加載就收緊描述，呢個飛輪係從 80/20 走向 99.9% 嘅關鍵。
  • 每加一個 Skill 都係一種税：新增 Skill 會悄無聲息地降級現有 Skill，要避免模型已會、重複 system prompt、變化太快嘅 Skill。
值得記低
連結 research.perplexity.ai

Designing, Refining, and Maintaining Agent Skills at Perplexity

Perplexity Agents 團隊內部規範公開版，原文連結。

開啟
流程

Skill 結構模板

標準目錄結構：SKILL.md + scripts/ + references/ + assets/ + config.json。SKILL.md 放主 body，scripts/ 放確定性邏輯，references/ 放條件加載嘅重文檔，assets/ 放輸出模板，config.json 放首次運行配置。

留作參考
整理重點

核心範式轉變：Skill 唔係代碼

Perplexity 團隊強調，寫 Skill 唔係寫代碼，而係為模型構建上下文。工程師成日將寫代碼嘅本能直接套落 Skill 度，結果幾乎一定會失敗。

作者用「Zen of Python vs. Zen of Skills」做對照：Python 講求「Simple is better than complex」，但 Skill 嘅信條係「複雜性係特性」；「Explicit is better than implicit」對應 Skill 嘅「激活靠隱式模式匹配」；「Sparse is better than dense」對應「每 token 都要榨出最大信號」。呢個範式轉變係成篇文嘅基石。

整理重點

Skill 嘅四重定義

Perplexity 將 Skill 定義為四個層面：目錄、格式、可調用、漸進式。每一個層面都有特定嘅約束同最佳實踐。

  • 目錄結構：必須有 SKILL.md + scripts/ + references/ + assets/ + config.json。複雜領域可以用多級層次，但層次本身有代價，需要導航工具（例如 quick reference）來對沖間接性。
  • 格式：frontmatter 必須有 name（小寫、連字符、與目錄同名）同 description。Description 係路由觸發器，唔係文檔。常見錯誤係寫「This Skill does X」，正確寫法係「Load when …」。depends 用於級聯依賴。
  • 可調用：load_skill() 會拷貝目錄入沙箱，遞歸裝載 depends 中嘅依賴，剝離 frontmatter，僅暴露 body 同附屬文件。
  • 漸進式成本模型：Index（所有 Skill 嘅 name+description）~100 tokens/Skill，每次會話永遠付費；Load（SKILL.md body）~5,000 tokens，一次加載持續佔用；Runtime（scripts/references/子 Skill）無上界，僅模型實際讀取時先付費。Index 係「奢侈品櫃枱」，Runtime 係「無限倉庫」。
整理重點

構建五步法（順序不可調）

Perplexity 提出咗五個嚴格排序嘅步驟，順序不可調，第一步係寫評測。

  1. 1 Step 0 — 先寫 Evals：收集真實查詢、已知失敗、鄰域混淆。負例往往比正例更重要。
  2. 2 Step 1 — 寫 Description（最難嘅一行）：以 Load when… 開頭，≤50 詞描述用戶意圖，用真實抱怨語（例如「babysit」、「watch CI」）。唔好總結工作流，唯一目標係路由準確。
  3. 3 Step 2 — 寫 Body：跳過顯而易見嘅內容，唔好羅列命令序列；用意圖陳述代替過程腳本。重點放 gotchas 同負例。「沒有呢句話，Agent 會做錯嗎？」答否即刪。
  4. 4 Step 3 — 用層次結構：將條件性、重型、模板類內容拆到 scripts/（確定性邏輯）、references/（條件加載重文檔）、assets/（輸出模板）、config.json（首次運行配置）。
  5. 5 Step 4 — 迭代：用一個評測集做小詞級調優，描述裏一字之差就能引發路由級聯。
  6. 6 Step 5 — Ship：之後進入維護階段，靠 Gotchas 飛輪生長。
整理重點

評測套件與維護之道

評測套件分四類，每類都係維護嘅必要組成部分。

  • 加載評測：精度、召回、禁止加載（避免污染鄰域）。
  • 漸進加載評測：Skill 加載後係咪正確讀取附屬文件（例如 FORMATTING.md）。
  • 端到端任務評測：跑完整 agent loop，用 LLM judge 按 rubric 打分。
  • 跨模型評測：喺 GPT / Opus / Sonnet 上同時跑，行為差異顯著。

作者重複提醒：Every Skill is a tax。三類典型濫用：模型已經會嘅（例如一串 git 命令）、重複 system prompt 嘅、變化太快嘅（如遠端 MCP 工具頻繁更新）。另外，新增 Skill 會悄無聲息地降級現有 Skill —— 呢個係默認風險，唔係邊角情況。

Perplexity Agents 團隊最新發佈咗團隊內部建立同迭代 Agent Skills 嘅設計規範、迭代原則同埋維護方法。

Designing, Refining, and Maintaining Agent Skills at Perplexity

https://research.perplexity.ai/articles/designing-refining-and-maintaining-agent-skills-at-perplexity

呢篇文章係 Perplexity Agents 團隊嘅內部規範公開版，核心論點好反直覺：寫 Skill 唔係寫代碼，而係為模型建立上下文將工程師寫代碼嘅本能直接套用喺 Skill 上面，幾乎一定會失敗。

核心範式轉變：Skill 唔等於代碼

作者用「Zen of Python vs. Zen of Skills」做對照，點明思維差異：

Python 嘅信條Skill 嘅反信條
Simple is better than complexSkill 係文件夾，複雜性係特性
Explicit is better than implicit激活靠隱式模式匹配 + 漸進披露
Sparse is better than dense每個 token 都要榨出最大信號
特例唔應該破壞規則Gotchas（陷阱）先至係最高價值內容
容易解釋嘅實現係好實現容易解釋嘅，模型已經識咗 → 刪咗佢

Skill 嘅四重定義

1. Skill 係目錄（唔係單一檔案）

  • 標準結構：SKILL.md + scripts/ + references/ + assets/ + config.json
  • 複雜領域用多級層次例子：美國税法有 1945 個 IRC 條款，扁平加載比唔加載效果更差；分三級嵌套之後先至可用。
  • 但係層次本身有代價，需要導航工具（quick reference、自定義檢索）嚟對沖間接性。

2. Skill 係格式

  • frontmatter 必須要有 name（小寫、連字符、同目錄同名）同 description。
  • description 係路由觸發器，唔係文檔常見錯誤：寫 "This Skill does X"；正確寫法係 "Load when …"。
  • depends: 用嚟做級聯依賴；運行時元數據可以用輔助 JSON/YAML 隔離，避免污染上下文。

3. Skill 係可以調用嘅

加載流程：

  1. load_skill()
  2. 複製目錄入沙箱
  3. 遞迴裝載 depends: 嘅依賴
  4. 剝離 frontmatter，淨係暴露 body 同附屬檔案

4. Skill 係漸進式嘅（最重要嘅成本模型）

層級內容預算幾時消耗 token 成本
Index所有 Skill 嘅 name+description~100 tokens/Skill每次會話、每個用戶、永久
LoadSKILL.md body~5,000 tokens一次加載，會話入面持續佔用
Runtimescripts / references / 子 Skill無上界得模型實際讀取嗰陣

→ 越靠上嘅層，每個字越貴。Index 係「奢侈品櫃枱」，Runtime 係「無限倉庫」。

幾時不需要 Skill

作者不斷強調 "Every Skill is a tax"。三類典型濫用：

  • 模型已經識嘅寫一串 git 命令 → 係好文檔，係壞 Skill。
  • 重複 system prompt 嘅通用知識應該入全局上下文，唔應該行條件加載。
  • 變化太快嘅遠端 MCP 工具版本成日變 → Skill 會漂移導致幻覺。

判斷單句應唔應該留嘅尺子：「冇呢句話，Agent 會做錯嗎？」 答冇就刪。

引用 Pascal：「呢封信寫得長，係因為我冇時間寫短。」

寫短 Skill 好難；寫得快嘅 Skill 大概率有問題。仲引用咗一篇研究：LLM 自生成嘅 Skill 平均冇收益，因為模型無法可靠咁將「自己消費有用嘅程序性知識」寫出嚟。

建立五步法（順序唔可以調）

Step 0 — 先寫 Evals

來源：真實查詢、已知失敗、鄰域混淆。負例往往比正例更加重要。

Step 1 — 寫 Description（最難嗰一行）

  • 以 Load when… 開頭，≤ 50 個詞
  • 描述用戶意圖（用真實抱怨語：「babysit」、「watch CI」、「make sure this lands」）
  • 唔好總結工作流
  • 唯一目標：路由準確，最小化對其他 Skill 嘅回歸影響

Step 2 — 寫 Body

跳過顯然嘅；唔好列舉命令序列；用意圖陳述代替過程腳本。

  • ❌ git log; git checkout main; git checkout -b; git cherry-pick
  • ✅ 「Cherry-pick 到乾淨分支，保留意圖解決衝突，落唔到嗰陣說明原因。」

重點放 gotchas / 負例。

Step 3 — 用層次結構

條件性、重型、模板類內容拆到：

  • scripts/ — 確定性邏輯
  • references/ — 條件加載嘅重文檔
  • assets/ — 輸出模板
  • config.json — 首次運行配置

Step 4 — 迭代

用一個評測集做小詞級調優（描述嗰度一字之差就能引發路由級聯）。

Step 5 — 出街

維護：Gotchas 飛輪

Skill 係淨係追加為主的：

  • Agent 錯咗 → 加 gotcha
  • 誤加載 → 收緊描述 + 加負例
  • 應該加載但冇加載 → 加關鍵詞 + 加正例
  • system prompt 變咗 → 檢查衝突同重複

從 80/20 走向 99.9% 嘅過程，幾乎全靠 gotcha 列表生長，而不是改描述或者加更長嘅指令。一旦 PR 改描述但冇附 evals，就已經走偏咗。

評測套件分四類

  1. 加載評測：精度、召回、禁止加載（避免污染鄰域）
  2. 漸進加載評測：Skill 加載後係咪正確讀取附屬檔案（例如 FORMATTING.md）
  3. 端到端任務評測：跑完整 agent loop，用 LLM judge 按 rubric 打分
  4. 跨模型評測：喺 GPT / Opus / Sonnet 上同步跑（行為差異顯著）

關鍵 takeaway

  1. 先 evals，後 Skill負例同「禁止誤載」同正例同等重要。
  2. Description 係最難嘅一行，以 Load when… 起手。
  3. Gotchas 係最高價值內容由薄起步、隨失敗生長。
  4. Action at a distance新增 Skill 會靜靜雞降級現有 Skill —— 呢個係默認風險，唔係邊角情況。
  5. 寫 Skill 嘅能力本身喺度複利增長；任何按日/星期/季度重複嘅工作流，都係潛在 Skill。

個人提煉嘅三條「最反直覺」要點

  1. 上下文係稀缺資源，唔係代碼空間Skill 設計本質係上下文經濟學：每一句話都喺度同其他 Skill 搶注意力預算。
  2. 路由唔等於文檔寫 Skill 嘅人最常犯嘅錯，就係將 description 寫成 README —— 佢實際係一個隱式嘅分類器輸入。
  3. 唔好規定路徑，規定意圖指令越具體越脆弱；模型喺面對「目標 ＋ 約束」嗰陣比面對「步驟清單」表現更好，尤其係異常路徑上面。

如果你正在建立一個 Skill 庫，建議將呢篇當成 checklist 反覆對照，特別係 Step 0（先寫 evals）同 description 嘅 Load when… 紀律 —— 呢兩點最容易被工程直覺繞過，但回報最高。

相關資源推薦

我開源咗復刻網站設計做 DESIGN.md 嘅 Skill，讓你嘅 Agent 完美復刻所有網站！

點樣寫好 Skill ？OpenAI、Anthropic 同 Sentry 嘅 Skill-Creator 對比結合：由快速原型到工程化工作流持續迭代

測試驅動嘅 Agent Skills 工程化建立迭代指南：基於 Anthropic/OpenAI Skill Creator 官方實踐嘅落地方法論


    Perplexity Agents 團隊最新發布了團隊內部構建迭代 Agent Skills 的設計規範、迭代原則和維護之道。

    Designing, Refining, and Maintaining Agent Skills at Perplexity

    https://research.perplexity.ai/articles/designing-refining-and-maintaining-agent-skills-at-perplexity

    這篇文章是 Perplexity Agents 團隊的內部規範公開版，核心論點很反直覺：寫 Skill 不是寫代碼，而是為模型構建上下文。把工程師寫代碼的本能直接套到 Skill 上，幾乎一定會失敗。

    核心範式轉變：Skill ≠ 代碼

    作者用「Zen of Python vs. Zen of Skills」對照，點明思維差異：

    Python 信條Skill 反信條
    Simple is better than complexSkill 是文件夾，複雜性是特性
    Explicit is better than implicit激活靠隱式模式匹配 + 漸進披露
    Sparse is better than dense每 token 都要榨出最大信號
    特例不應破壞規則Gotchas（坑）才是最高價值內容
    容易解釋的實現是好實現容易解釋的，模型已經會了 → 刪掉

    Skill 的四重定義

    1. Skill 是目錄（不是單文件）

    • 標準結構：SKILL.md + scripts/ + references/ + assets/ + config.json
    • 複雜領域用多級層次。例：美國税法有 1945 個 IRC 條款，扁平加載比不加載效果更差；分三級嵌套後才可用。
    • 但層次本身有代價，需要導航工具（quick reference、自定義檢索）來對沖間接性。

    2. Skill 是格式

    • frontmatter 必須有 name（小寫、連字符、與目錄同名）和 description。
    • description 是路由觸發器，不是文檔。常見錯誤：寫 "This Skill does X"；正確寫法是 "Load when …"。
    • depends: 用於級聯依賴；運行時元數據可用輔助 JSON/YAML 隔離，避免污染上下文。

    3. Skill 是可調用的

    加載流程：

    1. load_skill()
    2. 拷貝目錄入沙箱
    3. 遞歸裝載 depends: 中的依賴
    4. 剝離 frontmatter，僅暴露 body 與附屬文件

    4. Skill 是漸進式的（最重要的成本模型）

    層級內容預算何時付費
    Index所有 Skill 的 name+description~100 tokens/Skill每次會話、每個用戶、永遠
    LoadSKILL.md body~5,000 tokens一次加載，會話內持續佔用
    Runtimescripts / references / 子 Skill無上界僅模型實際讀取時

    → 越靠上的層，每個字越貴。Index 是「奢侈品櫃枱」，Runtime 是「無限倉庫」。

    什麼時候不需要 Skill

    作者反覆強調 "Every Skill is a tax"。三類典型濫用：

    • 模型已會的：寫一串 git 命令 → 是好文檔，是壞 Skill。
    • 重複 system prompt 的：通用知識應進全局上下文，不該走條件加載。
    • 變化太快的：遠端 MCP 工具版本頻繁變 → Skill 會漂移導致幻覺。

    判斷單句是否該留的尺子："沒有這句話，Agent 會做錯嗎？" 答否即刪。

    引用 Pascal：「這封信寫得長，是因為我沒時間寫短。」

    寫短 Skill 很難；寫得快的 Skill 大概率有問題。還引了一篇研究：LLM 自生成的 Skill 平均無收益，因為模型無法可靠地把"自己消費有用的程序性知識"寫出來。

    構建五步法（順序不可調）

    Step 0 — 先寫 Evals

    來源：真實查詢、已知失敗、鄰域混淆。負例往往比正例更重要。

    Step 1 — 寫 Description（最難的一行）

    • 以 Load when… 開頭，≤ 50 詞
    • 描述用戶意圖（用真實抱怨語："babysit"、"watch CI"、"make sure this lands"）
    • 不要總結工作流
    • 唯一目標：路由準確，最小化對其他 Skill 的迴歸影響

    Step 2 — 寫 Body

    跳過顯然的；不要羅列命令序列；用意圖陳述代替過程腳本。

    • ❌ git log; git checkout main; git checkout -b; git cherry-pick
    • ✅ "Cherry-pick 到乾淨分支，保留意圖解決衝突，落不下時說明原因。"

    重點放 gotchas / 負例。

    Step 3 — 用層次結構

    條件性、重型、模板類內容拆到：

    • scripts/ — 確定性邏輯
    • references/ — 條件加載的重文檔
    • assets/ — 輸出模板
    • config.json — 首次運行配置

    Step 4 — 迭代

    用一個評測集做小詞級調優（描述裏一字之差就能引發路由級聯）。

    Step 5 — Ship

    維護：Gotchas 飛輪

    Skill 是僅追加為主的：

    • Agent 錯了 → 加 gotcha
    • 誤加載 → 收緊描述 + 加負例
    • 該加載沒加載 → 加關鍵詞 + 加正例
    • system prompt 變了 → 檢查衝突與重複

    從 80/20 走向 99.9% 的過程，幾乎全靠 gotcha 列表生長，而不是改描述或加更長的指令。一旦 PR 改描述卻沒附 evals，"已經走偏了"。

    評測套件分四類

    1. 加載評測：精度、召回、禁止加載（避免污染鄰域）
    2. 漸進加載評測：Skill 加載後是否正確讀取附屬文件（如 FORMATTING.md）
    3. 端到端任務評測：跑完整 agent loop，用 LLM judge 按 rubric 打分
    4. 跨模型評測：在 GPT / Opus / Sonnet 上同時跑（行為差異顯著）

    關鍵 takeaway

    1. 先 evals，後 Skill；負例與"禁止誤載"與正例同等重要。
    2. Description 是最難的一行，以 Load when… 起手。
    3. Gotchas 是最高價值內容，從薄起步、隨失敗生長。
    4. Action at a distance：新增 Skill 會悄無聲息地降級現有 Skill —— 這是默認風險，不是邊角情況。
    5. 寫 Skill 的能力本身在複利增長；任何按日/周/季重複的工作流，都是潛在 Skill。

    個人提煉的三條「最反直覺」要點

    1. 上下文是稀缺資源，不是代碼空間。Skill 設計本質是上下文經濟學：每一句話都在和其他 Skill 搶注意力預算。
    2. 路由 ≠ 文檔。寫 Skill 的人最常犯的錯，是把 description 寫成 README —— 它實際是個隱式的分類器輸入。
    3. 不要規定路徑，規定意圖。指令越具體越脆弱；模型在面對"目標 + 約束"時比面對"步驟清單"表現更好，尤其是異常路徑上。

    如果你正在搭一個 Skill 庫，建議把這篇當成 checklist 反覆對照，特別是 Step 0（先寫 evals）和 description 的 Load when… 紀律 —— 這兩點最容易被工程直覺繞開，但回報最高。

    相關資源推薦

    我開源了復刻網站設計為 DESIGN.md 的 Skill，讓你的 Agent 完美復刻所有網站！

    怎麼寫好 Skill ？OpenAI、Anthropic 與 Sentry 的 Skill-Creator 對比結合：從快速原型到工程化工作流持續迭代

    測試驅動的 Agent Skills 工程化構建迭代指南：基於 Anthropic/OpenAI Skill Creator 官方實踐的落地方法論