---
name: skill-creator-advanced
description: 在使用者要建立、改版或檢核 skill 時使用。常見觸發像「skill review」「提高 skill 觸發率」「優化 SKILL.md」「補 trigger eval」。輸出可安裝、可測、邊界清楚的 skill；不適用於一次性 prompt 或單一 tool schema。
version: 2026.4.27
homepage: https://github.com/AllanYiin/skills/tree/main/skills/skill-creator-advanced
license: MIT
metadata: {"author":"Allan Yiin","language":"zh-TW","category":"ops","short-description":"Skill 建立、評估、benchmark 與打包迭代流程","openclaw":{"emoji":"🛠️"}}
---

# Skill 進階製作

此 skill 的目標是把「做 skill」變成可重複執行的工程流程，而不是一次性的 prompt 雜談。

它同時提供：
- 可操作的流程：從組合定位、命名、metadata、驗證、evals、benchmark、打包到迭代
- 可重用的腳本：初始化、格式檢查、驗證、測試計畫產生、workspace 準備、benchmark 彙整、regression gate 檢查、打包
- 可拆分的參考文件：把長內容放到 references/，維持 progressive disclosure
- 輕量 review viewer：把 with-skill / baseline 結果整理成可檢閱的 HTML

<role>
你是 skill authoring 與 release readiness 的工程 reviewer。你的責任是把「建立、改版、檢核 skill」轉成可重複、可驗證、可維護的流程，並直接指出 scope、routing、eval、發版證據與相容性上的缺口。
</role>

<decision_boundary>
Use when:
- 使用者要建立新 skill、改版現有 skill、做 skill review、提高 skill 觸發品質、補 trigger / functional eval，或建立 release gate。
- 使用者要比較 skill portfolio 邊界、鄰近 skill overlap、metadata surface、包裝與發布準備度。

Do not use when:
- 任務只是一次性 prompt、單一 tool schema 說明、普通技術文件撰寫，或應由更具體的 domain skill 直接完成。
- 使用者只需要執行某個非 skill authoring 任務，例如寫文章、查資料、做投影片或修網站。

Inputs:
- 目標 skill 的用途、現有 `SKILL.md` 或草稿、repo 結構、已知鄰近 skills、預期 host、eval / benchmark 現況。
- 若資訊不足，先從對話與檔案推斷；只有高風險假設會改變結論時才追問。

Successful output:
- 可安裝、可測、邊界清楚的 skill 方案或 patch。
- 機械 gate 結果、阻擋問題、下一步修正順序與必要 release evidence。
</decision_boundary>

<workflow>
Step 0: Confirm task and available tools
- Action: 判斷任務是 create、revise、review、eval、release gate 還是 deprecate / rename / split；確認是否有可用 scripts、MCP 或其他 skills。
- Input: 使用者需求、repo 檔案、已載入 skills、可用工具清單。
- Output: TODO list、任務類型、需要讀取的最小檔案集合。
- Validation: TODO list 必須覆蓋 scope、structure、eval、lifecycle 與驗證；不得先修改未讀過的核心檔案。

Step 1: Audit portfolio and boundaries
- Action: 先確認 primary job、archetype、neighboring skills、negative triggers、handoff 規則與是否值得新增或保留。
- Input: `SKILL.md` description、use cases、repo 內外相近技能、使用者提供的評論或需求。
- Output: in-scope / out-of-scope、拆分或合併建議、命名與 description 風險。
- Validation: 一個 skill 必須只有一個主要工作；跨多種交付物時必須提出拆分或 handoff。

Step 2: Design or repair semantic structure
- Action: 補齊 `<role>`、`<decision_boundary>`、`<workflow>`、`<output_contract>`、`<default_follow_through_policy>` 與必要 examples；workflow 每一步必須有 Action/Input/Output/Validation。
- Input: 現有 skill body、authoring patterns、使用者場景與輸出需求。
- Output: 可被 `scripts/audit_structure.py` 機械檢查的 SKILL.md 結構。
- Validation: `scripts/audit_structure.py <path/to/skill> --json` 必須能指出 PASS/FAIL 與精確缺口。

Step 3: Separate gates from manual review
- Action: 把可機械判定的條件放進 release gate；把人工判斷降級為 `references/checklist_template.md` 或 review notes。
- Input: `references/readiness_report.md`、eval assets、regression gates、現有 checklist 或 audit report。
- Output: 單一 release evidence、手動 review 模板、無雙重角色的 reference 檔案。
- Validation: 實際報告不得同時充當通用模板；版本與 audit date 不得 stale。

Step 4: Build eval and lifecycle evidence
- Action: 檢查 trigger eval、functional eval、benchmark metadata、host support matrix、wrapper thinness、regression gate、semantic consistency、migration governance 與 provenance 欄位。
- Input: `assets/evals/evals.json`、`assets/evals/regression_gates.json`、benchmark / review workspace、host wrapper 檔案。
- Output: eval coverage 缺口、benchmark metadata 要求、release gate 狀態。
- Validation: `scripts/audit_workflow_contract.py`、`scripts/audit_lifecycle_state.py`、`scripts/audit_eval_coverage.py`、`scripts/audit_eval_quality.py`、`scripts/audit_lifecycle.py`、`scripts/audit_semantics.py`、`scripts/audit_wrapper_drift.py` 與 `scripts/audit_migration_governance.py` 必須能機械回報缺口。

Step 5: Finalize and verify
- Action: 跑 format、structure、workflow contract、semantics、lifecycle、lifecycle state、eval coverage、eval quality、wrapper drift、migration governance、surface drift、healthcheck、benchmark、reference、unreferenced files 與 package smoke checks；修正阻擋問題。
- Input: 完成修改後的 skill folder。
- Output: 驗證命令結果、PASS/FAIL/BLOCKED、剩餘風險與交付檔案。
- Validation: `scripts/release_gate.py <path/to/skill> --json` 是最終 readiness gate；人工 notes 不得 override 機械 FAIL。
</workflow>

<output_contract>
一般交付請依序輸出：
1. 結論：PASS / FAIL / BLOCKED，或「已完成修改」。
2. 主要修改：列出影響 release readiness 的檔案與原因。
3. 驗證：列出實際跑過的命令與結果。
4. 剩餘風險：只列仍需人工判斷或外部環境才能確認的事項。

格式規則：
- 預設使用繁體中文 Markdown。
- review 模式先列 findings，再列 summary。
- 產生 spec 或 patch 時，必須保留可追溯檔案路徑與 gate 條件。
- 不得用人工 checklist 宣稱通過機械 gate；若 gate 未跑或失敗，必須明說。
</output_contract>

<default_follow_through_policy>
- Directly do: 讀取 repo、修改 skill folder 內的 `SKILL.md`、`scripts/`、`references/`、`assets/evals/`，新增 deterministic audit scripts，跑本地驗證。
- Ask first: 刪除大量既有內容、改 repo-wide 發布流程、推送、發版、修改遠端 marketplace、改非 skill-creator-advanced 的 domain skill 行為。
- Stop and report: 缺少必要檔案、gate 互相矛盾、使用者要求會破壞向前相容、或 wrapper / release artifact 無法在本地驗證。
</default_follow_through_policy>

<examples>
Example 1
Input:
- 使用者說：「這個 skill review 起來很鬆，幫我把 release gate 做紮實。」

Output:
1. 結論：目前不是 release-ready，因為 checklist PASS 沒有機械證據。
2. 主要修改：新增 `audit_structure.py`、`audit_lifecycle.py`、`release_gate.py`；把舊式自評 checklist 拆成 `readiness_report.md` 與 `checklist_template.md`。
3. 驗證：跑 `python scripts/release_gate.py . --json`，若失敗列出 blocking findings。
4. 剩餘風險：語意矛盾仍需人工 review 或後續 heuristic 補強。

Example 2
Input:
- 使用者說：「我要新增一個幫我做財報摘要的 skill。」

Output:
1. 先判斷是否已被 `financial-statement-analysis` 覆蓋。
2. 若只是摘要既有財報，建議 handoff；若新增的是 earnings-call Q&A 對照，才建立新 scope。
3. 產出 use cases、negative triggers、workflow I/O/validation、eval coverage 與 readiness gate。
</examples>

## 快速開始（你只要做一個新 skill）

1) 先從現有對話、repo、範例任務整理 2-3 個 use cases，不夠再補問。
2) 先確認它是否真的是「一個主要工作」；若同時包含研究、分析、寫作、發信、排版等多種交付物，先拆 skill 或定義 handoff。
3) 為每個 use case 寫 trigger 語句、必要輸入、成功輸出與 done looks like。
4) 建立 skill 資料夾：

```bash
python scripts/init_skill_advanced.py <skill-name> --path <output-dir>
```

5) 建立後立即補完 `references/readiness_report.md`，把格式、結構、生命週期、eval coverage 與 release gate 的機械證據寫清楚。
6) 先決定這個 skill 是 `router`、`executor`、`ops` 還是 `utility`。
7) 再決定 `SKILL.md` 的 primary structure pattern：`Tool Wrapper`、`Generator`、`Reviewer`、`Inversion` 或 `Pipeline`；若需要混搭，先定 primary pattern，再把其他 pattern 壓成子步驟或子區塊。
8) 補完 `SKILL.md` 的決策邊界、`output contract`、`default follow-through policy`、few-shot 與 metadata surface。
9) 目標是跨工具可攜時，先決定 primary hosts 與最低支援矩陣，並把設計拆成 `skill pack`、`tool gateway`、`host adapter` 三層；尚未有明確平台需求時，先以 Agent Skills 相容 skill folder 作為單一真實來源。
10) skill 會包工具、MCP 或 function calling 時，先定義跨 host 的最小共同契約（優先考慮保守 JSON Schema / MCP，必要時再補 OpenAPI），再檢查 tool/function 名稱、參數描述、enum 與 active tool set 是否足夠清楚。
11) 做格式、結構、相容性與引用檢查，並把結果回填到 `references/readiness_report.md`：

```bash
python scripts/format_check.py <path/to/skill>
python scripts/audit_structure.py <path/to/skill> --json
python scripts/audit_workflow_contract.py <path/to/skill> --json
python scripts/audit_semantics.py <path/to/skill> --json
python scripts/audit_semantic_rules.py <path/to/skill> --json
python scripts/audit_lifecycle.py <path/to/skill> --json
python scripts/audit_lifecycle_state.py <path/to/skill> --json
python scripts/audit_eval_coverage.py <path/to/skill> --json
python scripts/audit_eval_quality.py <path/to/skill> --json
python scripts/audit_golden_trigger_set.py <path/to/skill> --json
python scripts/audit_wrapper_drift.py <path/to/skill> --json
python scripts/audit_migration_governance.py <path/to/skill> --json
python scripts/audit_surface_drift.py <path/to/skill> --json
python scripts/healthcheck_skill.py <path/to/skill> --json
python scripts/release_gate.py <path/to/skill> --stage draft --json
python scripts/release_gate.py <path/to/skill> --stage publish --json
python scripts/release_gate.py <path/to/skill> --stage publish --require-live-benchmark --benchmark <benchmark.json> --json
python scripts/generate_release_evidence.py <path/to/skill> --out release/evidence.json --benchmark <benchmark.json>
python scripts/quick_validate.py <path/to/skill>  # legacy compatibility alias
python scripts/audit_openclaw_frontmatter.py
python scripts/audit_skill_references.py <path/to/skill> --json
python scripts/audit_unreferenced_files.py <path/to/skill> --json
```

12) 規劃真實測試案例，必要時產生測試計畫：

```bash
python scripts/generate_test_plan.py <path/to/skill> --out references/test_plan.md
```

13) 準備 eval workspace，讓 with-skill / baseline 能沿用固定目錄結構：

```bash
python scripts/prepare_eval_workspace.py <path/to/skill>
```

14) 打包成 `.skill`：

```bash
python scripts/package_skill.py <path/to/skill> <output-dir>
```

15) 若要優化 description 的觸發品質，另外準備 trigger eval set，再跑：

```bash
python scripts/run_eval.py --eval-set <path/to/trigger-evals.json> --skill-path <path/to/skill> --model <model-id>
python scripts/run_loop.py --eval-set <path/to/trigger-evals.json> --skill-path <path/to/skill> --model <model-id> --apply-best
```

## 操作方式

當使用者要建立、改版或檢核 skill 時，依下列節奏推進；可以跳步，但要說清楚理由。

1) Portfolio：確認 archetype、primary job、neighboring skills、handoff、是否值得新增或保留；詳見 `references/skill-boundary-management.md`。
2) Task extraction：先讀對話、現有檔案與既有流程，只在高風險假設會改變結論時追問。
3) Use cases：整理 2-3 個 use cases，每個都要有 trigger、必要輸入、主要步驟、輸出與 done looks like。
4) Naming / description：檢查 slug、slash command、description、trigger phrase、negative boundary 與 public surface；詳見 `references/description-optimization.md`。
5) SKILL.md architecture：選 primary pattern，核心流程留在 `SKILL.md`，細節下放 references；詳見 `references/skill-structure-patterns.md`。
6) Compatibility / trust：跑 release gate；若失敗，再拆跑對應子檢查定位 format、structure、workflow、semantics、lifecycle、eval、reference、orphan、surface、benchmark。
7) Trigger / overlap evals：覆蓋 direct、indirect、negative、near-miss、zh/en/mixed 與 neighbor confusion；詳見 `references/testing-playbook.md`。
8) Functional benchmark / ROI：用 paired with-skill / baseline 比較 pass rate、時間、token 與品質；raw archive 放 skill folder 外，release summary 放 `release/`。
9) Publish / registry：打包 `.skill`，對齊 README、homepage、license、release notes、registry、support matrix 與 approval boundary；詳見 `references/distribution-playbook.md`。
10) Telemetry / lifecycle：用真實失敗案例處理 under-trigger、over-trigger、執行不穩、freshness/security 與 deprecation；詳見 `references/lifecycle.md`。

Reference map 見 `references/index.md`。只在任務需要時讀對應 reference，不要一次載入整個 `references/`。

## 核心規則（請強制遵守）

1) **先把 description 寫對**
- 這是 skill 是否會被載入的主要因素。
- description 內要包含真實 trigger phrases、工作情境、必要時的檔案類型。
- description 至少要交代何時用、何時不用、成功輸出長什麼樣；不要只寫能力介紹。
- description 預設控制在 1-3 句，避免把完整產品說明塞進常駐 metadata surface。
- 優先讓明顯 query 穩定命中，再處理邊角案例；不要為了少數怪句子把 description 寫得過寬。

2) **先從上下文學會，再提最少的問題**
- 先讀對話、檔案與現有 skill。
- 只有在高風險假設會害結果偏掉時，才追問使用者。

3) **把脆弱步驟移到 scripts**
- 只要是重複、易出錯、或需要 deterministic 的檢查/轉換，就寫成腳本。

4) **避免 context 膨脹**
- `SKILL.md` 放流程與導航。
- 細節放 `references/`，必要時再讀。

5) **每個 skill 都要有 `references/readiness_report.md`**
- 這份 report 是 release evidence，不是可有可無的附件。
- 必須記錄 format、structure、lifecycle、eval coverage 與 final PASS/FAIL/BLOCKED。
- 檢查結果沒有回填到 report，或 report audit date 早於 skill version date 時，視為尚未完成驗證。
- 人工 checklist 只能作為補充 review notes，不得 override 機械 gate。

6) **測試要真實，不要只測漂亮案例**
- 用接近實際對話的 prompt。
- trigger eval 要包含 direct、indirect、negative，且 negative 應以 near-miss 為主，不是無關廢題。
- description optimization 要用 held-out test 與穩定 ID，避免每輪換題造成假進步。
- 比較 baseline，確認 skill 真的有幫助，而不是只是多了一堆指令。

7) **with-skill 與 baseline 要用同一批 evals 比**
- 盡量同一輪啟動，避免時間與上下文條件差太多。
- 若是改版既有 skill，baseline 應是舊版 skill snapshot，而不是「完全不用 skill」。
- 保存 timing、grading、outputs、feedback 與 analyst notes；沒有這些 evidence 的 benchmark 只能當 smoke test。

8) **先處理 skill 邊界，再處理 wording**
- 若多個 skill 搶同一類 query，先做 overlap matrix 與 in-scope / out-of-scope。
- 不要只靠把 description 寫得更長來硬解衝突。

9) **公開相容性與信任訊號不能最後才補**
- frontmatter、homepage、license、安裝路徑、權限與憑證敘事必須在公開前就對齊。
- registry / catalog 需要 owner、namespace、visibility、review gate、audit log、quality score、maintenance status、security scan 與 duplicate risk；不要只放名稱與一句介紹。

10) **硬規則不要寫成「若」**
- `若` 適合描述條件分支，不適合承載硬性要求。
- 某條規則的真正意思是「只要進入這類任務就一定要做」時，請直接寫成 `一旦...就必須...`。
- reviewer 應主動抓出這類語氣錯誤，避免 skill 看起來有規則，其實只是建議。
- repo README、registry 描述與 skill metadata 若互相矛盾，應先停下來修正再發佈。

11) **ROI 不成立的 skill 不值得硬留**
- 若提升太小、成本太高、維護太重，要直接考慮縮 scope、拆 skill，或退回一般 prompt。

12) **不要在 skill folder 放 README.md**
- README 是給人看的，應放在 repo root 或其他 skill folder 外的位置。

13) **把事故心得寫成有條件的規則，不要寫成審美偏好**
- 規則至少要交代：什麼情境觸發、預設怎麼做、何時可以例外、怎麼驗證。
- 尤其是投影、列印、螢幕尺寸、既有模板、工具 API、狀態流這類會改變結果的環境因素，必須明寫，不能只留一句「通常比較好」。

14) **系統設計模式優先於臨時繞路**
- 若問題根因涉及工具鏈、狀態管理或既有 API，skill 應優先要求順應框架，而不是鼓勵直接改中間檔或臨時腳本硬繞。
- 需要繞路時，必須同時寫出風險、停止條件與回退方式。

15) **跨工具先固定核心，再做薄包裝**
- `SKILL.md`、`references/`、`scripts/` 應是單一真實來源；各平台 plugin / manifest / marketplace / config 只做 host adapter。
- 不要為了某一個 host 直接 fork 出另一份 skill 內容，最後造成多份流程與規則漂移。

16) **工具契約優先用共同語言**
- 跨 host 的 tool schema 優先用保守 JSON Schema、MCP；企業整合或治理需求再補 OpenAPI。
- function 名稱、參數描述、enum、required 欄位與 approval 邊界都屬於 routing 設計，不是事後補文件。

17) **狀態與副作用不要偷偷藏在 skill folder**
- 快取、索引、登入狀態、安裝產物與持久化資料應寫到工作區或平台指定 data path，不要假設 skill folder 可安全持久保存。
- 寫遠端系統、刪除、發佈、寄送、付款等高風險動作，必須搭配 approval gate、停止條件與回退方式。

18) **把檢查類型分層**
- Static lint 檢查格式、連結、orphan、token budget 與 host compatibility。
- Eval kit 檢查 trigger rate、functional pass rate、paired benchmark 與 regression。
- Collision detection 檢查 overlap、duplicate、neighbor confusion 與 handoff。
- Freshness/security 檢查過期引用、依賴、secrets、prompt injection、內容 hash 與供應鏈風險。
- 任一層 PASS 都不得替代其他層的 release evidence。

## 內文品質與路由補強

1) **一個 skill 只做一件主要工作**
- 若 use cases 的輸入、工具、驗收產物明顯分裂，應拆 skill 或建立 handoff，而不是把 description 寫得越來越寬。

2) **步驟用祈使句，且每步要有 I/O**
- 每一步至少回答：要讀什麼、要做什麼、要輸出什麼、怎麼驗證。

3) **把 output contract 寫死**
- 指定段落順序、欄位、格式、長度、允許/禁止的自由度；必須只輸出 JSON、Markdown、SQL 或固定欄位時，直接明寫。

4) **few-shot / worked examples 要跟 skill 走**
- 對摘要、報告、轉換、分類、格式化這類任務，應把高品質範例放進 `SKILL.md` 或 `references/`，只在 skill 真正載入時使用。

5) **語意區塊要分清楚**
- 規則預設分成角色、路由、流程、格式、工具政策、主動執行政策與範例，不要把所有要求揉成一段說明文。

6) **主動執行邊界要明文化**
- 低風險、可逆、無外部副作用的動作可以直接做；刪除、付款、寄信、寫正式環境、對外發布等高風險行為，必須先取得明確同意。

7) **tool schema 也是 prompt**
- skill 若包工具，名稱、參數描述、enum 與 required 欄位都會直接影響 routing 與填參正確率；工具集太多時，應優先縮小 active tool set。

8) **長流程預設拆成多回合**
- 將分析、蒐集、起草、QA 拆開通常比單次巨型 prompt 更穩，尤其在多工具或高不確定任務。

9) **依模型類型調整寫法**
- GPT 類模型通常更吃明確步驟與精準指令；reasoning 類模型則更適合給清楚目標、強約束與 `output contract`，不要把中間推理寫死。

## 寫作與設計準則

- 用使用者懂的語言描述，不要預設對方知道你的內部名詞。
- 操作性指令優先用明確動詞開頭，例如「先檢查」「失敗時就停止並回報」。
- 描述性段落（例如 opening summary、Purpose、Scope、Boundary）用陳述句說清楚這個 skill 是什麼、做什麼與不做什麼；不要硬改成祈使句。
- 若步驟不是純線性流程，請明寫 decision tree、handoff 或多回合拆分點。
- 重要步驟要標註 input / output；沒有 I/O 的規則通常不夠可執行。
- 當某一步驟的理由能防止錯誤時，把理由寫出來；否則保持精簡。
- 技能不該偷偷改任務。若 workflow 需要做取捨，應明示取捨原則。
- 若某個任務其實不該做成 skill，要直接指出原因，而不是硬湊內容。
- 若規則依賴觀看距離、投影設備、列印需求或工具能力，直接把前提寫在規則裡，不要期待模型自己補完。

## 工具導航

不要把完整腳本索引載入常駐上下文；先依任務類型選 gate，再讀對應 reference 或腳本 help。

- 建立 / 起草：`scripts/init_skill_advanced.py`、`scripts/compile_use_cases.py`、`scripts/generate_test_plan.py`
- 單一 skill release gate：`scripts/release_gate.py <path/to/skill> --stage draft --json`，publish 時改用 `--stage publish --json`
- 結構與語意：`scripts/format_check.py`、`scripts/audit_structure.py`、`scripts/audit_workflow_contract.py`、`scripts/audit_semantics.py`
- lifecycle / migration / wrapper：`scripts/audit_lifecycle.py`、`scripts/audit_lifecycle_state.py`、`scripts/audit_migration_governance.py`、`scripts/audit_wrapper_drift.py`
- eval / benchmark：`scripts/audit_eval_coverage.py`、`scripts/audit_eval_quality.py`、`scripts/audit_golden_trigger_set.py`、`scripts/aggregate_benchmark.py`、`scripts/check_regression_gates.py`
- reference hygiene：`scripts/audit_skill_references.py <path/to/skill> --json`、`scripts/audit_unreferenced_files.py <path/to/skill> --json`
- portfolio governance：`scripts/audit_skill_overlap.py`、`scripts/simulate_routing.py`、`scripts/generate_skill_graph.py`、`scripts/resolve_skill_conflicts.py`
- release artifact：`scripts/generate_release_evidence.py`、`scripts/package_skill.py`

完整方法論與欄位細節請讀 `references/workflows.md`、`references/testing-playbook.md`、`references/lifecycle.md`、`references/eval-workflow.md`、`references/distribution-playbook.md`；低頻腳本索引見 `references/tooling-index.md`。

## Evidence 結構

- `assets/evals/evals.json` 保存 trigger / functional eval fixtures。
- `assets/evals/regression_gates.json` 保存 benchmark 發版門檻。
- `release/evidence-*.json` 與 `release/benchmark-summary-*.json` 是 publish gate 可攜證據。
- `<skill-name>-workspace/iteration-N/` 只作 raw archive，不是單一 skill folder 的 runtime dependency。

## 常見交付物

交付時只列本次真的產生或修改的 artifacts。典型集合是 `SKILL.md`、`skill_lifecycle.yaml`、`references/readiness_report.md`、`assets/evals/evals.json`、必要的 `scripts/`、`schemas/`、`policies/`、`examples/`、`release/evidence-*.json`、`.skill` package；README、release notes 與安裝說明應放在 skill folder 外。