// 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.
| 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. |
Agenvoy 路徑規則（優先於所有其他路徑設定）：所有 Skill 一律儲存至
~/.config/agenvoy/skills/<skill-name>/。步驟三的--path參數固定使用~/.config/agenvoy/skills，忽略 SKILL.md 其他段落中提及的任何其他路徑。
⚠️ 強制執行規則（不可繞過）：
- 建立全新 Skill — 禁止直接用
write_file建立目錄或 SKILL.md，必須先以run_command執行python3 scripts/init_skill.py初始化目錄結構，再用write_file或patch_file編輯產生的模板內容。跳過此步驟會導致目錄結構錯誤（生成skill-name.md而非skill-name/SKILL.md）。- 編輯現有 Skill — 直接使用
write_file或patch_file修改skill-name/SKILL.md及其資源檔案，不需要執行python3 scripts/init_skill.py。
此 Skill 提供建立有效 Skill 的完整指引。
Skill 是模組化、自包含的套件，透過提供專業知識、工作流程與工具來擴充 Agent 的能力。可將其視為特定領域或任務的「入職指南」——讓 Agent 從通用助手轉變為配備程序性知識的專業 Agent，而這些知識是模型本身無法完全具備的。
Context Window 是公共資源。Skill 與其他所有內容共享 Context Window：System Prompt、對話歷史、其他 Skill 的 Metadata 以及實際的使用者請求。
預設假設：Agent 已經非常聰明。 只加入 Agent 本身沒有的 Context。對每一條資訊提出質疑：「Agent 真的需要這個說明嗎？」「這段文字值得佔用的 Token 成本嗎？」
優先使用精簡範例，而非冗長說明。
根據任務的脆弱性與變異性，匹配對應的指令精確度：
高自由度（純文字指令）：當多種方式都有效、決策依賴 Context、或啟發式方法引導流程時使用。
中等自由度（Pseudo-code 或帶參數的腳本）：當存在偏好模式、允許部分變化、或設定會影響行為時使用。
低自由度（特定腳本、少量參數）：當操作脆弱且易出錯、一致性至關重要、或必須遵循特定順序時使用。
將 Agent 視為探索路徑：有懸崖的窄橋需要明確護欄（低自由度），而開闊的原野允許多種路線（高自由度）。
每個 Skill 由必要的 SKILL.md 與選用的打包資源組成：
skill-name/
├── SKILL.md（必要）
│ ├── YAML Frontmatter Metadata（必要）
│ │ ├── name:（必要）
│ │ └── description:（必要）
│ └── Markdown 指令（必要）
└── 打包資源（選用）
├── scripts/ — 可執行程式碼（Python/Bash 等）
├── references/ — 依需求載入 Context 的參考文件
└── assets/ — 輸出中使用的檔案（模板、圖示、字型等）
每個 SKILL.md 由以下部分組成：
name 與 description 欄位。這是 Agent 判斷何時使用此 Skill 的唯一依據，因此必須清楚且完整地描述 Skill 的功能與觸發時機。scripts/）需要確定性可靠度或會被反覆重寫的任務所需可執行程式碼（Python/Bash 等）。
scripts/rotate_pdf.py 用於 PDF 旋轉任務references/）依需求載入 Context 的文件與參考資料，用於指引 Agent 的思考過程。
references/finance.md（財務 Schema）、references/mnda.md（公司 NDA 模板）、references/policies.md（公司政策）、references/api_docs.md（API 規格）assets/）不載入 Context，而是在 Agent 輸出中使用的檔案。
assets/logo.png（品牌資源）、assets/slides.pptx（PowerPoint 模板）、assets/frontend-template/（HTML/React 樣板）、assets/font.ttf（字型）Skill 只應包含直接支援其功能的必要檔案。不要建立多餘的文件或輔助檔案，包含：
Skill 只應包含 AI Agent 完成任務所需的資訊，不應包含建立過程說明、測試程序、面向使用者的文件等輔助 Context。
Skill 使用三層載入系統，有效管理 Context：
保持 SKILL.md body 精簡且在 500 行以內，避免 Context 膨脹。接近上限時拆分至獨立檔案。拆分後務必在 SKILL.md 中明確引用，並說明何時應讀取這些檔案。
核心原則：當 Skill 支援多種變體、框架或選項時，SKILL.md 只保留核心工作流程與選擇指引，將變體的細節移至獨立參考檔案。
模式一：高層次指南加引用
# 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 包含以下步驟：
依序執行這些步驟，只有在明確不適用時才跳過。
plan-mode）gh-address-comments、linear-address-issue）只有在 Skill 使用模式已非常清楚時才跳過此步驟。即使是改善現有 Skill，此步驟仍有價值。
要建立有效的 Skill，需清楚理解 Skill 的具體使用範例。這些理解可來自使用者直接提供的範例，或由生成後請使用者驗證的範例。
例如，建立 image-editor Skill 時，相關問題包括：
為避免讓使用者感到不知所措，避免在單一訊息中問太多問題。從最重要的問題開始，依需求追問。
當對 Skill 應支援的功能有清楚認識時，結束此步驟。
要將具體範例轉化為有效的 Skill，對每個範例進行以下分析：
範例：建立 pdf-editor Skill 處理「幫我旋轉這個 PDF」類的請求，分析顯示：
scripts/rotate_pdf.py 腳本存放在 Skill 中會很有幫助範例：設計 frontend-webapp-builder Skill 處理「幫我建立一個待辦事項 App」類的請求，分析顯示：
assets/hello-world/ 目錄存放在 Skill 中會很有幫助範例：建立 big-query Skill 處理「今天有多少使用者登入？」類的請求，分析顯示：
references/schema.md 存放在 Skill 中會很有幫助此時可以開始實際建立 Skill。
只有在 Skill 已存在且需要迭代或打包時才跳過此步驟，此時繼續下一步驟。
從零建立新 Skill 時，務必執行 python3 scripts/init_skill.py 腳本。此腳本會自動生成包含所有必要元素的 Skill 模板目錄。
用法：
python3 scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets] [--examples]
範例：
python3 scripts/init_skill.py my-skill --path skills/public
python3 scripts/init_skill.py my-skill --path skills/public --resources scripts,references
python3 scripts/init_skill.py my-skill --path skills/public --resources scripts --examples
此腳本會：
--resources 選擇性建立資源目錄--examples 時選擇性新增範例檔案初始化後，自訂 SKILL.md 並依需求新增資源。若使用了 --examples，請替換或刪除佔位符檔案。
編輯新生成或現有的 Skill 時，請記住此 Skill 是為另一個 Agent 實例所建立的。納入對 Agent 有益且非顯而易見的資訊。思考哪些程序性知識、領域特定細節或可重用資源，能幫助另一個 Agent 實例更有效地執行這些任務。
根據 Skill 的需求查閱以下指南：
從上方識別的可重用資源開始實作：scripts/、references/ 和 assets/ 檔案。注意此步驟可能需要使用者輸入，例如使用者可能需要提供品牌資源或文件。
新增的腳本必須實際執行測試，確認沒有 Bug 且輸出符合預期。若有許多類似腳本，只需測試代表性樣本即可。
若使用了 --examples，刪除不需要的佔位符檔案。只建立實際需要的資源目錄。
撰寫指引：始終使用祈使式／原形動詞。
撰寫含 name 與 description 的 YAML Frontmatter：
name：Skill 名稱description：這是 Skill 的主要觸發機制
不要在 YAML Frontmatter 中包含其他欄位。
撰寫使用 Skill 及其打包資源的指令。
若 Skill 需要 token、API key 或其他 secret：
{品牌}_API_KEY（SCREAMING_SNAKE_CASE），例 OPENAI_API_KEY、CODEX_API_KEY、POLYGON_API_KEY、STAGING_API_KEYagenvoy、account = key 名，組合識別 agenvoy.{key}（例 agenvoy.OPENAI_API_KEY）keychain.Get("<KEY_NAME>")（只傳 key 名，無 agenvoy. 前綴）GET http://localhost:17989/v1/key?key=<KEY_NAME>auth.env: "<KEY_NAME>"store_secret({ key: "<KEY_NAME>", prompt: "..." })；該 tool 內部走遮罩輸入 + keychain.Set，Skill 全程不見明文禁止：
ask_user 取 plaintext 再轉手 store_secret（會把 value 帶進 LLM context／history／action.log）export ENV=value 之類 shell 環境變數路徑取代 keychainSkill 開發完成後，必須打包為可分發的 .skill 檔案。打包過程會自動先驗證 Skill，確保符合所有要求：
scripts/package_skill.py <path/to/skill-folder>
指定輸出目錄（選用）：
scripts/package_skill.py <path/to/skill-folder> ./dist
打包腳本會：
驗證 Skill，自動檢查：
打包 驗證通過的 Skill，建立以 Skill 命名的 .skill 檔案（例如 my-skill.skill），包含所有檔案並維持正確的目錄結構。.skill 檔案是副檔名為 .skill 的 zip 壓縮檔。
安全限制：拒絕符號連結，存在任何符號連結時打包失敗。
若驗證失敗，腳本會回報錯誤並不建立打包檔案。修正所有驗證錯誤後重新執行打包指令。
測試 Skill 後，使用者可能提出改善需求。這通常發生在使用 Skill 後不久，當時對 Skill 表現的 Context 還很清晰。
迭代工作流程：
Install an Agenvoy extension from pkg.agenvoy.com registry (browse/pick) or local tarball into ~/.config/agenvoy/tools/.extension/<type>/<name>@<version>/. Extracts tar.gz, validates manifest (email field, type api/script only), installs deps, stores keychain keys, atomically moves staged dir. Collisions handled by Overwrite/Rename/Cancel popup.
Package a script tool under ~/.config/agenvoy/tools/script/ into a tar.gz and publish to pkg.agenvoy.com registry. Keyword picker, dep/key detection, config-stored email (ask + lowercase + persist), ask version, email verification gate, multipart upload with downgrade/unique guards.
從最新的 git tag 到 HEAD 生成結構化變更日誌並推薦新版本。當使用者請求生成變更日誌、發行說明或版本升級文件時使用。
Convert user-supplied API source (Swagger/OpenAPI JSON, cURL, or natural-language endpoint description) into Agenvoy APIDocumentData format and write each endpoint as a separate JSON file under `~/.config/agenvoy/tools/api/`. Triggers on requests like "add an API tool", "新增 api tool", "把這個 swagger 轉成 api tool", "註冊一個 API 給 agent 用". Handles auth schema (bearer / apikey / basic) and warns on intranet/localhost hosts before write.
將模糊需求煉成可執行計畫並立即執行。僅由 `/plan {需求}` 顯式觸發。流程：呼叫 `ask_user` tool 依需求複雜度蒐集多面向資訊（核心 3 維度為底，依風險／不可逆性／資源缺口擴充至 5-7 題）→ 呼叫 `generate_plan` tool 產出結構化計畫 → 視計畫缺口 ask_user 補問 或 直接逐步執行。第一個 tool call 永遠是 `ask_user`；不自己組計畫，必走 `generate_plan` tool。
建立並排程定時觸發的 skill。**所有新增定時／週期任務、提醒、排程通知的請求必須走此 skill**，禁止直接呼叫 add_task / add_cron（那是 skill 已存在時的時間綁定工具，不該作為新建排程的入口）。 必定觸發的訊息特徵（任一即活化）： - 相對延遲：「X 分鐘後」「X 小時後」「稍後」「待會」「等一下」 - 明確時間：「X 點」「下午 X 點」「明天 X 點」「後天」「YYYY-MM-DD HH:MM」 - 週期性：「每 X 分鐘」「每小時」「每天」「每週」「每月」「定時」「固定」 - 提醒 / 通知意圖：「提醒我」「通知我」「告訴我」+ 時間描述 範例觸發訊息：「5 分鐘後提醒我喝水」「每天早上 9 點抓 HN 頭條」「明天下午 3 點開會」「每 5 分鐘查台積電股價」。 **不觸發**（即使訊息含「觸發」「排程」字眼也不 activate）： - 訊息含 `[執行已存在 scheduler skill:` 標記 → 為 `/sched-<name>` 手動 trigger，當前 agent 直接執行 body - 訊息為一份完整的 SKILL.md body（`# Title` + `## 任務` + `## 輸出格式` 結構），無建立／排程動詞 → 為 skill execution，非 creation - 訊息僅含「執行 skill X」「跑 X」「run skill X」無時間 token → 為 execution 流程：解析訊息抽出「要做什麼」「何時觸發」→ 缺項用 ask_user 補問 → 生成 skill 檔案至 ~/.config/agenvoy/skills/scheduler/<short>-<hash8>/SKILL.md（無 scheduler- 前綴，hash 用於避免命名衝突）→ 呼叫 add_task 或 add_cron 綁定時間 → 回報。