agency-agents 詳細教學

對應 repo: https://github.com/msitarzewski/agency-agents（103k stars / 17k forks / MIT，截至 2026-05-21）

1. 專案定位

1.1 它是什麼

Matt Sitarzewski 開源的 「一個 repo = 一整家 AI 顧問公司」。190+ 個 agent persona（不是空白 prompt template！）按 17 個 division 分類：工程、設計、行銷、銷售、產品、財務、學術、法務、醫療、遊戲、VR … 一份 root .md → convert.sh 轉成 11 個 AI 工具的專屬格式（Claude Code、GitHub Copilot、Antigravity、Gemini CLI、OpenCode、OpenClaw、Cursor、Aider、Windsurf、Kimi、Qwen）→ install.sh 一鍵裝。

1.2 它解決什麼問題

• 「每次想喚醒專業角色就要重寫 prompt」：本 repo 直接給 190+ 個已調試的 persona
• 「同一個 agent 在 Claude / Cursor / Copilot 寫法都不同」：本 repo 寫一份，convert 出 11 種版本
• 「prompt 寫得太空，agent 沒個性」：本 repo 強制 6 段結構（identity + memory + mission + workflows + deliverables + metrics + style）
• 「公司想引入 AI 但不知道從哪些角色開始」：直接看 README roster，從 division 挑

1.3 與其他 prompt library 差異

agency-agents 數量 與 跨工具 兩端皆冠。

1.4 適合誰用

• 個人開發者：想隨時喚醒「Frontend Developer / Backend Architect / Code Reviewer」
• 小公司：沒錢請 marketing / legal / sales 員工，用 AI 角色補位
• 顧問：用「Strategy / Product / UX Researcher」做客戶簡報
• 教育單位：當作 prompt engineering 教材
• 想 fork 自家工具的 prompt 集合：本 repo 是最好的 monorepo + 自動化 template

2. 安裝指南

2.1 一鍵互動安裝（推薦）

 1git clone --depth 1 https://github.com/msitarzewski/agency-agents
 2cd agency-agents
 3
 4# auto-detect 已裝的工具 + 互動式選擇
 5./scripts/install.sh
 6
 7# 流程：
 8# [✓] Detected: claude-code (~/.claude/)
 9# [✓] Detected: cursor (.cursor/)
10# [ ] Not detected: gemini-cli
11# > Install for which tools?  [a]ll  [s]elect  [q]uit

2.2 指定單一工具

 1./scripts/install.sh --tool claude-code      # ~/.claude/agents/
 2./scripts/install.sh --tool copilot          # ~/.github/agents/ + ~/.copilot/agents/
 3./scripts/install.sh --tool antigravity      # ~/.gemini/antigravity/skills/
 4./scripts/install.sh --tool gemini-cli       # ~/.gemini/extensions/agency-agents/
 5./scripts/install.sh --tool opencode         # ./.opencode/agents/
 6./scripts/install.sh --tool cursor           # ./.cursor/rules/
 7./scripts/install.sh --tool aider            # ./CONVENTIONS.md
 8./scripts/install.sh --tool windsurf         # ./.windsurfrules
 9./scripts/install.sh --tool openclaw         # ~/.openclaw/agency-agents/
10./scripts/install.sh --tool qwen             # ~/.qwen/agents/ or ./.qwen/agents/
11./scripts/install.sh --tool kimi             # Kimi Code

2.3 只裝某個 division

1# 假設 integrations/claude-code/ 已生成（convert.sh 跑過）
2cp integrations/claude-code/engineering-*.md ~/.claude/agents/   # 只裝 engineering
3cp integrations/claude-code/specialized-*.md ~/.claude/agents/   # 只裝 specialized

2.4 環境需求

• Bash 3.2+（macOS 內建 / Linux / Windows Git Bash / WSL）
• 對應 AI 工具已裝（install.sh auto-detect 對應目錄）
• 想用 parallel：./scripts/install.sh --parallel --jobs 4

flowchart LR
    R[Root .md
engineering/.../*.md
×190+] --> CV[scripts/convert.sh]
    CV --> I1[integrations/claude-code/]
    CV --> I2[integrations/copilot/]
    CV --> I3[integrations/antigravity/]
    CV --> I4[integrations/gemini-cli/]
    CV --> I5[integrations/opencode/]
    CV --> I6[integrations/cursor/]
    CV --> I7[integrations/aider/]
    CV --> I8[integrations/windsurf/]
    CV --> I9[integrations/openclaw/]
    CV --> I10[integrations/qwen/]
    CV --> I11[integrations/kimi/]
    I1 --> INS[scripts/install.sh]
    I2 --> INS
    I3 --> INS
    I4 --> INS
    I5 --> INS
    I6 --> INS
    I7 --> INS
    I8 --> INS
    I9 --> INS
    I10 --> INS
    I11 --> INS
    INS --> T[各家 AI 工具
~/.claude/, ~/.cursor/, ~/.openclaw/, ...]

3. 核心架構解析

3.1 17 個 division + 數量

graph TB
    subgraph "Tech-heavy"
        E[engineering
29]
        D[design
8]
        T[testing
8]
        SC[spatial-computing
6]
        GD[game-development
5]
    end
    subgraph "Business"
        M[marketing
30]
        S[sales
8]
        PM[paid-media
7]
        P[product
5]
        PJ[project-management
6]
        ST[strategy
3]
        F[finance
5]
    end
    subgraph "Knowledge / Service"
        SP[specialized
41]
        SU[support
6]
        A[academic
5]
        EX[examples
6]
    end

最大三類：specialized (41) + marketing (30) + engineering (29) = ~100 個 agent；其餘 ~90 個分布在另外 14 個 division。

3.2 一個 agent 的 6 段強結構

 1---
 2name: <Agent Name>            ← 必要：呼叫用
 3description: <1 line>          ← 必要：agent 自動觸發判斷
 4color: <CSS color>             ← UI 標識
 5emoji: <unicode>               ← UI 標識
 6vibe: <1-line personality>     ← 速讀印象
 7---
 8
 9# <Name> Agent Personality
10
11## 🧠 Your Identity & Memory     ← 1. 我是誰
12- Role / Personality / Memory / Experience
13
14## 🎯 Your Core Mission           ← 2. 我做什麼
15### <subsection 1>
16- <action 1>
17- <action 2>
18
19## <Workflows>                   ← 3. 我怎麼做
20## <Deliverables>                ← 4. 我交付什麼
21## <Success Metrics>             ← 5. 怎麼算我成功
22## <Communication Style>         ← 6. 我怎麼說話

設計重點：description 必須讓 host agent（Claude / Cursor 等）自動判斷「現在該召喚這個 agent 嗎？」— 寫法越具體越好。

3.3 跨 11 工具的 convert 模式

sequenceDiagram
    participant U as 使用者
    participant R as Root .md
    participant CV as convert.sh
    participant I as integrations/<tool>/
    participant INS as install.sh
    participant T as Tool's config dir

    U->>CV: ./scripts/convert.sh
    Note over CV: 對每個 root .md 跑一次
    loop 每個 root .md
        CV->>R: 讀
        CV->>CV: 抽 frontmatter + body
        CV->>CV: 對每個 tool 跑 adapter
        Note over CV,I: adapter 規則：
- Claude Code: 直接複製
- Cursor: 轉 .cursor-rule
- Aider: append 到 CONVENTIONS.md
- Windsurf: 轉 .windsurfrules block
- Gemini extension: 包成 extension.json
- ...
        CV->>I: 寫 converted file
    end
    U->>INS: ./scripts/install.sh --tool claude-code
    INS->>I: 讀 integrations/claude-code/
    INS->>T: cp 到 ~/.claude/agents/
    INS-->>U: ✓ 190 agents installed

3.4 lint-agents.sh 強制規範

1./scripts/lint-agents.sh
2
3# 校驗：
4# - 每個 .md 都有 valid frontmatter（name / description 必填）
5# - body 含 6 段標題（Identity / Mission / Workflows / Deliverables / Metrics / Style）
6# - 無 hardcoded API key / token / password
7# - 檔名符合 <division>-<slug>.md 規則

是 CI 的必過 gate（看 .github/workflows/）。

3.5 mcp-memory 整合

integrations/mcp-memory/ 是個 MCP server，讓 agent 跑出的成果可以存到共用記憶 — 跟 agentmemory（本知識庫已知）概念互通。可以併用：agency-agents 提供 persona，agentmemory 提供持久記憶。

4. Helper Scripts 詳細用法

4.1 scripts/install.sh

 1# 顯示 help
 2./scripts/install.sh --help
 3
 4# 主要 flags
 5--tool <name>      # 指定工具（11 個 + all）
 6--interactive      # 互動式選擇（terminal 預設）
 7--no-interactive   # 安靜模式，裝所有偵測到的
 8--parallel         # 平行裝（順序可能亂）
 9--jobs N           # parallel 最大 N（預設 nproc 或 4）
10
11# 範例組合
12./scripts/install.sh --no-interactive --parallel --jobs 8
13# → 全部偵測到的工具同時裝，最快

4.2 scripts/convert.sh

把 root <division>/*.md 轉成各家格式，輸出到 integrations/。第一次或新增 agent 後必跑。

1./scripts/convert.sh           # 全部
2./scripts/convert.sh --tool cursor    # 只重 cursor

4.3 scripts/lint-agents.sh

1./scripts/lint-agents.sh             # 全部
2./scripts/lint-agents.sh engineering # 單 division
3./scripts/lint-agents.sh --fix       # 自動修簡單問題

4.4 scripts/i18n/

i18n 工具（最近 #338 PR 加進來的 Chinese localization for agent names）。

5. 應用場景

6. 資安掃描報告

掃描範圍：scripts/、SECURITY.md、agent .md（spot check）、integrations/。

綜合燈號：🟢 / 🟡（核心無紅燈；要警惕「prompt injection 從社群 PR 進來」這個面）

重點建議：

• 安裝前spot-check 你要用的那幾個 agent 的 .md，看有沒有怪指令（「ignore previous」「always do X regardless of user」）
• 不要用 --no-interactive --parallel 一次裝全部 — 先互動裝 5–10 個你真的會用的
• 監聽本 repo 是否引入 AI 自動審查（仿 claude-plugins-official 的 scan-plugins.yml）

7. FAQ

Q1：跟 ConardLi/garden-skills、claude-plugins-official 是什麼關係？ A：

• garden-skills：4 個聚焦 SKILL.md（深度勝出）
• claude-plugins-official：203 個 plugin marketplace（包含 hooks / LSP / MCP）+ AI 審查（治理勝出）
• agency-agents：190+ 個 persona-driven prompt（廣度勝出，11 工具支援，但缺 AI 審查）

3 者可以並用：用 agency-agents 喚醒 persona、用 garden-skills 跑專業工作流、用 claude-plugins-official 裝 plugin。

Q2：作者 msitarzewski 是誰？ A：Matt Sitarzewski；本 repo 是他維運的個人 OSS 集大成（103k stars 表明社群超紅）。歡迎 sponsor。

Q3：為什麼 fork 數 (17k) 比 star 數 (103k) 高那麼多比例（fork/star ≈ 17%）？ A：典型「人們 fork 來改自家用」的 prompt library 特徵。fork ≠ 開發貢獻；是「我要客製化內容」。

Q4：能不能只 import 某幾個 agent，不要全裝？ A：可以——直接 cp <division>/<specific-agent>.md ~/.claude/agents/（不要走 install.sh）。或者刪 root 不要的 .md 再跑 convert + install。

Q5：agent .md 能用在 OpenAI ChatGPT custom GPT 嗎？ A：直接複製 .md 內容到 ChatGPT 的 custom GPT instruction 欄位，可以用（但不會有 install.sh 那層自動化）。

Q6：怎麼貢獻新 agent？ A：看 CONTRIBUTING.md（14KB）— 完整 style guide：

1. 確認分類 + 不重複
2. 用 6 段結構寫
3. 跑 lint-agents.sh 過
4. 開 PR

Q7：lint-agents.sh 都檢查什麼？ A：（從 SECURITY.md + 命名推測）：

• frontmatter 有效（name / description 必填）
• 6 段標題齊全
• 無 API key 字串
• 無「ignore previous instructions」這類疑似 injection 字串
• 檔名符合 <division>-<slug>.md

Q8：本 repo 7 個月 103k stars 是怎麼來的？ A：原始啟發是 Reddit 串；早期被多個 AI tooling 社群轉發；fork-friendly 設計（每個人都 fork 來自家用 → 強曝光）；多工具支援戳到很多痛點。

Q9：跟 agentmemory 怎麼搭？ A：integrations/mcp-memory/ 暗示作者已意識到「persona + memory」的雙劍合璧。實務上：用 agency-agents 喚醒角色 → 該角色的工作成果 / 對話進 agentmemory → 下次同角色 session 自動 recall。

8. 進階技巧

8.1 自製 agent

 1# 1. 選 division
 2cd engineering/
 3
 4# 2. 抄一個現成的當 template
 5cp engineering-frontend-developer.md engineering-data-scientist.md
 6
 7# 3. 改 frontmatter + 6 段內容
 8vim engineering-data-scientist.md
 9
10# 4. lint
11./scripts/lint-agents.sh engineering
12
13# 5. convert + install
14./scripts/convert.sh
15./scripts/install.sh --tool claude-code

8.2 為自家工具加 integration adapter

看 scripts/convert.sh 內各 tool 的 adapter 邏輯（bash function）。例如要加 cline 或 roo-code 等新工具：

1. 在 convert.sh 加 convert_for_<tool>() 函式
2. 在 install.sh 加 install_<tool>() 函式 + 路徑常數
3. 在 README 補一段
4. 開 PR

8.3 用 i18n 系統翻譯

1ls scripts/i18n/
2# 跑翻譯（看 README 內 Community Translations 段落）

中文 zh-CN 已有；繁中 zh-TW 是 fork 的好機會（按 contributing 規則加）。

8.4 把 agency-agents 接到本知識庫

1# 在本知識庫的 .claude/agents/ 加 symbolic links
2ln -s /path/to/agency-agents/engineering/engineering-code-reviewer.md \
3      .claude/agents/
4
5# 或直接 cp 過來但不要進 git
6echo "/.claude/agents/agency-*" >> .gitignore
7cp /path/to/agency-agents/integrations/claude-code/*.md .claude/agents/

8.5 跟 dari-docs 互測

把任一個 agent .md 餵 dari-docs：

1dari-docs check /path/to/agency-agents/engineering --managed \
2  --task "Activate Frontend Developer mode and build a React counter"

看 agent 能否在 sandbox 真實照 persona 做事。

9. 整合進其他工作流

10. 重點摘要 Checklist

• 103k stars / 17k forks / MIT / 7 個月生命週期（2025-10-13）
• 190+ agent persona 分 17 個 division
• specialized (41) + marketing (30) + engineering (29) 為三大類
• 11 個 AI 工具支援：Claude Code / Copilot / Antigravity / Gemini CLI / OpenCode / OpenClaw / Cursor / Aider / Windsurf / Kimi / Qwen
• 6 段強結構（Identity / Mission / Workflows / Deliverables / Metrics / Style）
• 3 個 shell script：install.sh / convert.sh / lint-agents.sh
• mcp-memory integration（可接 agentmemory）
• 中文 zh-CN i18n
• CONTRIBUTING.md 14KB + zh-CN 版
• SECURITY.md：禁止 .md 含可執行碼 + 禁 API key
• 無 AI 自動審查（相比 claude-plugins-official 缺一塊）
• 資安綜合燈號：🟢 / 🟡（要警惕社群 PR 的 prompt injection）

11. 進一步閱讀

• 官方 README roster：本 repo README.md 58KB（920 行）
• CONTRIBUTING.md 14KB：怎麼貢獻新 agent
• 對應姊妹專案：
  • ConardLi/garden-skills — inbox/2026-05-21-github-ConardLi-garden-skills.md
  • anthropics/claude-plugins-official — inbox/2026-05-21-github-anthropics-claude-plugins-official.md
  • rohitg00/agentmemory — inbox/2026-05-21-github-rohitg00-agentmemory.md
• 本知識庫先前 tutorial：inbox/2026-05-21-tutorial-text-to-cad.md
• Author sponsor：https://github.com/sponsors/msitarzewski