agent-skills 完整教學

一份不浪費你時間的 quick reference + 深度解析。 適合：想知道「能不能用」、「怎麼用」、「會不會中招」三件事的工程師。

1. 專案定位

1.1 一句話介紹

agent-skills 是一個 可信任的 AI agent skill (技能) 註冊中心 — 你可以把它想成 AI coding agent 版的 npm registry，但每個 skill 都經過資安掃描、人工審核與內容雜湊鎖定 (content hashing lockfile)。

1.2 為什麼需要它？

當前 AI agent 生態的痛點：

• Snyk Agent Scan 報告：marketplace 上 13.4% 的 skill 含嚴重漏洞（prompt injection、RCE 模式、credential leakage 等）
• 無統一標準：每家 agent (Claude Code / Cursor / Copilot / Antigravity …) 有不同 skill 格式，跨平台複用困難
• 安裝即執行：許多 skill 透過 postinstall hooks 或 shell command 執行，缺乏 sandbox

agent-skills 解決方案：

• 靜態分析 + 人工審核：所有 PR 走 Snyk Agent Scan + 維護者審核
• 統一 SKILL.md 格式：跨 14 種 agent 通用
• CDN 拉取 + lockfile：CLI 從 CDN 拉，內容雜湊鎖定，避免供應鏈攻擊
• Defense-in-depth CLI：輸入清洗 (sanitization)、路徑隔離 (filesystem isolation)、symlink guard、原子 lockfile、audit trail

1.3 適合誰用？

1.4 數字快照（2026-05-18）

• ⭐ Stars: 3,782 / Forks: 333
• 🛠 SKILL.md 檔數: 80 個 skill 跨 13 個分類（architecture / cloud / creation / decision-making / design / development / gtm / learning / monitoring / performance / quality / security / tooling / web-automation）
• 📦 主要套件: @tech-leads-club/agent-skills (CLI v1.4.7) + @tech-leads-club/agent-skills-mcp (v0.1.3)
• 🏗 架構: Nx monorepo, TypeScript 100%, Node ≥22 (CLI) / ≥24 (root)

2. 安裝指南

2.1 前置需求

• Node.js >= 22（建議 24 以對齊 monorepo 設定）
• npm 或 pnpm / yarn
• 一個支援的 AI agent（例如 Claude Code、Cursor）

2.2 三種安裝路徑

flowchart TD
    A[使用者] --> B{用途?}
    B -->|快速安裝 skill| C[npx 互動式 CLI]
    B -->|終端整合 skill 列表| D[MCP server]
    B -->|貢獻 / 自架 registry| E[clone monorepo]
    C --> F[skill 寫入 ~/.claude/skills/]
    D --> G[Agent 透過 MCP 查詢]
    E --> H[Nx build + 本地 dev]

2.3 路徑 A：互動式 CLI（推薦給一般使用者）

1# 一行式，零安裝
2npx @tech-leads-club/agent-skills
3
4# 或全域安裝
5npm i -g @tech-leads-club/agent-skills
6agent-skills

第一次跑會進入 React Ink 互動模式 (TUI; terminal user interface)：方向鍵選 skill、Enter 確認、自動偵測你裝了哪些 agent。

2.4 路徑 B：MCP server（推薦給已用 Claude Desktop / Cursor 等 MCP-aware 客戶端）

加入到你的 MCP client 設定（以 Claude Desktop 為例 ~/Library/Application Support/Claude/claude_desktop_config.json）：

1{
2  "mcpServers": {
3    "agent-skills": {
4      "command": "npx",
5      "args": ["-y", "@tech-leads-club/agent-skills-mcp"]
6    }
7  }
8}

之後 agent 內部會看到 4 個 tools：

• list_skills — 列分類
• search_skills — 模糊搜尋（依意圖）
• read_skill — 載入單一 SKILL.md
• fetch_skill_files — 取參考檔（templates / references）

關鍵設計：progressive disclosure。一開始 agent 不知道任何 skill，user 問問題後 agent 才 search 拉相關 skill，避免 context window 浪費。

2.5 路徑 C：clone monorepo 開發

1git clone https://github.com/tech-leads-club/agent-skills.git
2cd agent-skills
3npm install      # Nx 會自動拉所有 workspace
4npm run build    # 建所有 package
5npm run start:dev:cli   # 開發 CLI
6npm run start:dev:mcp   # 開發 MCP server
7npm run generate:skill  # Nx generator 建新 skill
8npm run scan     # 跑 Snyk Agent Scan

3. 核心架構解析

3.1 Monorepo 結構

 1agent-skills/
 2├── packages/
 3│   ├── cli/                    # @tech-leads-club/agent-skills (CLI + React Ink TUI)
 4│   ├── mcp/                    # @tech-leads-club/agent-skills-mcp (MCP server, FastMCP)
 5│   ├── marketplace/            # Next.js 行銷網站 (agent-skills.techleads.club)
 6│   └── skills-catalog/         # 80 個 SKILL.md + 註冊資料 (CDN 發佈)
 7├── libs/
 8│   └── core/                   # 共用核心 (registry、installer、lockfile、shell port)
 9├── tools/
10│   └── skill-plugin/           # Nx generator (建 skill scaffolding)
11└── .github/actions/
12    └── security-scan/          # Snyk Agent Scan composite action

3.2 4 個套件職責對應

flowchart LR
    A[skills-catalog
80 個 SKILL.md] -->|CDN| B[CLI
互動安裝]
    A -->|CDN| C[MCP server
progressive disclosure]
    A -->|靜態生成| D[Marketplace
Next.js 網站]
    E[core lib
registry/installer/lockfile] --> B
    E --> C
    F[skill-plugin
Nx generator] -.->|建腳手架| A
    G[security-scan
GitHub Action] -->|CI 把關| A

3.3 安全分層 (Defense-in-Depth)

flowchart TD
    A[CLI 啟動] --> B[Input sanitization
skill name / agent name 白名單]
    B --> C[CDN fetch
HTTPS + content hash]
    C --> D[Filesystem isolation
禁止跳出 ~/.<agent>/skills/]
    D --> E[Symlink guard
偵測 symlink 攻擊]
    E --> F[Lockfile
atomic write + integrity check]
    F --> G[Audit trail
~/.agent-skills/audit.log]

每一層都在 SECURITY.md 詳細記錄威脅模型與實作位置。

3.4 SKILL.md 標準格式

每個 skill 都有統一 frontmatter，方便註冊器自動索引：

 1---
 2name: react-best-practices
 3description: React and Next.js performance optimization guidelines from Vercel Engineering. Use when writing, reviewing, or refactoring React/Next.js code... Do NOT use for component API architecture or composition patterns (use react-composition-patterns instead).
 4license: MIT
 5metadata:
 6  author: vercel
 7  version: '1.0.0'
 8---
 9
10# Vercel React Best Practices
11
12Comprehensive performance optimization guide ...
13## When to Apply
14...

description 必須符合 [What it does] + [Use when ...] + [Do NOT use for ...] 三段式（CONTRIBUTING.md 規定，< 1024 chars，否則 CI 擋）。這是給 agent 看的 trigger judgment。

4. Helper Scripts 詳細用法

4.1 CLI 子指令清單

 1# 互動模式（最常用）
 2agent-skills
 3
 4# 列出所有可用 skill
 5agent-skills list
 6
 7# 安裝單一 skill
 8agent-skills install --skill react-best-practices
 9
10# 安裝多個 skill
11agent-skills install --skill skill-a skill-b skill-c
12
13# 指定 agent
14agent-skills install --skill react-best-practices --agent claude-code cursor
15
16# 全域安裝（裝到 ~/.gemini, ~/.claude 而非 cwd）
17agent-skills install --skill react-best-practices --global
18
19# 用 symlink 而非 copy（開發者方便修改）
20agent-skills install --skill react-best-practices --symlink
21
22# 強制重抓（跳過 cache）
23agent-skills install --skill react-best-practices --force
24
25# 更新 skill
26agent-skills update                  # 全部
27agent-skills update --skill <name>   # 單一
28
29# 移除
30agent-skills remove --skill <name>
31agent-skills remove --skill <name> --force   # 跳過 lockfile 檢查
32
33# 維護
34agent-skills cache --clear            # 清 ~/.cache/agent-skills/
35agent-skills audit                    # 看 audit log
36agent-skills credits                  # 看貢獻者
37agent-skills --help

4.2 Monorepo 開發指令

 1# Nx 跨 workspace 跑
 2npm run build                # nx run-many -t build
 3npm run test                 # 全套測試
 4npm run lint                 # eslint .
 5npm run format               # prettier --write .
 6
 7# 內容相關
 8npm run generate:skill       # 互動式建新 skill
 9npm run generate:data        # 重建 skills.json（餵 marketplace）
10npm run generate:registry    # 重建 CDN registry
11npm run validate             # 跑 validate-skills.ts 對所有 SKILL.md 做 schema check
12npm run scan                 # Snyk Agent Scan

4.3 MCP server 自架

1# 安裝
2npm i @tech-leads-club/agent-skills-mcp
3
4# 直接跑
5npx @tech-leads-club/agent-skills-mcp
6
7# 或從 monorepo 跑
8npm run start:dev:mcp

啟動時會先做 getRegistry() 拉註冊資料（throws if CDN unavailable），然後 buildIndexes() 建 in-memory 索引，最後 server.start({ transportType: 'stdio' }) 上線。背景每隔 CACHE_TTL_MS 重新 fetch registry 自動更新。

5. 應用場景

5.1 場景 A：個人開發者快速套用

我用 Claude Code 寫 Next.js，想直接套用 Vercel 官方的 React 效能優化指引。

1npx @tech-leads-club/agent-skills install --skill react-best-practices --agent claude-code

裝完，下次 Claude Code 看到你在寫 React，會自動載入 skill 中的 57 條優化規則。

5.2 場景 B：團隊統一 skill baseline

我們團隊 5 人都用 Cursor，想統一導入 spec-driven planning + AWS advisor + security best practices。

1# 寫進 onboard 腳本
2agent-skills install \
3  --skill tlc-spec-driven aws-advisor security-best-practices \
4  --agent cursor

lockfile.json 進 git，新成員 agent-skills install（無 –skill）會依 lockfile 還原所有 skill。

5.3 場景 C：企業 MCP server 集中管控

我們公司禁止員工直接從外部下載 prompt，所有 AI agent 行為都要走內部 server。

1員工 IDE (Claude Code/Cursor)
2    ↓ MCP
3內部 MCP gateway (轉 agent-skills-mcp)
4    ↓ stdio
5@tech-leads-club/agent-skills-mcp (npm 私服 + 內部 patch)
6    ↓ HTTPS
7公司 CDN（mirror skills-catalog）

好處：審計集中、版本控制、可加自訂 skill。

5.4 場景 D：skill 開發者貢獻流程

sequenceDiagram
    participant Dev as Skill 開發者
    participant Repo as agent-skills repo
    participant CI as GitHub Action (Snyk Scan)
    participant Main as Maintainer

    Dev->>Dev: nx g skill-plugin:skill my-skill --category=quality
    Dev->>Dev: 撰寫 SKILL.md (含 use-when/do-not-use)
    Dev->>Dev: npm run validate（local schema check）
    Dev->>Repo: git push + 開 PR
    Repo->>CI: trigger security-scan + skill-validate
    CI-->>Main: ✅ 通過 / ❌ 失敗 + 建議
    Main->>Main: 人工 review (description 品質、定位、與既有 skill 重疊)
    Main->>Repo: merge to main
    Repo->>Repo: semantic-release 自動 publish

6. 資安掃描報告

掃描方法：grep -rE "eval|exec\(|os\.system|shell=True|child_process\.exec|api_key|secret|password=|sk-[A-Za-z0-9]{20}" + 檢視 dependencies + 看 postinstall hooks + 讀 SECURITY.md。

6.1 結論：🟢 LOW RISK

這份專案在資安實踐上 明顯高於平均水準。維護者把 security 視為核心賣點，而非事後補救。

6.2 細項

6.3 已知 advisory

• CVE-2026-27896 (MCP Go SDK)：不適用，本 repo 為 TypeScript，無 Go 代碼（維護者已在 #57 澄清）
• serialize-javascript@6.0.2：build-only transitive，無 runtime 風險，等候 bump 中

6.4 給使用者的建議

1. 可放心使用 npx @tech-leads-club/agent-skills — 攻擊面評估後屬可接受範圍
2. 企業環境：建議走 MCP server 路徑 + 自架 CDN mirror，把外部依賴收斂到自有基礎設施
3. 開發 skill 時：別在 SKILL.md 內藏 prompt injection trigger，Snyk Agent Scan 會擋

7. FAQ

Q1：skill 跟 prompt 有什麼不同？ A：skill 是有 metadata（name / description / use-when）+ 可附 templates / references / scripts 的「打包後 prompt」。Agent 看到觸發詞才載入，省 context window。

Q2：和 Claude Code 內建 plugin / Cursor rules 有衝突嗎？ A：不衝突。CLI 安裝會把 SKILL.md 寫到 agent 各自的 skill 目錄（~/.claude/skills/、.cursor/rules/），由 agent 自己決定何時觸發。

Q3：每次安裝都從 CDN 抓嗎？ A：第一次抓並 cache 在 ~/.cache/agent-skills/；之後檢查 lockfile hash，未改變不重抓。--force 可強制更新。

Q4：MCP server 跟 CLI 哪個比較好？ A：取決於使用模式。

• 偏 靜態使用（裝固定一組 skill）：CLI
• 偏 動態查詢（agent 自己依當下任務找 skill）：MCP server
• 通常兩者並用：CLI 裝核心 skill、MCP 補長尾

Q5：可以自己 fork 維護內部版本嗎？ A：MIT 授權，當然可以。但建議分開 @yourorg/agent-skills namespace，避免與官方 CDN 撞 hash。

Q6：為什麼 root LICENSE 是 “Other”？ A：GitHub 偵測到多份 LICENSE 文件（root + 各 package）就標 Other；實際每個 package 都是 MIT，monorepo root 為 LICENSE 也是 MIT。

8. 進階技巧

8.1 用 lockfile 做 reproducible 安裝

1# 第一次安裝後 lockfile.json 進 git
2agent-skills install --skill skill-a skill-b
3git add ~/.agent-skills/lockfile.json
4git commit -m "lock initial skills"
5
6# 新成員拉 repo 後
7agent-skills install   # 無 --skill 會依 lockfile 還原

8.2 同時裝到多個 agent

1agent-skills install \
2  --skill tlc-spec-driven react-best-practices \
3  --agent claude-code cursor copilot

CLI 會分別寫到三個 agent 的對應目錄，且共享 cache（不重抓）。

8.3 開發中 skill 用 symlink 加速 iteration

1# 在 agent-skills clone 出來
2cd ~/agent-skills/packages/skills-catalog/skills/(quality)/my-skill/
3# 編輯 SKILL.md 後不需重新安裝
4agent-skills install --skill my-skill --symlink
5# agent 直接讀符號連結，即時生效

8.4 用 MCP server 自訂 registry

如果你想跑內部版本：

1# 1. fork skills-catalog
2# 2. 改 CDN URL 環境變數（看 packages/mcp/src/constants.ts）
3AGENT_SKILLS_REGISTRY_URL=https://my-cdn.example.com/registry.json \
4  npx @tech-leads-club/agent-skills-mcp

8.5 跑 Snyk Agent Scan local 驗證自訂 skill

1npm run scan
2# 或單獨對某資料夾
3npx nx run @tech-leads-club/skills-catalog:security-scan -- --skills packages/skills-catalog/skills/(quality)/my-skill

9. 整合進其他工作流

9.1 與本專案的 gh-tutorial-qd 對比

9.2 把 agent-skills 當「skill 來源」整合進 Claude Code

 1# 1. 全域裝 CLI
 2npm i -g @tech-leads-club/agent-skills
 3
 4# 2. 一次性裝核心
 5agent-skills install \
 6  --skill tlc-spec-driven react-best-practices security-best-practices \
 7  --agent claude-code --global
 8
 9# 3. 加 MCP server 配置（~/.claude/mcp.json 或 settings.json）
10# 4. Claude Code 重啟，progressive disclosure 上線

9.3 與 gh-save 工作流的關係

gh-save 把任意 GitHub repo 變成知識卡片進 inbox。agent-skills 把 skill 變成可執行配置進 agent 目錄。前者是知識管理，後者是配置部署。

10. 重點摘要 Checklist

• agent-skills = 受審核的 AI agent skill registry（防 13.4% marketplace 漏洞）
• 4 個套件：CLI / MCP / Marketplace / Skills-catalog（80 個 skill 跨 13 分類）
• 統一 SKILL.md 格式 + 三段式 description（What / Use when / Do NOT use for）
• 安全：靜態分析 + Snyk Agent Scan + path isolation + lockfile + audit trail
• 兩種使用：CLI（靜態安裝） vs MCP server（動態查詢）
• 無 postinstall hooks、無 hard-coded secrets、攻擊面評估 🟢 LOW
• MIT 授權，企業可 fork 自架
• 進階：lockfile reproducible、symlink dev、自訂 CDN

11. 進一步閱讀

• 官方網站：https://agent-skills.techleads.club/
• GitHub repo：https://github.com/tech-leads-club/agent-skills
• 安全政策：SECURITY.md
• 貢獻指南：CONTRIBUTING.md
• MCP server 文件：packages/mcp/README.md
• Snyk Agent Scan：https://github.com/snyk/agent-scan
• MCP 協定規格：https://modelcontextprotocol.io/

Captured：2026-05-18 by gh-tutorial-qd workflow（depth=full / lang=zh-tw / qd_preset=report / security=on）。