02 · MECHANISM10 / 30

SKILL · 原理

先看 description,
用到才讀完整內容。

STEP 01 · SESSION 啟動

只載 metadata

模型拿到所有 skills 的 name + description,內容沒進 context。

# context 裡只有清單
brainstorming → "Use when..."
code-review   → "Run after..."
pr-summary    → "When opening..."

STEP 02 · USER → MATCH

意圖對上 description

Agent 自己判斷哪個 skill 該觸發 — 你不用喊出 skill 名字。

> 幫我想想通知系統怎麼辦
# Agent 比對 description
match → brainstorming ✓

STEP 03 · LOAD BODY

完整內容才進 context

規則、步驟、範例這時才被讀進來;沒被叫到的 skill 永遠不佔空間。

# brainstorming.md 全文
✓ rules
✓ process
✓ anti-patterns

結論:description 是唯一被「常駐看到」的部分。寫不準 = 不會被叫到 = 等於不存在。

SOURCES

① Anthropic Engineering — Agent Skills(progressive disclosure 原文) · anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills

② OpenAI — Codex Skills(同 metadata-first 模型) · developers.openai.com/codex/skills

③ GitHub Copilot — Agent Skills(2026 起支援,同 progressive disclosure 開放標準) · docs.github.com/en/copilot/concepts/agents/about-agent-skills

02 · ARCHITECTURE11 / 30

SKILL · 架構

Skill 不是一段 prompt,
是一個可被 catalog 的小套件。

skill-name/
|-- SKILL.md
|   |-- frontmatter
|   |   |-- name
|   |   `-- description
|   `-- instructions
|-- references/
|-- scripts/
`-- assets/

01 · CATALOG

metadata

常駐在清單裡,決定 AI 看不看得到這個 skill。

name + description

02 · EXECUTION

body

被選中後才進 context,放流程、規則、反例。

SKILL.md content

03 · ASSETS

dependencies

細節、範本、腳本拆出去,需要時再讀或執行。

refs / scripts / assets

工程師視角: description = public interface; body = implementation; references/scripts/assets = dependencies。

下一頁的載入策略,其實是在比較 catalog 能不能被模型看見,以及 body 什麼時候進 context。

SOURCES

① Claude / Anthropic Agent Skills: metadata、body、additional files · anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills

② Codex / OpenAI Skills: SKILL.md、scripts、references、assets · developers.openai.com/codex/skills

③ Copilot / GitHub Agent Skills: SKILL.md frontmatter、scripts、examples/resources · docs.github.com/en/copilot/.../add-skills

02 · COMPARISON12 / 30

SKILL · 三種載入策略

三種載入策略,
差在誰決定、何時進 context。

	AI 自選能力 AGENT SKILLS	常駐規範 ALWAYS-LOADED	手動叫用流程 USER-INVOKED
Loading	Progressive description 常駐 → body on invoke	Eager 每次 task / session 都先讀入	On-demand 明確指令或 mention 才載
Catalog	有 description catalog AI 可從清單判斷該用哪個能力	沒有 catalog 整份規範直接進 context	不靠 catalog 使用者指定要跑哪個流程
Decision	AI 判斷也可以由使用者明確指定	工具自動套用不用觸發，但也不能選擇性省略	使用者主動叫要記得流程名稱或指令
Names	Agent Skills Claude Skills · Codex Skills · Copilot Skills	Instruction files CLAUDE.md · AGENTS.md · Copilot custom instructions	Commands / prompts Claude /skill · Codex $skill · Copilot prompt files
Best for	多種專業情境讓 AI 自己挑該用哪個能力	專案通用規範 coding style、repo rule、工作偏好	固定流程 template 每次步驟都差不多的操作

判斷原則:通用規範放常駐；專業能力做 skill；固定流程才用手動叫用。

02 · QUALITY13 / 30

穩定可復用 · 三個條件

一個好 skill,
每次叫出來都長一樣。

Scope 要小

一個 skill 做一件事。brainstorming 就是 brainstorming,不要塞 code review。

Trigger 要準

用情境而非關鍵字 —「when exploring ideas」比「brainstorm」好。

範例要真

附 good / bad example,model 會照著做。抽象規則它容易自由發揮。

02 · ANATOMY14 / 30

SKILL · 解剖

把 brainstorming 拆開看。

---
name: brainstorming
description: Use when the user wants to explore
  multiple ideas BEFORE committing to one.
---

# Brainstorming

## When to use this
- Vague prompts ("help me think about X")
- User explicitly asks for options
- Before writing code for ambiguous specs

## Process
1. Restate the problem in one sentence.
2. Generate 5+ distinctly different angles.
3. For each: pros, cons, which use-case it wins.
4. Stop. Do not pick for them.

## Anti-patterns
✗ Converging too early
✗ Three angles that are the same idea reworded

METADATA

決定 AI 看不看到。description 是 trigger。

WHEN TO USE

用情境描述,不是關鍵字比對。

PROCESS

步驟明確。不要只寫「think carefully」。

ANTI-PATTERNS

負面規則通常比正面規則更有用。

02 · OPS15 / 30

SKILL · OWNERSHIP

先決定 owner,
再談載入點。

Owner	判斷問題	放錯會怎樣	適合放什麼
Personal ME ONLY	只有我需要嗎? 個人偏好、常用流程、自己的工作記憶。	個人偏好變成團隊負擔放進專案後,每個 agent 都會吃到你的私人工作習慣。	Superpowers 個人裝一組現成流程:brainstorming、debugging、verification。
Team SHARED RULE	團隊要一致嗎? 跨 repo 可復用,需要 review、版本、升級流程。	共用規則長出多個版本沒有 review、版本、升級流程,每個 repo 會慢慢不一樣。	104 coding standards 共用 review rule、API error handling、test naming,版本化後分發。
Project THIS REPO	只在此專案成立嗎? 依賴 repo 架構、domain rule、內部 API 或測試資料。	其他人或其他 agent 看不到放在個人環境,專案規則就無法跟著 repo 重現。	EOL migration check 專案限定的 legacy mapping、domain rule、測試缺口盤點。

判斷順序:先找 owner,再選載入點。Personal / Team / Project 是責任邊界。

SOURCES

① Claude Code — Where skills live: enterprise / personal / project / plugin · code.claude.com/docs/en/skills

② Codex — repository / user / admin / system locations, plugins for distribution · developers.openai.com/codex/skills

③ GitHub Copilot — project / personal skills, gh skill public preview for install/update · docs.github.com/.../add-skills

PART 03 · WORKSHOP16 / 30

PART 03 ── AI CODING WORKSHOP

工具整合,
才是真正的槓桿。

一個人用 AI 寫 code 很強,一個團隊用對工具 — 是另一個量級。

03 · STACK17 / 30

今天的工具箱

五樣,每一樣解一個痛點。

MCP

外部能力的插座

解:AI 看不到你的 DB / API / 內部文件

worktree

平行開發基石

解:AI 還在跑,你要開新 branch 改別的

skills

可復用專業知識

解:每次都重寫 prompt · 品質忽高忽低

hooks

流程自動化

解:AI 寫完忘記跑 lint / format / test

05 ★

super
powers

整組現成 skill pack

今天的主角 · 重點 demo

03 · TOOL 0118 / 30

01 ── MCP · CLAUDE CODE

外部能力
的插座

把 GitHub / Linear / DB / 內部 API 接成 AI 能直接呼叫的工具。

github linear postgres filesystem slack

CHEATSHEET

# 加一個 MCP server
$ claude mcp add github \
    -- npx -y @modelcontextprotocol/server-github

# 列出有哪些工具可用
$ claude mcp list

# 在 session 裡直接叫
> 把這個 PR 的 review comments 整理成 TODO

Rule of thumb — 當你發現自己 copy-paste 給 AI 的東西重複出現,那就是一個 MCP。

03 · TOOL 0219 / 30

02 ── GIT WORKTREE

平行開發
的基石

一個 repo、多個 working directory。AI 在一個 worktree 跑 migration,你在另一個寫 UI。

痛點: AI 花 10 分鐘跑 test,你這 10 分鐘什麼都不能做。

CHEATSHEET

# 為新 feature 開一個 worktree
$ git worktree add ../app-feat-auth feat/auth
$ cd ../app-feat-auth && claude

# 回主線改別的
$ cd ../app && claude

# 看目前有哪些 worktree
$ git worktree list

# 完工後清掉
$ git worktree remove ../app-feat-auth

03 · TOOL 0320 / 30

03 ── SKILLS

同一種
SKILL.md
模型

Part 2 講的是能力模型:一個 skill 由 description 觸發,用到才載入完整內容。不同工具只是搜尋位置和分發方式不同。

承接第 15 頁的 owner 判斷後,這一頁只回答一件事:在 Codex / Claude / Copilot 裡實際放哪裡。

TOOL MAPPING

Tool	Project	Personal	Team
Codex	`.agents/skills/` 可放在 CWD 到 repo root 的任一層	`~/.agents/skills/` 個人跨 repo 能力	plugin / shared repo 需要分發時包成 plugin
Claude	`.claude/skills/` 專案專屬,跟 repo 一起 review	`~/.claude/skills/` 個人全域 skills	repo / installer 共用來源安裝到 user 或 project
Copilot	`.github/skills/` 也支援 `.agents/skills/` / `.claude/skills/`	`~/.copilot/skills/` 也支援 `~/.agents/skills/`	`gh skill` preview 搜尋、安裝、更新 shared skills

SOURCES · Codex Skills · GitHub Copilot Skills

03 · SKILL VS COMMAND21 / 30

SLASH COMMANDS · 你的快捷鍵

常做的事,寫成 /command。

# Claude Code example: .claude/commands/ship.md
---
description: 幫我 review、跑 test、寫 commit message、
  開 PR — 一條龍
---

1. git diff --staged 看改了什麼
2. 跑 pnpm test,fail 就停
3. 寫一句 conventional commit
4. gh pr create --fill
5. 把 PR link 貼給我

USAGE · CLAUDE CODE

> /ship

# 一句話,跑完整流程

Skills 是 AI 自己會判斷用不用,
slash command 是你明確叫它做。

03 · TOOL 0422 / 30

04 ── HOOKS

流程
自動化

在特定事件自動跑指令:寫完檔案跑 format、送出前跑 lint、commit 前跑 test。

PostToolUse → prettier --write PreCompact → dump notes to file Stop → run tests

EXAMPLE · CLAUDE CODE · .claude/settings.json

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "pnpm format $CLAUDE_FILE_PATHS"
      }]
    }],
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "pnpm test --changed"
      }]
    }]
  }
}

03 · WHY SUPERPOWERS23 / 30

WHY NOT JUST /PLAN?

不是不用 `/plan`,
而是把「規劃」變成開發流程。

NATIVE /PLAN

先停下來想,
避免直接改檔。

進入 plan mode,先分析 codebase
適合探索、估範圍、討論方向
重點是「安全模式」與互動確認
後續品質仍靠你提醒與追蹤

SUPERPOWERS

把 plan 接到
真正的開發循環。

brainstorming 用一連串問題釐清需求
writing-plans 拆成可執行的小 task
TDD / review / verification 接住實作
skill 自動觸發,也能跨工具復用

個人使用感覺:方向性更明確,也更方便;因為它會用一連串問題讓需求更清楚,這也讓 design 文件品質更好。

SOURCE · /plan commandSOURCE · Claude Code plan modeSOURCE · Superpowers workflow

03 · LIVE DEMO ★24 / 30

SUPERPOWERS · CLAUDE CODE DEMO

現成的 skill pack,
一行指令裝上來。

INSTALL · CLAUDE CODE

# 一次載入一整組精選 skills
$ /plugin install superpowers@claude-plugins-official

# 看看裝了什麼
$ claude skills list
✓ brainstorming
✓ rubber-duck
✓ code-archaeology
✓ pr-storytelling ... +12 more

# Demo:給一個模糊的問題
> 通知系統太吵 — 幫我想想

AI · AUTO-TRIGGERED

偵測到「幫我想想」→ 載入 brainstorming

STEP 1

把問題重述一遍 → 確認理解

STEP 2

給 5 個「不同角度」的方案

STEP 3

每個 pros / cons / 適合場景 — 不替你決定

03 · FLOW25 / 30

一次完整的開發循環

所有東西組起來是這樣。

開 worktree

隔離這個 task

新 session

乾淨 context

skill 被觸發

brainstorm / plan

MCP 抓資料

github / DB

hook 自動跑

format · test

/ship

一條龍送出

── context 乾淨 ── 知識可復用 ── 流程不用記 ── 平行不卡

03 · IMPACT26 / 30

痛點 · 前後對比

一樣是用 AI 寫 code,感受差一個檔次。

── 沒工具整合

寫 AI prompt 的人

每次複製貼上 context
每次手寫「請先 review 再 commit」
AI 跑的時候只能等
好的 prompt 留在某個聊天記錄裡
切 task 忘記清 session

── 有 AI coding stack

用 AI 工程化的人

MCP 直接連 → 不用貼
Hook 自動跑 → 不用記
Worktree 平行 → 不用等
Skill / slash 可復用 → 不用寫
一 task 一 session → 不會亂

03 · TAKEAWAY27 / 30

收斂 · 三句話

今天帶走三件事。

Context 乾淨,model 才會聰明。

好 prompt 寫一次,skill 用一輩子。

工具組起來,AI 才真的是同事。

03 · CHEATSHEET28 / 30

DEMO CHEATSHEET

今日 demo 指令 · 帶走這一張就好

── SESSION · CLAUDE CODE

/clear 清空 context,開新 task 前用

/compact 壓縮歷史 · 保留關鍵決策

/resume 回到上次的 session

/cost 看這個 session 花了多少

── MCP

claude mcp add <name> -- <cmd>

claude mcp list

claude mcp remove <name>

── WORKTREE

git worktree add ../path branch

git worktree list

git worktree remove ../path

── SKILLS

~/.claude/skills/*.md 全域

.claude/skills/*.md 專案

/skill <name> 手動觸發

── SUPERPOWERS · THREE TOOLS

/plugin install superpowers@claude-plugins-official

claude skills list

claude skills disable <name>

03 · SETUP29 / 30

SUPERPOWERS · 安裝方式

不是重裝 AI 工具,
是把 workflow 裝進你的 agent。

CLAUDE CODE

官方 plugin marketplace

Claude Code 裡直接裝,下一個 session 會自動載入 skills。

$ /plugin install superpowers@claude-plugins-official

CODEX CLI

官方 plugin marketplace

在 Codex 開 plugin 搜尋,找到 Superpowers 後按 Install。

$ /plugins
> search: superpowers
> Install Plugin

GITHUB COPILOT CLI

Superpowers marketplace

先註冊 marketplace,再安裝 Superpowers plugin。

$ copilot plugin marketplace add obra/superpowers-marketplace

$ copilot plugin install superpowers@superpowers-marketplace

裝完後開新 session,用「幫我想想 / debug / review」測 skill 是否會觸發。其他環境看文件 · github.com/obra/superpowers#installation

HANDS-ON · Q&A 30 / 30

── NOW IT'S YOUR TURN

挑題目
跑一輪。

挑一個下列小工具，先用 brainstorming 釐清規格，再走完整開發循環。

OPTION 01

匯率轉換工具

金額 · 幣別 · 換算結果

OPTION 02

顏色轉換工具

HEX · RGB · HSL

OPTION 03

密碼產生器

長度 · 規則 · 複製

FLOW · pick topic → clarify with brainstorming → implement in worktree → verify → summarize

有問題隨時打斷 ↗感謝聆聽 · THANK YOU

Context.
Skills.
Superpowers.

一個 session,
一件事。

模型看到的不是「你的專案」,
是這個 session 的對話歷史。

同一個 session,從早寫到晚。

每一輪對話,都付全長的錢。

一個 task,
一個 session,
做完就 /clear。

好用的 prompt,
是可復用的能力。

一段可被 AI 讀取、且知道
「什麼時候該用」的指令集。

先看 description,
用到才讀完整內容。

Skill 不是一段 prompt,
是一個可被 catalog 的小套件。

三種載入策略,
差在誰決定、何時進 context。

一個好 skill,
每次叫出來都長一樣。

把 brainstorming 拆開看。

先決定 owner,
再談載入點。

工具整合,
才是真正的槓桿。

五樣,每一樣解一個痛點。

外部能力
的插座

平行開發
的基石

同一種
SKILL.md
模型

常做的事,寫成 /command。

流程
自動化

不是不用 `/plan`,
而是把「規劃」變成開發流程。

現成的 skill pack,
一行指令裝上來。

所有東西組起來是這樣。

一樣是用 AI 寫 code,感受差一個檔次。

今天帶走三件事。

今日 demo 指令 · 帶走這一張就好

不是重裝 AI 工具,
是把 workflow 裝進你的 agent。

挑題目
跑一輪。

TWEAKS

Context. Skills. Superpowers.

一個 session, 一件事。

模型看到的不是「你的專案」,是這個 session 的對話歷史。

同一個 session,從早寫到晚。

每一輪對話,都付全長的錢。

一個 task, 一個 session, 做完就 /clear。

好用的 prompt, 是可復用的能力。

一段可被 AI 讀取、且知道「什麼時候該用」的指令集。

先看 description,用到才讀完整內容。

Skill 不是一段 prompt,是一個可被 catalog 的小套件。

三種載入策略,差在誰決定、何時進 context。

一個好 skill,每次叫出來都長一樣。

把 brainstorming 拆開看。

先決定 owner,再談載入點。

工具整合, 才是 真正的槓桿。

五樣,每一樣解一個痛點。

外部能力的插座

平行開發的基石

同一種SKILL.md模型

常做的事,寫成 /command。

流程自動化

不是不用 /plan,而是把「規劃」變成開發流程。

現成的 skill pack,一行指令裝上來。

所有東西組起來是這樣。

一樣是用 AI 寫 code,感受差一個檔次。

今天帶走三件事。

今日 demo 指令 · 帶走這一張就好

不是重裝 AI 工具,是把 workflow 裝進你的 agent。

挑題目跑一輪。

TWEAKS

Context.
Skills.
Superpowers.

一個 session,
一件事。

模型看到的不是「你的專案」,
是這個 session 的對話歷史。

一個 task,
一個 session,
做完就 /clear。

好用的 prompt,
是可復用的能力。

一段可被 AI 讀取、且知道
「什麼時候該用」的指令集。

先看 description,
用到才讀完整內容。

Skill 不是一段 prompt,
是一個可被 catalog 的小套件。

三種載入策略,
差在誰決定、何時進 context。

一個好 skill,
每次叫出來都長一樣。

先決定 owner,
再談載入點。

工具整合,
才是真正的槓桿。

外部能力
的插座

平行開發
的基石

同一種
SKILL.md
模型

流程
自動化

不是不用 `/plan`,
而是把「規劃」變成開發流程。

現成的 skill pack,
一行指令裝上來。

不是重裝 AI 工具,
是把 workflow 裝進你的 agent。

挑題目
跑一輪。