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 — 禁止直接用 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_*／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 附帶的檔案，不要去讀取它們。

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

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

重要指引：

• 避免深層巢狀引用 — 引用層級保持在 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 中會很有幫助