使用手冊

第 01 期 · 開源 AI Agent / 工程實務

讓 AI agent 照資深工程師的流程做事。

Addy Osmani 開源的 Agent Skills 是 MIT 授權的生產級 AI agent 技能包:8 個斜線指令、24 個技能、4 個專家 persona,把 Google 工程實務(Hyrum's Law、測試金字塔、trunk-based)編進 DEFINE→PLAN→BUILD→VERIFY→REVIEW→SHIP 工作流。本手冊涵蓋安裝、技能總覽、設計原則與實戰示範。

Agent Skills 是 Google 工程師 Addy Osmani 開源、MIT 授權的生產級 AI agent 技能包,把資深工程師建構軟體時的工作流、品質關卡與最佳實務打包成 agent 會穩定遵循的步驟。8 個斜線指令對應開發生命週期,24 個技能各自是帶步驟、驗證關卡與「反合理化」表格的結構化工作流,另含 4 個專家 persona 與 6 份參考清單。本手冊涵蓋安裝、技能總覽、設計原則與一段實戰示範。

addyosmani/agent-skills
星標
—
分支
—
授權
—
資料截至
—
閱讀時間
9 分
更新日期
開啟原始報告
結構化技能
24
斜線指令
8
專家 Persona
4
開源授權
MIT
本頁章節

01這是什麼

把工程紀律編進 agent 的工作流。

Agent Skills 由 Google 工程師 Addy Osmani 開源,定位是「給 AI coding agent 的生產級工程技能」。它要解決的問題很明確:AI agent 預設走最短路徑,常常跳過寫規格、寫測試、做安全審查這些讓軟體可靠的步驟。Agent Skills 給 agent 一套結構化工作流,把資深工程師帶進生產環境的那種紀律強加進去。

每個技能不是給 agent「讀」的參考文件,而是給它「照著走」的流程:有步驟、有檢查點、有退出條件。技能彼此會依工作內容自動啟用——設計 API 觸發 api-and-interface-design、做 UI 觸發 frontend-ui-engineering。8 個斜線指令是入口,對應 DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP 六個階段。

技能裡編進的是 Google 工程文化的具體實務,而非抽象原則:API 設計的 Hyrum's Law、測試的 Beyoncé Rule 與測試金字塔(80/15/5)、code review 的變更大小(約 100 行)與審查速度規範、簡化的 Chesterton's Fence、git 的 trunk-based development、CI/CD 的 Shift Left 與 feature flag,以及一個把程式視為負債的專門 deprecation 技能。出處是《Software Engineering at Google》與 Google 的 engineering practices guide。

  1. Define

  2. Plan

  3. Build

  4. Verify

  5. Review

  6. Ship

AI coding agent 預設走最短路徑—— 而那往往代表跳過規格、測試與安全審查。

— 依官方 README「Why Agent Skills?」段落

02安裝

兩行裝進 Claude Code, 或任何 agent。

官方推薦 Claude Code,透過 plugin marketplace 兩行安裝:

bash
/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

# SSH 錯誤?marketplace 預設用 SSH clone。沒設 SSH key 就改用完整 HTTPS URL:
/plugin marketplace add https://github.com/addyosmani/agent-skills.git

其他 agent:一行或一個檔

技能本體是純 Markdown,任何接受 system prompt 或 instruction 檔的 agent 都能用。常見 host 安裝方式:

工具安裝方式
Antigravity CLIagy plugin install https://github.com/addyosmani/agent-skills.git
Gemini CLIgemini skills install https://github.com/addyosmani/agent-skills.git --path skills
Cursor把任一 SKILL.md 複製進 .cursor/rules/,或引用整個 skills/ 目錄
Windsurf把技能內容加進 Windsurf rules 設定
OpenCode透過 AGENTS.md 與 skill 工具做 agent 驅動執行
Kiro IDE / CLI技能放在 .kiro/skills/(專案或全域層級),也支援 AGENTS.md
GitHub Copilot用 agents/ 作 persona,技能內容放 .github/copilot-instructions.md
Codex / 其他 agent技能是純 Markdown,任何吃 system prompt 或 instruction 檔的 agent 都能用

03能力總覽

8 個指令, 24 個技能。

8 個斜線指令是入口,各自會自動啟用對應的技能。下面先列指令,再用一張表把 24 個技能依生命週期分組。指令是手動入口,技能則會依你正在做的事自動觸發。

Define · 01

/spec

定義要做什麼

原則:先有規格再寫 code。寫一份涵蓋目標、結構、程式風格、測試與邊界的 PRD。

Plan · 02

/plan

規劃怎麼做

原則:小而原子的任務。把規格拆成有驗收條件、依序排好相依的可實作單元。

Build · 03

/build

逐片建構

原則:一次一片。薄垂直切片,實作→測試→驗證→提交。/build auto 核准一次後自動跑完全部任務。

Verify · 04

/test

證明它能動

原則:測試即證據。Red-Green-Refactor、測試金字塔、瀏覽器測試,以實際通過為憑。

Review · 05

/review

合併前審查

原則:改善程式健康度。五軸審查、變更大小約 100 行、嚴重度標籤(Nit / Optional / FYI)。

Review · 06

/webperf

Web 效能稽核

原則:先量再優化。Core Web Vitals 稽核,有 Quick / Deep 模式與「指標誠實」規則,由 web-performance-auditor persona 執行。

Review · 07

/code-simplify

簡化程式

原則:清楚勝過聰明。Chesterton's Fence、Rule of 500,在不改行為的前提下降低複雜度。

Ship · 08

/ship

上線部署

原則:更快即更安全。上線前檢查清單、feature flag 生命週期、分階段 rollout 與回滾程序。

24 個技能,依生命週期分組

指令是入口,底下是完整的 24 個技能(23 個生命週期技能 + 1 個 meta 技能)。每個都能直接引用。

階段技能
Metausing-agent-skills——把工作對應到正確技能,定義共用操作規則
Defineinterview-me · idea-refine · spec-driven-development
Planplanning-and-task-breakdown
Buildincremental-implementation · test-driven-development · context-engineering · source-driven-development · doubt-driven-development · frontend-ui-engineering · api-and-interface-design
Verifybrowser-testing-with-devtools · debugging-and-error-recovery
Reviewcode-review-and-quality · code-simplification · security-and-hardening · performance-optimization
Shipgit-workflow-and-versioning · ci-cd-and-automation · deprecation-and-migration · documentation-and-adrs · observability-and-instrumentation · shipping-and-launch

04設計原則與用法

為什麼它逼你照流程走。

以下八條全部來自官方 README 與 docs,說明這套技能的設計選擇與正確用法。每張卡標注出處段落。

是流程,不是文件

技能是 agent 照著做的工作流,不是它讀的參考文件。每個技能都有步驟、檢查點與退出條件。設計時優先放可執行步驟,而非說明性散文。

來源 · 官方 README「How Skills Work」

反合理化表格擋掉偷懶

每個技能內建一張表,列出 agent 常用來跳過步驟的藉口(例如「測試之後再補」)與對應的反駁。這是它逼流程走完的關鍵機制。

來源 · 官方 README「Key design choices」

驗證不可妥協

每個技能都以證據要求收尾:測試通過、build 輸出、runtime 資料。官方原話:「Seems right」永遠不夠。要的是可驗證的證據,不是感覺對。

來源 · 官方 README「Key design choices」

漸進揭露,省 token

SKILL.md 是入口,支援性參考檔只在需要時才載入,讓 token 用量維持最小。不必一次把所有知識塞進 context。

來源 · 官方 README「Key design choices」

/build auto 一次跑完,但仍會驗證

規格就緒後,/build auto 會生計畫並在一次核准內實作每個任務。它拿掉的是「任務之間」的人工介入,不是驗證:每個任務仍 test-driven、逐一提交,遇失敗或高風險步驟會暫停。

來源 · 官方 README「Commands」

技能會依工作自動啟用

不必每次手動選技能。設計 API 自動觸發 api-and-interface-design、建 UI 觸發 frontend-ui-engineering。8 個指令只是手動入口。

來源 · 官方 README「Commands」

用 persona 做定向審查

需要特定視角時呼叫 persona:code-reviewer 用「staff 工程師會核准嗎」的標準、security-auditor 做 OWASP 評估。編排規則見 docs/agents.md,且「persona 不呼叫 persona」。

來源 · 官方 README「Agent Personas」

內建的是 Google 工程實務

Hyrum's Law、Beyoncé Rule、測試金字塔、Chesterton's Fence、trunk-based development、Shift Left 都直接編進步驟裡,出處是《Software Engineering at Google》與 Google eng-practices guide。

來源 · 官方 README「Why Agent Skills?」

05實戰示範

從 /spec 一路跑到 /ship。

以下示範把一個新功能跑完整個生命週期:/spec 先逼出規格、/plan 拆成原子任務、/build 逐片實作、/test 取得證據、/review 過品質關卡、/ship 上線。指令與原則均取自官方 README。

~/projects/app · claude code · agent-skills


$ You › /spec 加一個匯出 CSV 的功能


# [activates spec-driven-development]
claude: Claude ›
  寫 code 前先定義邊界。PRD 草稿:
    · 目標:使用者匯出篩選後的清單為 CSV
    · 邊界:不含分頁外資料、上限 10 萬列、UTF-8 BOM
    · 測試:空集合、特殊字元跳脫、大檔串流
# [wrote spec.md · 等你確認]


$ You › /plan
# [planning-and-task-breakdown · 拆成 4 個原子任務,附驗收條件]
    T1 CSV 編碼工具(跳脫 + BOM)  T2 串流匯出端點
    T3 前端按鈕 + 下載  T4 大檔 E2E


$ You › /build
# [incremental-implementation · 薄垂直切片]
  # T1 實作→測試→提交 ✓   T2 實作→測試→提交 ✓
  hl: TDD:先寫紅燈測試,再寫實作轉綠


$ You › /test
ok: 42 passed · 含特殊字元跳脫與 10 萬列串流 · 證據已附


$ You › /review
# [code-review-and-quality · 五軸審查 · 變更 ~90 行]
    [Nit] 變數命名  [FYI] 可抽共用跳脫函式
    [Optional] 大檔加進度提示 → 記入 backlog


$ You › /ship
ok: trunk-based · 原子提交 · feature flag: csv_export=staged
ok: PR 開好 · 上線前檢查清單通過 ✓

每個技能都以證據要求收尾。 「Seems right」永遠不夠。

— 依官方 README「Verification is non-negotiable」

這段示範的重點

六個指令不是六段獨立操作,而是一條有交班的流程:/spec 產出的 PRD 餵給 /plan,任務拆解餵給 /build,每一步都在 agent 想跳過時被「反合理化」表格擋下來。最後的 /review 用嚴重度標籤分流,把非阻擋項丟進 backlog 而非卡住合併。

示範中的測試數、變更行數與標籤是說明性數值,實際結果取決於你的任務與 codebase。要少手動介入,可在規格就緒後改用 /build auto 一次核准跑完。

06邊界與限制

知道它的成本與邊界。

07進階路徑

改成你團隊的標準。

裝好、跑通一輪生命週期之後,下面幾步把 Agent Skills 從「個人工作流」推進到「團隊一致的工程規範」。

進階玩法地圖

**1. 客製化技能。**每個 SKILL.md 都是純 Markdown,打開就能改步驟、加你公司的 lint 規則與命名慣例、補你自己的反合理化條目。

**2. 用 persona 編排審查。**讀 docs/agents.md 的決策矩陣,讓 code-reviewer、security-auditor、web-performance-auditor 組成定向審查;記住「persona 不呼叫 persona」這條編排規則。

**3. 把參考清單接進關卡。**把 security-checklist.md、performance-checklist.md、accessibility-checklist.md 接到 CI 或上線前 gate,讓品質要求可被檢核。

**4. 跨工具同步同一套規則。**技能是純 Markdown,可同時放進 Claude Code、Cursor、Windsurf、Kiro、Copilot。團隊用不同編輯器也能共用同一份工程規範。

**5. 自己評估,再決定要不要用。**讀 docs/comparison.md 的對比與 head-to-head 實驗,對照 Superpowers 與 Matt Pocock 的 skills,挑最適合你團隊的形狀。

最該讀的三份延伸閱讀

① docs/skill-anatomy.md——技能格式規格:Frontmatter、Process、Rationalizations、Red Flags、Verification。 ② docs/agents.md——persona 決策矩陣、編排規則,以及與技能、指令如何組合。 ③ docs/comparison.md——與 Superpowers、Matt Pocock skills 的誠實對比與適用場景。

好技能應該是 specific、verifiable、 battle-tested、minimal—— 可執行、可驗證、實戰過、夠精簡。

— 依官方 README「Contributing」段落