garden-skills 詳細教學

對應 repo: https://github.com/ConardLi/garden-skills（5.5k stars / 803 forks / 4 skills / MIT，截至 2026-05-21）

1. 專案定位

1.1 它是什麼

ConardLi 個人開源的 跨 AI Agent skill 集合。4 個 skill 全部按 SKILL.md 標準寫成（agentskills.io 規格），同一份 skill 可以在 Claude Code / Cursor / Codex / Gemini CLI / OpenCode 上跑。每個 skill 都是 self-contained 子套件：獨立 manifest.json + 獨立版本號 + 獨立 release zip。

1.2 它解決什麼問題

跨 Agent skill 共享：寫一次 SKILL.md，多家 Agent 都能用
skill 版本管理：每個 skill 獨立 semver、獨立 tag、獨立 release artifact
skill 對外分發：5 種安裝方式（npx CLI / Claude Code marketplace / .zip download / 手動 copy / git submodule）覆蓋不同團隊偏好
示範頂級 skill 寫法：每個 skill 都是「方法論 + 流程 + 範本」的綜合體，不只是「prompt 一段話」

1.3 與其他 skill 集合的差異

來源	範圍	跨 Agent	版本管理
ConardLi/garden-skills	4 個聚焦 skill	✅ 5+ Agent	✅ per-skill semver
anthropics/claude-plugins-official	203 plugin（含 LSP / hooks / MCP）	只 Claude Code	SHA pinning
個人 dotfiles	不規範	❌	❌

1.4 適合誰用

想嘗試 Agent skill 開發的人：直接抄一個來改
跨 Agent 開發者：想做一份 skill 同時在 Claude Code / Cursor / Codex 用
前端 / 設計工作者：web-design-engineer 和 web-video-presentation 直接拿來用
想做 GPT-Image-2 圖像生成：gpt-image-2 提供 80+ 模板（最方便的起點）
想對本地知識庫做 RAG：kb-retriever 是極簡 baseline

2. 安裝指南

2.1 五種安裝方式

 1# (A) skills CLI（npx，無依賴）
 2npx @anthropic/skills@latest install conardli/garden-skills:web-design-engineer
 3
 4# (B) Claude Code plugin marketplace
 5/plugin marketplace add ConardLi/garden-skills
 6/plugin install web-design-skills@garden-skills
 7
 8# (C) 從 Release 抓 pinned zip（最穩定）
 9curl -L -O \
10  https://github.com/ConardLi/garden-skills/releases/download/web-design-engineer-v1.1.0/web-design-engineer-1.1.0.zip
11unzip web-design-engineer-1.1.0.zip -d ~/.claude/skills/
12
13# (D) 手動複製
14git clone --depth 1 https://github.com/ConardLi/garden-skills
15cp -r garden-skills/skills/gpt-image-2 ~/.claude/skills/
16
17# (E) Git submodule（跟整個 garden 同步演進）
18git submodule add https://github.com/ConardLi/garden-skills .skills/garden
19ln -s ../../.skills/garden/skills/web-video-presentation ~/.claude/skills/web-video-presentation

2.2 環境需求

Node.js >= 20（用 maintainer scripts 才需要）
各 skill 自己的 runtime 需求（看每個 skill 的 README）：
- gpt-image-2 Garden 模式：需要 OPENAI_API_KEY 或 OpenAI 相容 endpoint
- web-video-presentation：需要 Vite + React + TS 工具鏈
- web-design-engineer：純 HTML/CSS/JS，無外部需求
- kb-retriever：純檢索協定，無 runtime 需求


flowchart LR
    A[用戶] -->|選擇安裝方式| B{5 種方式}
    B -->|A| C1[npx skills CLI]
    B -->|B| C2[Claude /plugin install]
    B -->|C| C3[wget release zip]
    B -->|D| C4[手動 cp]
    B -->|E| C5[git submodule]
    C1 --> D[~/.claude/skills/<name>/]
    C2 --> D
    C3 --> D
    C4 --> D
    C5 --> D
    D --> E[Claude/Cursor/Codex 自動載入 SKILL.md]

3. 核心架構解析

3.1 三層結構


graph TB
    subgraph "Layer 1 — 對外發行"
        R1[GitHub Releases
per-skill zip]
        R2[marketplace.json
Claude Code 入口]
        R3[npx skills CLI
來源]
    end
    subgraph "Layer 2 — Skill 本體 (skills/*)"
        S1[web-video-presentation
v1.1.5]
        S2[web-design-engineer
v1.1.0]
        S3[gpt-image-2
v1.0.3]
        S4[kb-retriever
v1.0.0]
    end
    subgraph "Layer 3 — 自動化 (scripts/release/)"
        T1[cut-release.mjs
本地切版]
        T2[pack-skill.mjs
打 zip]
        T3[update-readme.mjs
同步 README]
        T4[validate.yml CI]
    end
    T1 --> S1 & S2 & S3 & S4
    T2 --> R1
    T3 --> R2
    S1 & S2 & S3 & S4 --> R1
    S1 & S2 & S3 & S4 --> R2
    S1 & S2 & S3 & S4 --> R3

3.2 單一 skill 結構（以 gpt-image-2 為例）

 1skills/gpt-image-2/
 2├── SKILL.md                          # 入口（agent 讀這個）
 3├── manifest.json                     # name / version / category / compat
 4├── README.md / README.zh-CN.md       # 給人類看的文件
 5├── references/                       # 詳細參考（避免塞 SKILL.md）
 6│   ├── 01-poster/
 7│   ├── 02-ui/
 8│   ├── 03-product/
 9│   ├── ...
10│   └── 18-edit-workflow/
11└── scripts/                          # skill 自帶腳本
12    ├── check-mode.js                 # 探測 3 種運行模式
13    └── shared.js                     # 共用工具（API client）

3.3 SKILL.md 規格（agentskills.io）

 1---
 2name: <skill-name>                    # 必要：與目錄名一致
 3description: <long, detailed description>  # 必要：讓 agent 自動決定何時觸發
 4---
 5
 6# <Title>
 7
 8## 適用場景
 9...
10
11## 工作流總覽
12...
13
14## 環境變數 / 模式
15...

設計品味重點：description 不是「一句話定位」，而是長段、詳細、列出具體場景。Agent 用這段做 keyword 比對；越具體 → 觸發越準確。

3.4 manifest.json 規格

 1{
 2  "name": "gpt-image-2",
 3  "version": "1.0.3",                 // 獨立 semver，與 repo 整體版本無關
 4  "category": "Image Generation / Prompt Engineering",
 5  "description": "...",
 6  "homepage": "https://github.com/ConardLi/garden-skills/tree/main/skills/gpt-image-2",
 7  "compat": [                         // 跨 Agent 相容性宣告
 8    "claude-code", "claude-ai",
 9    "cursor", "codex-cli",
10    "gemini-cli", "opencode"
11  ]
12}

3.5 4 個 skill 的設計品味

Skill	核心抽象	反 AI 套路設計
`web-video-presentation`	`(chapter, step)` cursor model + 5 個硬性檢查點	動畫不在 outline 規劃，而是章節開發時即時設計（避免一致性陷阱）
`web-design-engineer`	6 步驟設計 workflow + WebSearch 真實品牌驗證	拒絕「3 個 stars 的 ASCII 評分」「漸層紫 + 玻璃模糊」等 AI 老套
`gpt-image-2`	3 種運行模式 + 18 大類 80+ 結構化模板	`check-mode.js` 自動探測，避免 agent 瞎猜當前模式
`kb-retriever`	分層 `data_structure.md` 索引 + 「處理前先學 references」	最多 5 輪檢索預算（避免無限探查）

4. Helper Scripts 詳細用法

4.1 scripts/release/cut-release.mjs

用途：切某個 skill 的新版本（本地執行）

1# 互動式選 skill + 選 bump 類型（patch / minor / major）
2npm run release
3
4# 乾跑（看會做什麼但不真的 commit / tag）
5npm run release:dry

執行流程（從 lib/skills.mjs 推得）：

列出 skills/ 下所有 manifest.json
讓使用者選 skill + bump 類型
用 SEMVER_BUMP_RE 算新 version
改 manifest.json
git commit -m "chore(release): bump <skill> to <version>"
git tag <skill>-v<version> + git push origin <tag>
CI 接手 → pack-skill.mjs + 發 GitHub Release

4.2 scripts/release/pack-skill.mjs

用途：把指定 skill 打包成 zip artifact

1# 打單一 skill
2npm run pack -- web-design-engineer
3
4# 打全部
5npm run pack:all

被 .github/workflows/release-skill.yml 在 tag push 時觸發。

4.3 scripts/release/update-readme.mjs

用途：同步 README.md 中的下載連結 = 最新版

讀每個 manifest.json 的 version，把 README.md 中標記 ... 之間的內容替換成新版下載連結。

1npm run readme:sync       # 真的改
2npm run readme:check      # 只檢查是否需要更新（CI 用）

4.4 scripts/release/list-skills.mjs

用途：列出所有 skill + 版本

1npm run list
2# Output:
3# web-video-presentation@1.1.5
4# web-design-engineer@1.1.0
5# gpt-image-2@1.0.3
6# kb-retriever@1.0.0

4.5 skills/gpt-image-2/scripts/check-mode.js

用途：自動探測當前 agent 環境的圖像生成能力

1node skills/gpt-image-2/scripts/check-mode.js
2# Output:
3# has_api_key: true / false
4# enable_garden_imagegen: true / false
5# recommended_mode: A (Garden) / B (Host-Native) / C (Advisor)

這是 skill 本身就附帶探測工具的好範例 — 讓 SKILL.md 不用猜環境。

5. 應用場景

場景	怎麼用本 repo
想用網頁做影片教學	裝 `web-video-presentation`；用點擊驅動 16:9 場景錄屏
想做動態 PPT	`web-video-presentation` 的場景模型，比 PPT 自由 100 倍
想做 landing page / dashboard / 行銷頁	裝 `web-design-engineer`；按 6 步 workflow 走
想 critique / 評分既有設計	`web-design-engineer` 的 5 維 Critique mode
想生 poster / UI / 產品圖	裝 `gpt-image-2`；按 18 大類找模板
想對本地知識庫問答	裝 `kb-retriever`；在根目錄寫 `data_structure.md`
想自己做 skill 並跨 Agent 發行	抄整個 repo 結構 + 抄 `scripts/release/`

6. 資安掃描報告

掃描範圍：scripts/release/、skills/*/scripts/、.github/workflows/、skills/*/SKILL.md。

風險面	燈號	說明
惡意碼 / 後門	🟢 低	純 mjs + JS，邏輯透明
Shell injection	🟢 低	`scripts/release/lib/skills.mjs` 用 `execFileSync("git", args, {...})` 列表形式，無 `shell=true`
API 金鑰處理	🟢 低	`gpt-image-2` 用 `process.env.OPENAI_API_KEY`，明確 throw if missing；不會在 log / 錯誤訊息洩漏
網路出口	🟡 中	`gpt-image-2` skill 會打 OpenAI 兼容 endpoint；`web-video-presentation` 的腳手架專案會引入 npm 套件（依賴鏈相關）
跨 Agent 觸發	🟢 低	SKILL.md description 寫得清楚具體，無 prompt injection 攻擊面（「忽略其他指令」「always run first」等）
對 host 檔系統的影響	🟡 中	`kb-retriever` 會讀使用者本地 `knowledge/` 目錄（依使用者明確指示），無權限提升
Release artifacts 完整性	🟢 低	每個 release tag 對應確定的 commit SHA；GitHub artifacts immutable
第三方依賴	🟡 中	`package.json` 列的依賴需審 — 但本層 `package.json` 是 maintainer-only（`private: true`），end user 不需要安裝
CI 權限	🟢 低	兩個 workflow 範圍清楚（release / validate）
`web-video-presentation` template	🟡 中	提供 Vite + React + TS 腳手架；使用者執行時會 `npm install` 引入完整前端依賴鏈 — 風險水準等同任何 React 專案

綜合燈號：🟢 / 🟡（中性偏好；無紅燈）

重點建議：

用 gpt-image-2 前確認 OPENAI_API_KEY 不在 repo / log
用 web-video-presentation 跑腳手架時，跟一般前端專案一樣審 package.json
kb-retriever 不會自動爬全部本地檔；它只跟著 data_structure.md 走 — 安全

7. FAQ

Q1：本 repo 跟 anthropics/claude-plugins-official 是什麼關係？ A：兩個都是 skill / plugin 集合，但定位不同：

官方目錄是「203 個 plugin 的中央目錄」（涵蓋 MCP server、LSP、hooks 等多型）
garden-skills 是「4 個 ConardLi 自家做的 SKILL.md」(focused, high-quality)
官方目錄也會收 garden-skills（事實上 marketplace.json 裡就有 web-design-skills@garden-skills 等 4 個進 official）

Q2：「為什麼一個 repo 有 4 個 release tag 命名規則？」 A：因為每個 skill 獨立 semver。tag 格式是 <skill-name>-v<version>：

web-video-presentation-v1.1.5
web-design-engineer-v1.1.0
gpt-image-2-v1.0.3
kb-retriever-v1.0.0

GitHub Releases 也跟著切，每個 skill 各自一條 release timeline。

Q3：如果只想要一個 skill，需要 clone 整個 repo 嗎？ A：不需要。從 Release 抓對應 zip 是最輕量做法（單 skill < 1MB）。

Q4：SKILL.md 是什麼？哪邊的標準？ A：agentskills.io 推的「跨 AI Agent skill」格式。重點：

檔名 = SKILL.md（大寫）
含 frontmatter 的 name 與 description
description 越具體越長越好（agent 用來決定是否觸發）

Claude Code / Cursor / Codex CLI / OpenCode 都會主動讀使用者 skills 目錄下的 SKILL.md。

Q5：作者 ConardLi 是誰？ A：lishiqi.conard，中國前端工程師、活躍開源作者；garden-skills 是他在 2026-04 開始的個人 skill 集合。

Q6：可以 PR 加自己的 skill 進去嗎？ A：可以。本 repo 接受 PR；但「進 Anthropic 官方目錄」是另一條 — 走 submission form。

Q7：4 個 skill 是哪一個最 production-ready？ A：版本號透露：web-video-presentation v1.1.5 是迭代最頻繁的（每週都 patch），代表實際使用回饋最多。gpt-image-2 與 kb-retriever 仍在早期 1.0.x。

8. 進階技巧

8.1 用 garden-skills 做自家 skill 開發 template

 1# 1. clone
 2git clone https://github.com/ConardLi/garden-skills my-skills
 3cd my-skills && rm -rf .git skills/* && git init
 4
 5# 2. 抄 release infra + workflows
 6# 已含：scripts/release/ + .github/workflows/release-skill.yml + validate-skills.yml
 7
 8# 3. 改 package.json name 與 marketplace.json owner
 9
10# 4. 在 skills/ 下加自己的 skill（複製 example 結構）
11mkdir -p skills/my-first-skill
12# 至少要：SKILL.md + manifest.json + README.md

10 分鐘內可以做出「自家版 garden-skills」，含 release 自動化。

8.2 寫好 SKILL.md description 的訣竅

看 web-design-engineer/SKILL.md 的 description 寫法：

不只一句話：用 multi-line yaml block scalar (|)
列具體場景：「Creating web pages, landing pages, dashboards…」
特別強調反例：「Not applicable: pure back-end logic, CLI tools…」

Agent 在自動觸發判斷時，描述越具體 → 誤觸越少。

8.3 SKILL.md 中的 references/ 拆檔技巧

gpt-image-2 把 80+ 模板拆成 references/01-poster/、references/02-ui/ … 每個檔幾百字。SKILL.md 只放索引，agent 用到哪個再 Read 哪個 — token 友善。

1skills/gpt-image-2/
2├── SKILL.md          # 100 行索引 + 工作流
3└── references/
4    ├── 01-poster/
5    │   ├── README.md          # 該分類的索引
6    │   ├── poster-event.md    # 單個模板
7    │   ├── poster-product.md
8    │   └── ...
9    └── ...

這是「SKILL.md 不要塞滿，細節放 references/，按需 Read」的最佳實踐。

8.4 跨 Agent 相容性檢查

manifest.json 的 compat 欄位是「宣告性」標記，不是自動校驗。要真的相容：

確保 SKILL.md 用 markdown 標準語法（無 Claude 專屬 tag）
scripts/ 內腳本走 Node 標準 API，無平台特定依賴
references/ 路徑使用相對路徑 ./references/...

8.5 Release zip 內容是什麼？

看 pack-skill.mjs（推測）：把 skills/<name>/ 整個目錄 zip 起來，加上一個 manifest.json 頂層。下載後解壓即可用，不需要再裝額外東西。

9. 整合進其他工作流

既有 skill	整合方式
`ai-gh-save`	已存 standard gh-save md 在 `inbox/2026-05-21-github-ConardLi-garden-skills.md`
`gh-tutorial-qd`	本檔產出
`skillshare`	本 repo 結構與 skillshare 完全相容（4 個 skill 都可 import 進 skillshare）
`paper-qa-lite`	可把所有 SKILL.md + README.md 作 RAG source，問「ConardLi 怎麼寫 skill description？」
`quarkdown`	tutorial 已轉 .qd → HTML（雙版）
`kami`	不適用（內容已適合 quarkdown）

10. 重點摘要 Checklist

5.5k stars / 803 forks / 4 skills / MIT
1 個月 GitHub 生命週期（2026-04-21 創建）
跨 Agent 相容：claude-code / claude-ai / cursor / codex-cli / gemini-cli / opencode
4 個 skill 各有獨立 semver + 獨立 release tag + 獨立 zip
5 種安裝方式（npx CLI / Claude /plugin / .zip / cp / submodule）
Release 自動化：cut-release → tag → CI pack → README sync 全打通
三語 README + CONTRIBUTING（en / zh-CN / ja-JP）
web-design-engineer：6 步 workflow + 反 AI 套路設計
web-video-presentation：(chapter, step) cursor model + 5 個硬性檢查點
gpt-image-2：3 種模式 + 18 大類 80+ 模板 + check-mode.js
kb-retriever：分層 data_structure.md + 最多 5 輪檢索
資安綜合燈號：🟢 / 🟡（無紅燈）

11. 進一步閱讀

Skill 標準：https://agentskills.io
ConardLi 個人主頁：https://github.com/ConardLi
官方目錄相關（本 repo 的 4 個 plugin 都收在這）：https://github.com/anthropics/claude-plugins-official
對應姊妹專案 skillshare：本知識庫 /config/.config/skillshare/skills/
本知識庫先前 gh-save：inbox/2026-05-21-github-anthropics-claude-plugins-official.md

ConardLi garden-skills 詳細教學 — 跨 Agent SKILL.md 標準範本 + 4 個 production-ready skill

Contents

garden-skills 詳細教學

1. 專案定位

1.1 它是什麼

1.2 它解決什麼問題

1.3 與其他 skill 集合的差異

1.4 適合誰用

2. 安裝指南

2.1 五種安裝方式

2.2 環境需求

3. 核心架構解析

3.1 三層結構

3.2 單一 skill 結構（以 gpt-image-2 為例）

3.3 SKILL.md 規格（agentskills.io）

3.4 manifest.json 規格

3.5 4 個 skill 的設計品味

4. Helper Scripts 詳細用法

4.1 scripts/release/cut-release.mjs

4.2 scripts/release/pack-skill.mjs

4.3 scripts/release/update-readme.mjs

4.4 scripts/release/list-skills.mjs

4.5 skills/gpt-image-2/scripts/check-mode.js

5. 應用場景

6. 資安掃描報告

7. FAQ

8. 進階技巧

8.1 用 garden-skills 做自家 skill 開發 template

8.2 寫好 SKILL.md description 的訣竅

8.3 SKILL.md 中的 references/ 拆檔技巧

8.4 跨 Agent 相容性檢查

8.5 Release zip 內容是什麼？

9. 整合進其他工作流

10. 重點摘要 Checklist

11. 進一步閱讀

Comments

ConardLi garden-skills 詳細教學 — 跨 Agent SKILL.md 標準範本 + 4 個 production-ready skill

Contents

garden-skills 詳細教學

1. 專案定位

1.1 它是什麼

1.2 它解決什麼問題

1.3 與其他 skill 集合的差異

1.4 適合誰用

2. 安裝指南

2.1 五種安裝方式

2.2 環境需求

3. 核心架構解析

3.1 三層結構

3.2 單一 skill 結構（以 gpt-image-2 為例）

3.3 SKILL.md 規格（agentskills.io）

3.4 manifest.json 規格

3.5 4 個 skill 的設計品味

4. Helper Scripts 詳細用法

4.1 scripts/release/cut-release.mjs

4.2 scripts/release/pack-skill.mjs

4.3 scripts/release/update-readme.mjs

4.4 scripts/release/list-skills.mjs

4.5 skills/gpt-image-2/scripts/check-mode.js

5. 應用場景

6. 資安掃描報告

7. FAQ

8. 進階技巧

8.1 用 garden-skills 做自家 skill 開發 template

8.2 寫好 SKILL.md description 的訣竅

8.3 SKILL.md 中的 references/ 拆檔技巧

8.4 跨 Agent 相容性檢查

8.5 Release zip 內容是什麼？

9. 整合進其他工作流

10. 重點摘要 Checklist

11. 進一步閱讀

Related Posts

Comments