justinramos101/agent-skill-kit

Agent DX

一個AI 代理即開發者的表面的開發者體驗（DX）— 代理用以建構或行動的 SDK、工具、結構化輸出、錯誤封包或遙測。來源資訊位於 skill.json；此檔案僅供執行時期路由使用。

產出： 一份 change-plan.md（DO）、一份 audit-report.md 加上 findings-ledger + workflow-state（若為追蹤狀態，REVIEW）、或一份 design-doc.md / refactor-runbook.md / explanation.md（DESIGN）。

核心原則

代理獨自、以機器速度消費表面，沒有任何工具提示可依賴。 因此，任何 SDK、工具、錯誤或跨度（span）的門檻在於：一個隨機消費者能否解析它、從中恢復，且不受傷害：型別化合約勝過散文；恢復是設計出來的，不是期望出來的；信任邊界預設關閉。它位於 dx-audit / dx-design 所擁有的 HTTP-client 層之上，不會取代該層。

啟用

• 裸調用 ("use agent-dx", "start")：顯示一個精簡選單：模式選擇（引導式 / 自動駕駛 / 拷問我？）以及路由器的編號意圖。等待。不檢查檔案、不進行網路呼叫、不寫入。
• 具體調用 帶有意圖與可推斷的表面：直接跳到步驟 3。
• 模糊調用：詢問一次 — 例如，「您要審計的是 SDK、工具綱要、結構化輸出封包，還是遙測表面？」 或 「這是合約/恢復審查還是信任邊界審計？」

工作流程

1. 選擇意圖。 載入 references/intent-router.csv；比對至 do、review 或 design。模糊 → 詢問一次。
2. 選擇表面。 載入 references/intents/<intent>.csv；比對一個或多個 sdk-design、tools-and-mcp、structured-output、errors-and-retry、sdk-telemetry — 或 all 進行 REVIEW 扇出。模糊 → 以選單詢問一次。
3. 載入接地情境。 僅載入所選行的 playbook 及其 core_refs。不載入其他 playbook（review/all 行不帶任何資料 — 每個表面代理會自行載入；見步驟 6）。
4. 識別目標人物 來自 references/core/personas.md。
5. 然後根據專案規模校準（REVIEW / DESIGN）參照 references/calibration.md：低於關鍵負載時，縮小範圍，將相同機制的缺口合併為一個系統性發現，並拆分現階段（Now） 與未來（Later，隨著增長）。層級影響產出，而非嚴重性。
6. 並行派遣透鏡（REVIEW 預設，允許時）：all 時每個表面一個代理；否則為以下三個透鏡。若無委派基本元素則降為序列執行。
7. 應用 playbook。 使用標記了意圖的啟發式規則。對於 REVIEW，為每個表面評分 0–10（references/core/score-rubric.md）；綜合透鏡發現，保留分歧作為開放問題。套用嚴重性與穩定的 AGENT-DX-<surface>-NNN ID（references/core/severity-rubric.md）：AGENT-DX-SDK、AGENT-DX-TOOL、AGENT-DX-OUT、AGENT-DX-ERR、AGENT-DX-TEL。
8. 產出。 DO → templates/change-plan.md。REVIEW → templates/audit-report.md。DESIGN → templates/design-doc.md（形狀）、templates/refactor-runbook.md（序列化強化步驟）、或 templates/explanation.md（解釋原則）。
9. 建立、恢復或關閉追蹤狀態（REVIEW）。對於有 7 個以上發現、任何嚴重性 3–4 的審計，或收到儲存/追蹤/關閉請求時，載入 references/trackable-findings.md。如果請求指定了已有的 ledger、workflow-state、PR 或 AGENT-DX-* ID，先讀取已儲存狀態；只在每個驗證規則通過後更新狀態。否則在 docs/audits/agent-dx-findings-ledger-<YYYY-MM-DD>-<scope-slug>.md 撰寫 ledger，並在 docs/audits/agent-dx-workflow-state-<YYYY-MM-DD>-<scope-slug>.json 撰寫 workflow 狀態（若 docs/audits/ 無法寫入則回退至 audit-artifacts/agent-dx-...）。報告兩個路徑；路線圖、問題與非追蹤編輯保持選擇加入。

方向錯誤？ 如果使用者表示這不是他們的意思，請回到步驟 1（選擇意圖）— 不要在錯誤方向進行修補。重新陳述更正後的理解並重新規劃。

模式

引導式草稿（預設）、自動駕駛、拷問我 — 請見 references/modes.md。在裸調用時提供；在具體調用時預設為引導式草稿。

產出要求

每個產出都需命名意圖、表面、人物、所應用的 playbook 以及來自 skill.json 的接地來源；REVIEW 需為每個發現添加嚴重性 + 驗證以及專案層級。請明確列出您刻意不加入的代理可消費性保證（YAGNI），而不只是您有加入的。

子代理派遣

REVIEW 預設，當委派被允許時；跳過小型或機密性工作。並行產出三個透鏡 — 合約與綱要（contract-and-schema）（來自程式碼的型別綱要、穩定的錯誤封包、驗證過的輸出）、代理恢復（agent-recovery）（停止+驗證、重試形狀的錯誤、語義重試、有界迴圈）、信任與隔離（trust-and-isolation）（工具後設資料注入、護欄檢查點、憑證牆、內容遮蔽）— 依據 references/subagent-dispatch.md，然後綜合，按嚴重性排序。

參考映射

• references/intent-router.csv + references/intents/<intent>.csv — 兩個路由層。
• references/playbooks/<surface>.md — sdk-design、tools-and-mcp、structured-output、errors-and-retry、sdk-telemetry。
• references/subagent-dispatch.md — 三個透鏡提示與綜合。
• references/core/*.md — 嚴重性、評分、人物、詞彙表。
• references/{calibration,trackable-findings,modes}.md — 共享（符號連結）。
• templates/*.md — change-plan、audit-report、design-doc、refactor-runbook、explanation，加上共享的追蹤產出。
• evals/、skill.json — 閘門與來源。