---

name: refactor-skill-structure locale: wenyan-lite source_locale: en source_commit: 82c77053 fence_basis_commit: 82c77053 translator: "Julius Brussee homage — caveman" translation_date: "2026-04-26" description: > Refactor an over-long or poorly structured SKILL.md by extracting examples to references/EXAMPLES.md, splitting compound procedures, and reorganizing sections for progressive disclosure. Use when a skill exceeds the 500-line CI limit, when code blocks dominate the skill body, when a procedure step contains multiple unrelated operations, or after a content update pushed the skill over the line limit. license: MIT allowed-tools: Read Write Edit Grep Glob metadata: author: Philipp Thoss version: "1.1" domain: review complexity: advanced language: multi tags: review, skills, refactoring, structure, progressive-disclosure

重構技能結構

重構已逾 500 行限或結構有疾之 SKILL.md。本技能將延伸之代碼例抽出至 references/EXAMPLES.md，將複合程序拆分為聚焦之子程序，加交互引用以漸進揭示，並驗證重組後技能仍完整有效。

適用時機

• 技能逾 CI 所執之 500 行限
• 一程序步驟含多個不相關操作，宜分為各步
• 逾 15 行之代碼塊主導 SKILL.md 而可抽出
• 技能累積臨時段落，破壞標準六段結構
• 內容更新後技能逾行限
• 技能評審標出超越內容品質之結構問題

輸入

• 必要：擬重構之 SKILL.md 文件路徑
• 選擇性：目標行數（預設：瞄準 500 行限之 80%，即約 400 行）
• 選擇性：是否建立 references/EXAMPLES.md（預設：有可抽內容則是）
• 選擇性：是否拆為多技能（預設：否，宜先抽出）

步驟

步驟一：度量當前行數並識別膨脹之源

讀取技能並按段建立行預算，以識別膨脹所在。

# Total line count
wc -l < skills/<skill-name>/SKILL.md

# Line count per section (approximate)
grep -n "^## \|^### " skills/<skill-name>/SKILL.md

膨脹之源分類：

• 可抽：逾 15 行之代碼塊、完整配置例、多變體例
• 可拆：作 2 種以上不相關操作之複合程序步
• 可削：冗解、過長之上下文句
• 結構性：不合標準六段結構之臨時段

預期： 行預算顯示哪些段過大及何種膨脹類別適用。最大段乃首要重構標的。

失敗時： 若技能未逾 500 行且無顯結構問題，本技能恐不需。先驗重構之請求是否合理。

步驟二：抽代碼塊至 references/EXAMPLES.md

將逾 15 行之代碼塊移至 references/EXAMPLES.md，於主 SKILL.md 留簡短行內片段（3-10 行）。

1. 建 references 目錄：

   mkdir -p skills/<skill-name>/references/
   

2. 對每可抽之代碼塊：

   • 將完整代碼塊複製至 references/EXAMPLES.md，置於描述性標題之下
   • 於 SKILL.md 中以 3-5 行簡短片段取代之
   • 加交互引用：See [EXAMPLES.md](references/EXAMPLES.md#heading) for the complete configuration.

3. 以清晰標題組織 references/EXAMPLES.md：

   # Examples
   
   ## Example 1: Full Configuration
   
   Complete configuration file for [context]:
   
   \```yaml
   # ... full config here ...
   \```
   
   ## Example 2: Multi-Variant Setup
   
   ### Variant A: Development
   \```yaml
   # ... dev config ...
   \```
   
   ### Variant B: Production
   \```yaml
   # ... prod config ...
   \```
   

預期： 所有逾 15 行之代碼塊已抽出。主 SKILL.md 留簡短行內片段以資易讀。交互引用連至所抽之內容。references/EXAMPLES.md 組織良好，標題具描述性。

失敗時： 若抽代碼塊不足以充分減行（仍逾 500），續至步驟三作程序拆分。若技能代碼塊極少（如自然語言類技能），則改聚焦於步驟三、四。

步驟三：拆複合程序為聚焦之步驟

識別作多種不相關操作之程序步並拆之。

複合步之徵兆：

• 步題含「與」字（如「配置資料庫並設置快取」）
• 步有多個 Expected/On failure 塊（或應有）
• 步逾 30 行
• 步可被略過或其子部分可以不同順序進行

對每複合步：

1. 識其中之分離操作
2. 為每操作建一新 ### Step N:
3. 為後續步驟重新編號
4. 確保每新步有自己之 Expected 與 On failure 塊
5. 於新步間加過渡上下文

預期： 每程序步只作一事。無步逾 30 行。步數可增但每步可獨立驗證。

失敗時： 若拆步過細（如總計逾 20 步），考慮將相關微步歸於單一步下之編號子步。佳之區間為 5-12 程序步。

步驟四：自 SKILL.md 加交互引用至所抽內容

確保抽出後主 SKILL.md 仍易讀且可發現。

對每抽出：

1. SKILL.md 中之行內片段對常見情形應自足
2. 交互引用應說明附加內容為何
3. 使用相對路徑：[EXAMPLES.md](references/EXAMPLES.md#section-anchor)

交互引用模式：

• 簡短代碼片段之後：See [EXAMPLES.md](references/EXAMPLES.md#full-configuration) for the complete configuration with all options.
• 多變體例：See [EXAMPLES.md](references/EXAMPLES.md#variants) for development, staging, and production variants.
• 延伸排錯：See [EXAMPLES.md](references/EXAMPLES.md#troubleshooting) for additional error scenarios.

預期： 每抽出皆有對應之交互引用。讀者可循主 SKILL.md 處理常見情形，而鑽入 references 看細節。

失敗時： 若交互引用使行文不順，將多引用合併為程序步末之單一注：For extended examples including [X], [Y], and [Z], see [EXAMPLES.md](references/EXAMPLES.md).

步驟五：重構後驗行數

對 SKILL.md 重新度量行數。

# Check main SKILL.md
lines=$(wc -l < skills/<skill-name>/SKILL.md)
[ "$lines" -le 500 ] && echo "SKILL.md: OK ($lines lines)" || echo "SKILL.md: STILL OVER ($lines lines)"

# Check references file if created
if [ -f skills/<skill-name>/references/EXAMPLES.md ]; then
  ref_lines=$(wc -l < skills/<skill-name>/references/EXAMPLES.md)
  echo "EXAMPLES.md: $ref_lines lines"
fi

# Total content
echo "Total content: $((lines + ${ref_lines:-0})) lines"

預期： SKILL.md 已逾 500 行下。理想於 400 行下，留將來增長空間。references/EXAMPLES.md 無行限。

失敗時： 若抽出與拆分後仍逾 500 行，考慮是否應將該技能分解為兩個獨立技能。涵蓋過廣乃範圍蠕之徵。用 create-skill 寫第二技能並更新二者之相關技能交互引用。

步驟六：驗所有段落仍存

重構之後，驗該技能仍具所有必需段且 frontmatter 完整。

跑 review-skill-format 清單：

1. YAML frontmatter 解析正確
2. 六必需段皆存（When to Use、Inputs、Procedure、Validation、Common Pitfalls、Related Skills）
3. 每程序步皆有 Expected 與 On failure 塊
4. 無孤立交互引用（所有連結可達）

# Quick section check
for section in "## When to Use" "## Inputs" "## Procedure" "## Common Pitfalls" "## Related Skills"; do
  grep -q "$section" skills/<skill-name>/SKILL.md && echo "$section: OK" || echo "$section: MISSING"
done
grep -qE "## Validation( Checklist)?" skills/<skill-name>/SKILL.md && echo "Validation: OK" || echo "Validation: MISSING"

預期： 所有段皆存。抽出時無內容意外被刪。SKILL.md 中之交互引用解析至 EXAMPLES.md 中之實際標題。

失敗時： 若有段意外被移除，自 git 歷史復之：git diff skills/<skill-name>/SKILL.md 以見何變。若交互引用斷，驗 EXAMPLES.md 之標題錨點與 SKILL.md 之連結相符（GitHub 風格 markdown 錨點規則：小寫、空格化連字符、剝點符）。

驗證

• SKILL.md 行數 500 或更少
• SKILL.md 中所有代碼塊 15 行或更少
• 抽出之內容於 references/EXAMPLES.md 中，附描述性標題
• 每抽出皆於主 SKILL.md 有交互引用
• 無複合程序步留存（每步只作一事）
• 重構後六必需段皆存
• 每程序步皆有 Expected: 與 On failure: 塊
• YAML frontmatter 完整可解析
• 交互引用連結解析至 EXAMPLES.md 中之實際標題
• review-skill-format 之驗證於重構後技能上通過

常見陷阱

• 抽得太狠：將所有代碼移至 references 使主 SKILL.md 不易讀。常見情形宜留 3-10 行片段於行內。僅抽逾 15 行或多變體之塊
• 錨連結斷：GitHub 風格 markdown 錨點於某些渲染器中區分大小寫。EXAMPLES.md 用小寫標題並於交互引用中精確對應。以 grep -c "heading-text" references/EXAMPLES.md 測之
• 拆分時失 Expected/On failure：拆複合步時，確保每新步有自己之 Expected 與 On failure 塊。拆後易留某步無此二塊
• 創過多細步：拆分宜得 5-12 程序步。若得 15 步以上則拆得過狠。將相關微步合回邏輯組
• 遺忘更新 references/EXAMPLES.md 標題：若改 EXAMPLES.md 中之段名，SKILL.md 中所有交互引用錨皆須更新。grep 舊錨名以捉所有引用

相關技能

• review-skill-format — 重構之後跑格式驗證，確認技能仍合規
• update-skill-content — 內容更新每每為結構重構之觸發，當其推技能逾行限時
• create-skill — 決定如何組織抽出內容時，參照標準結構
• evolve-skill — 須將一技能拆為二時，用 evolve 建衍生