/skill-creator

name: skill-creator
description: 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 內部最佳化版本**，依 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`、`~/.copilot/skills`、`~/.agents/skills`，但那些是別的 harness 的位置，本 Skill 不往那裡寫。）

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

> **⚠️ 強制執行規則（不可繞過）**： > - **建立全新 Skill** — 禁止直接用 `edit_skill(mode=write)`／`edit_file(mode=write)` 建立目錄或 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_*` 工具 —— 那是 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 附帶的檔案**，不要去讀取它們。

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

# 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。

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

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

# DOCX 處理

## 建立文件

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

## 編輯文件

簡單編輯可直接修改 XML。

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

**重要指引：**

• **避免深層巢狀引用** — 引用層級保持在