# Skill Creator

> Create, edit, improve, or audit AgentSkills. Use when creating a new skill from scratch or when asked to improve, review, audit, tidy up, or clean up an existing skill or SKILL.md file. Also use when editing or restructuring a skill directory.

- Skill: `agenvoy/skill-creator` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add agenvoy/skill-creator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/agenvoy/skill-creator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: agenvoy (https://skillmd.com/u/agenvoy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/agenvoy/skill-creator

---


> **本 Skill 為 Agenvoy 內部最佳化版本**，依 Agenvoy 的執行環境撰寫（`run_command` 的 CWD、`~/.config/agenvoy/skills/.system/` 安裝位置、`edit_skill`／`schedules`／`find_edit_tool` 等工具、subagent 與排程的觸發路徑），**不保證適配其他 AI harness**。

# Skill 建立器

> **儲存位置（`--path`）**：依用途選，**不要寫死**。Skill scanner 會掃下列位置，任一處都會被載入：
>
> | 用途 | `--path` |
> |---|---|
> | Agenvoy 全域（預設）| `~/.config/agenvoy/skills` |
> | 跨工具共用（Claude Code 也要看得到）| `~/.claude/skills` |
> | 只服務單一專案 | `<專案根>/.skills` 或 `<專案根>/.claude/skills` —— **有前提，見下** |
>
> 使用者沒指定時問一次再決定；把只服務單一專案的 Skill 塞進全域會污染每個 session 的 Skill 清單，反之放進專案目錄則換專案就用不到。
>
> **專案目錄的前提**：scanner 的 `<專案根>` 取自**行程啟動當下**的 `os.Getwd()`（`internal/runtime/skill.go:35`），之後不再更新。從專案目錄啟動的 TUI 讀得到；但 daemon 由 launchd／systemd 啟動時 cwd 是 `$HOME`，所以**排程、Web、Telegram、Discord 觸發的執行讀不到專案目錄的 Skill**。要被那些入口用到就別放專案目錄。
>
> （scanner 另外也掃 `~/.codex/skills`、`~/.opencode/skills`、`~/.openai/skills`，但那些是別的 harness 的位置，本 Skill 不往那裡寫。）

> **本 Skill 自己的腳本路徑**：`run_command` 的 CWD 是使用者的工作目錄，**不是本 Skill 目錄**，相對路徑 `scripts/...` 必定找不到（實測會讓 agent 反覆 glob 找檔案，白燒數輪）。本 Skill 只服務 Agenvoy、安裝位置固定，一律用絕對路徑 `~/.config/agenvoy/skills/.system/skill-creator/scripts/`。

> **⚠️ 強制執行規則（不可繞過）**：
> - **建立全新 Skill** — 禁止直接用 `write_file` 建立目錄或 SKILL.md，必須先以 `run_command` 執行 `~/.config/agenvoy/skills/.system/skill-creator/scripts/init_skill.py`初始化目錄結構，再用 `edit_skill(mode=write)` 或 `edit_skill(mode=patch)` 編輯產生的模板內容。跳過此步驟會導致目錄結構錯誤（生成 `skill-name.md` 而非 `skill-name/SKILL.md`）。
> - **編輯現有 Skill** — 直接使用 `edit_skill(mode=write)` 或 `edit_skill(mode=patch)` 修改 `skill-name/SKILL.md` 及其資源檔案，不需要執行 `init_skill.py`。

此 Skill 提供建立有效 Skill 的完整指引。

## 關於 Skill

Skill 是模組化、自包含的套件，透過提供專業知識、工作流程與工具來擴充 Agent 的能力。可將其視為特定領域或任務的「入職指南」——讓 Agent 從通用助手轉變為配備程序性知識的專業 Agent，而這些知識是模型本身無法完全具備的。

### Skill 提供什麼

1. 專業化工作流程 — 特定領域的多步驟程序
2. 工具整合 — 操作特定檔案格式或 API 的指引
3. 領域專業知識 — 公司特定知識、資料 Schema、業務邏輯
4. 打包資源 — 用於複雜且重複任務的腳本、參考文件與靜態資源

## 核心原則

### 精簡為王

Context Window 是公共資源。Skill 與其他所有內容共享 Context Window：System Prompt、對話歷史、其他 Skill 的 Metadata 以及實際的使用者請求。

**預設假設：Agent 已經非常聰明。** 只加入 Agent 本身沒有的 Context。對每一條資訊提出質疑：「Agent 真的需要這個說明嗎？」「這段文字值得佔用的 Token 成本嗎？」

優先使用精簡範例，而非冗長說明。

### 設定適當的自由度

根據任務的脆弱性與變異性，匹配對應的指令精確度：

**高自由度（純文字指令）**：當多種方式都有效、決策依賴 Context、或啟發式方法引導流程時使用。

**中等自由度（Pseudo-code 或帶參數的腳本）**：當存在偏好模式、允許部分變化、或設定會影響行為時使用。

**低自由度（特定腳本、少量參數）**：當操作脆弱且易出錯、一致性至關重要、或必須遵循特定順序時使用。

將 Agent 視為探索路徑：有懸崖的窄橋需要明確護欄（低自由度），而開闊的原野允許多種路線（高自由度）。

### Skill 的結構

每個 Skill 由必要的 SKILL.md 與選用的打包資源組成：

```
skill-name/
├── SKILL.md（必要）
│   ├── YAML Frontmatter Metadata（必要）
│   │   ├── name:（必要）
│   │   └── description:（必要）
│   └── Markdown 指令（必要）
└── 打包資源（選用）
    ├── scripts/      — 可執行程式碼（Python/Bash 等）
    ├── references/   — 依需求載入 Context 的參考文件
    └── assets/       — 輸出中使用的檔案（模板、圖示、字型等）
```

#### SKILL.md（必要）

每個 SKILL.md 由以下部分組成：

- **Frontmatter**（YAML）：包含 `name` 與 `description` 欄位。這是 Agent 判斷何時使用此 Skill 的唯一依據，因此必須清楚且完整地描述 Skill 的功能與觸發時機。
- **Body**（Markdown）：使用 Skill 的指令與指引。僅在 Skill 觸發後才載入。

#### 打包資源（選用）

##### Scripts（`scripts/`）

需要確定性可靠度或會被反覆重寫的任務所需可執行程式碼（Python/Bash 等）。

- **何時納入**：當相同程式碼被反覆重寫，或需要確定性可靠度時
- **範例**：`scripts/rotate_pdf.py` 用於 PDF 旋轉任務
- **優點**：Token 效率高、確定性強、可不載入 Context 直接執行
- **注意**：腳本仍可能需要被 Agent 讀取以進行 Patch 或環境特定調整
- **邊界**：這裡的腳本只服務這個 Skill 自己，用 `edit_skill(mode=write)` 寫進該 Skill 的 `scripts/`。**不要**用 `edit_tool` 產全域 `script_*`／`api_*` 工具 —— 那是 tool generate 的職責，兩者不混用：全域工具的 description 每個 session 每次請求都付 Token，而且刪掉 Skill 時不會一併清掉，會留成孤兒

##### References（`references/`）

依需求載入 Context 的文件與參考資料，用於指引 Agent 的思考過程。

- **何時納入**：當有 Agent 在工作時應參考的文件
- **範例**：`references/finance.md`（財務 Schema）、`references/mnda.md`（公司 NDA 模板）、`references/policies.md`（公司政策）、`references/api_docs.md`（API 規格）
- **使用場景**：資料庫 Schema、API 文件、領域知識、公司政策、詳細工作流程指南
- **優點**：保持 SKILL.md 精簡，僅在需要時載入
- **最佳實踐**：若檔案較大（超過 10k 字），在 SKILL.md 中加入 grep 搜尋模式
- **避免重複**：資訊應存於 SKILL.md 或 references 檔案其中一處，不兩者都放

##### Assets（`assets/`）

不載入 Context，而是在 Agent 輸出中使用的檔案。

- **何時納入**：當 Skill 需要用於最終輸出的檔案時
- **範例**：`assets/logo.png`（品牌資源）、`assets/slides.pptx`（PowerPoint 模板）、`assets/frontend-template/`（HTML/React 樣板）、`assets/font.ttf`（字型）
- **使用場景**：模板、圖片、圖示、樣板程式碼、字型、會被複製或修改的範例文件
- **優點**：將輸出資源與文件分離，讓 Agent 無需載入 Context 即可使用檔案

#### 不應納入 Skill 的內容

Skill 只應包含直接支援其功能的必要檔案。**不要**建立多餘的文件或輔助檔案，包含：

- README.md
- INSTALLATION_GUIDE.md
- QUICK_REFERENCE.md
- CHANGELOG.md
- 等等

Skill 只應包含 AI Agent 完成任務所需的資訊，不應包含建立過程說明、測試程序、面向使用者的文件等輔助 Context。

### 漸進式揭露設計原則

Skill 使用三層載入系統，有效管理 Context：

1. **Metadata（name + description）** — 始終在 Context 中（約 100 字）
2. **SKILL.md body** — Skill 觸發時載入（<5k 字）
3. **打包資源** — 由 Agent 依需求載入（無限制，腳本可不讀入 Context 直接執行）

#### 漸進式揭露模式

保持 SKILL.md body 精簡且在 500 行以內，避免 Context 膨脹。接近上限時拆分至獨立檔案。拆分後務必在 SKILL.md 中明確引用，並說明何時應讀取這些檔案。

**核心原則**：當 Skill 支援多種變體、框架或選項時，SKILL.md 只保留核心工作流程與選擇指引，將變體的細節移至獨立參考檔案。

> 以下兩個模式區塊裡的檔名（`FORMS.md`、`REFERENCE.md`、`EXAMPLES.md`、`DOCX-JS.md`、`REDLINING.md`、`OOXML.md`）**是示意用的假檔名，不是本 Skill 附帶的檔案**，不要去讀取它們。

**模式一：高層次指南加引用**

```markdown
# PDF 處理

## 快速開始

使用 pdfplumber 提取文字：
[程式碼範例]

## 進階功能

- **表單填寫**：完整指南請見 [FORMS.md](FORMS.md)
- **API 參考**：所有方法請見 [REFERENCE.md](REFERENCE.md)
- **範例**：常見模式請見 [EXAMPLES.md](EXAMPLES.md)
```

Agent 只在需要時載入 FORMS.md、REFERENCE.md 或 EXAMPLES.md。

**模式二：領域特定組織**

對於支援多個領域的 Skill，依領域組織內容，避免載入無關 Context：

```
bigquery-skill/
├── SKILL.md（概覽與導覽）
└── reference/
    ├── finance.md（營收、帳務指標）
    ├── sales.md（商機、Pipeline）
    ├── product.md（API 使用、功能）
    └── marketing.md（廣告活動、歸因）
```

使用者詢問銷售指標時，Agent 只讀取 sales.md。

**模式三：條件式細節**

展示基本內容，連結進階內容：

```markdown
# DOCX 處理

## 建立文件

使用 docx-js 建立新文件。請見 [DOCX-JS.md](DOCX-JS.md)。

## 編輯文件

簡單編輯可直接修改 XML。

**追蹤修訂**：請見 [REDLINING.md](REDLINING.md)
**OOXML 細節**：請見 [OOXML.md](OOXML.md)
```

**重要指引：**

- **避免深層巢狀引用** — 引用層級保持在 SKILL.md 的一層以內
- **結構化較長的參考檔案** — 超過 100 行的檔案，頂部加入目錄

## Skill 建立流程

建立 Skill 包含以下步驟：

1. 透過具體範例理解 Skill 的使用情境
2. 規劃可重用的 Skill 內容（scripts、references、assets）
   - 含「工具／Skill 搭配探索」：動手寫 `scripts/` 前先確認有沒有現成的可用
3. 初始化 Skill（執行 python3 ~/.config/agenvoy/skills/.system/skill-creator/scripts/init_skill.py）
4. 編輯 Skill（實作資源並撰寫 SKILL.md）
5. 打包 Skill（執行 package_skill.py）
6. 依實際使用回饋迭代改善

依序執行這些步驟，只有在明確不適用時才跳過。

### Skill 命名

- 只使用小寫字母、數字與連字號；將使用者提供的名稱正規化為 hyphen-case（例如 "Plan Mode" → `plan-mode`）
- 名稱限制在 64 字元以內（字母、數字、連字號）
- 優先使用動詞開頭的短句描述動作
- 當能提升清晰度或觸發準確性時，以工具命名空間前綴（例如 `gh-address-comments`、`linear-address-issue`）
- Skill 目錄名稱與 Skill 名稱完全一致

### 步驟一：透過具體範例理解 Skill

只有在 Skill 使用模式已非常清楚時才跳過此步驟。即使是改善現有 Skill，此步驟仍有價值。

要建立有效的 Skill，需清楚理解 Skill 的具體使用範例。這些理解可來自使用者直接提供的範例，或由生成後請使用者驗證的範例。

例如，建立 image-editor Skill 時，相關問題包括：

- 「image-editor Skill 應支援哪些功能？編輯、旋轉，還有其他？」
- 「你能舉幾個使用此 Skill 的範例嗎？」
- 「我想像使用者可能會說『去除這張圖片的紅眼』或『旋轉這張圖片』。你還想到其他使用方式嗎？」
- 「使用者說什麼話應該觸發此 Skill？」

以 `ask_user` **tool call** 收集這些資訊；`questions` 是 array，當下所有想問的寫成多題一起送，答案本身引出的新問題再追問。

當對 Skill 應支援的功能有清楚認識時，結束此步驟。

### 步驟二：規劃可重用的 Skill 內容

要將具體範例轉化為有效的 Skill，對每個範例進行以下分析：

1. 思考如何從零開始執行此範例
2. 識別重複執行這些工作流程時，哪些 scripts、references 和 assets 會有幫助

範例：建立 `pdf-editor` Skill 處理「幫我旋轉這個 PDF」類的請求，分析顯示：

1. 旋轉 PDF 每次都需要重寫相同的程式碼
2. 一個 `scripts/rotate_pdf.py` 腳本存放在 Skill 中會很有幫助

範例：設計 `frontend-webapp-builder` Skill 處理「幫我建立一個待辦事項 App」類的請求，分析顯示：

1. 撰寫前端 WebApp 每次都需要相同的 HTML/React 樣板
2. 一個包含樣板的 `assets/hello-world/` 目錄存放在 Skill 中會很有幫助

範例：建立 `big-query` Skill 處理「今天有多少使用者登入？」類的請求，分析顯示：

1. 查詢 BigQuery 每次都需要重新探索 Table Schema 與關聯
2. 一個記錄 Table Schema 的 `references/schema.md` 存放在 Skill 中會很有幫助

### 步驟二點五：工具／Skill 搭配探索

在動手寫 `scripts/` 之前，先確認要做的事是否已有現成的 Skill 或 Tool。重寫一份等於多一份要維護，而且會與原版各自漂移。

**探索順序**（禁止跳過直接寫 script）：

1. **讀 System Prompt 的 `## Skills` 區段**（Context 內已有）：把步驟一整理的使用情境對照既有 Skill 的 `description`。命中就在 SKILL.md 引用 `/<skill-name>`，只補這個 Skill 特有的前後處理，不要把對方的流程抄一遍。
2. **`find_edit_tool(mode=search)` 找現成 Tool**：抽出使用情境的動詞逐個搜尋，回傳的 Tool 名稱才能寫進 SKILL.md。

   ```
   find_tools({"mode": "search", "query": "rotate pdf"})
   find_tools({"mode": "search", "query": "pdf page"})
   ```

3. **兩者都沒有，才寫 `scripts/`**：用 `edit_skill(mode=write)` 寫進**這個 Skill 自己的** `scripts/`（邊界見「打包資源 → Scripts」）。**不要**用 `edit_tool` 產全域工具。

**判定原則**：

| 情境 | SKILL.md 怎麼寫 |
|---|---|
| 有現成 Skill | 引用 `/<skill-name>`，只補本 Skill 特有的前後處理 |
| 無 Skill 但有 Tool | 直接寫 Tool 名稱與參數 |
| 兩者都無 | 寫 `scripts/<name>.py`，SKILL.md 寫執行方式與預期輸出 |

### 步驟三：初始化 Skill

此時可以開始實際建立 Skill。

只有在 Skill 已存在且需要迭代或打包時才跳過此步驟，此時繼續下一步驟。

從零建立新 Skill 時，務必執行 `python3 ~/.config/agenvoy/skills/.system/skill-creator/scripts/init_skill.py` 腳本。此腳本會自動生成包含所有必要元素的 Skill 模板目錄。

用法：

```bash
python3 ~/.config/agenvoy/skills/.system/skill-creator/scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets] [--examples]
```

範例：

```bash
python3 ~/.config/agenvoy/skills/.system/skill-creator/scripts/init_skill.py my-skill --path ~/.config/agenvoy/skills
python3 ~/.config/agenvoy/skills/.system/skill-creator/scripts/init_skill.py my-skill --path ~/.claude/skills --resources scripts,references
python3 ~/.config/agenvoy/skills/.system/skill-creator/scripts/init_skill.py my-skill --path <專案根>/.skills --resources scripts --examples
```

此腳本會：

- 在指定路徑建立 Skill 目錄
- 生成含適當 Frontmatter 與 TODO 佔位符的 SKILL.md 模板
- 根據 `--resources` 選擇性建立資源目錄
- 設定 `--examples` 時選擇性新增範例檔案

初始化後，自訂 SKILL.md 並依需求新增資源。若使用了 `--examples`，請替換或刪除佔位符檔案。

### 步驟四：編輯 Skill

編輯新生成或現有的 Skill 時，請記住此 Skill 是為另一個 Agent 實例所建立的。納入對 Agent 有益且非顯而易見的資訊。思考哪些程序性知識、領域特定細節或可重用資源，能幫助另一個 Agent 實例更有效地執行這些任務。

#### 從可重用 Skill 內容開始

從上方識別的可重用資源開始實作：`scripts/`、`references/` 和 `assets/` 檔案。注意此步驟可能需要使用者輸入，例如使用者可能需要提供品牌資源或文件。

新增的腳本必須實際執行測試，確認沒有 Bug 且輸出符合預期。若有許多類似腳本，只需測試代表性樣本即可。

若使用了 `--examples`，刪除不需要的佔位符檔案。只建立實際需要的資源目錄。

#### 更新 SKILL.md

**撰寫指引**：始終使用祈使式／原形動詞。

##### Frontmatter

撰寫含 `name` 與 `description` 的 YAML Frontmatter：

- `name`：Skill 名稱
- `description`：這是 Skill 的主要觸發機制
  - 同時包含 Skill 的功能描述與使用時機/Context
  - 所有「何時使用」的資訊放在這裡，不放在 body 中。body 在觸發後才載入，因此 body 中的「何時使用此 Skill」區段對 Agent 沒有幫助
  - **長度限制：不超過 256 個字元（Unicode rune）**
  - 範例 docx Skill 的 description：「提供全面的文件建立、編輯與分析，支援追蹤修訂、註解、格式保留與文字提取。當需要處理 .docx 檔案時使用：建立新文件、修改或編輯內容、處理追蹤修訂或新增註解」

不要在 YAML Frontmatter 中包含其他欄位。

##### Body

撰寫使用 Skill 及其打包資源的指令。

##### Secret／API Key

若 Skill 需要 token、API key 或其他 secret：

- **命名格式**：`{品牌}_API_KEY`（SCREAMING_SNAKE_CASE），例 `OPENAI_API_KEY`、`CODEX_API_KEY`、`POLYGON_API_KEY`、`STAGING_API_KEY`
- **儲存位置**：macOS keychain 中 **service = `agenvoy`**、**account = key 名**，組合識別 `agenvoy.{key}`（例 `agenvoy.OPENAI_API_KEY`）
- **取值方式**：
  - Go 內部：`keychain.Get("<KEY_NAME>")`（只傳 key 名，無 `agenvoy.` 前綴）
  - Script tool：`GET http://localhost:17989/v1/key?key=<KEY_NAME>`
  - API tool（registry）：`auth.env: "<KEY_NAME>"`
- **落地動作**：建立 Skill 時若需要新 key，呼叫 `store_secret({ key: "<KEY_NAME>", prompt: "..." })`；該 tool 內部走遮罩輸入 + `keychain.Set`，**Skill 全程不見明文**

**禁止**：
- 在 SKILL.md frontmatter／body／scripts／assets 任何位置寫死 token 值
- 在 Skill 參數 schema 暴露 plaintext secret 欄位讓 LLM 收明文
- 走 `ask_user` 取 plaintext 再轉手 `store_secret`（會把 value 帶進 LLM context／history／action.log）
- 指導使用者用 `export ENV=value` 之類 shell 環境變數路徑取代 keychain

### 步驟五：打包 Skill

Skill 開發完成後，必須打包為可分發的 .skill 檔案。打包過程會自動先驗證 Skill，確保符合所有要求：

```bash
~/.config/agenvoy/skills/.system/skill-creator/scripts/package_skill.py <path/to/skill-folder>
```

指定輸出目錄（選用）：

```bash
~/.config/agenvoy/skills/.system/skill-creator/scripts/package_skill.py <path/to/skill-folder> ./dist
```

打包腳本會：

1. **驗證** Skill，自動檢查：
   - YAML Frontmatter 格式與必要欄位
   - Skill 命名規範與目錄結構
   - Description 的完整性與品質
   - 檔案組織與資源引用

2. **打包** 驗證通過的 Skill，建立以 Skill 命名的 .skill 檔案（例如 `my-skill.skill`），包含所有檔案並維持正確的目錄結構。.skill 檔案是副檔名為 .skill 的 zip 壓縮檔。

   安全限制：拒絕符號連結，存在任何符號連結時打包失敗。

若驗證失敗，腳本會回報錯誤並不建立打包檔案。修正所有驗證錯誤後重新執行打包指令。

### 步驟六：迭代

測試 Skill 後，使用者可能提出改善需求。這通常發生在使用 Skill 後不久，當時對 Skill 表現的 Context 還很清晰。

**迭代工作流程：**

1. 在實際任務中使用 Skill
2. 發現困難或低效之處
3. 識別應如何更新 SKILL.md 或打包資源
4. 實作變更並再次測試