no-markdown-decoration-principle

name	no-markdown-decoration-principle
description	SKILL.md 撰寫時避免不必要的 Markdown 裝飾（粗斜底線），並只在表格真的更適合時才使用表格，以 Text Mode 友善的原始排版為主。Use when 撰寫或修改 SKILL.md、skill 正文、或使用者要求簡潔無裝飾的 skill 文件時。

Purpose

讓 AI 在協助撰寫或修改 SKILL.md 時，預設以 Text Mode 可直接閱讀的原始排版產出，避免堆疊粗體、斜體、底線等不必要裝飾，並審慎判斷表格是否真的值得使用。 多數人習慣在編輯器的 Text Mode 閱讀與修改 Markdown；Preview Mode 切換不便，螢幕不夠大時更難雙軌對照，頻繁切換會干擾編輯節奏。 此 skill 是 skill 撰寫工作流中的排版守門原則：假設內容與結構已大致確定，本 skill 負責把落地成 SKILL.md 或其他 reference markdown 文件時的呈現方式收斂為簡潔、可掃讀、易於在純文字模式下修改的格式，同時只在表格明顯優於段落與列表時才保留表格。

Rules

觸發與適用範圍

1. 觸發時機: 正在新建、改寫、或審查任何 SKILL.md（含本 repo 與 user-scope skill）的正文時。
2. 適用對象: skill 的 Purpose、Rules、SOP、範例與其他說明段落；frontmatter 的 YAML 不受此 skill 約束。
3. 跳過: 使用者明確要求保留特定 Markdown 裝飾（例如對外發布的 README）時，以使用者當次指示為準。

嚴禁的裝飾

1. 不得使用粗體（** 或 __）。
2. 不得使用斜體（* 或 _）。
3. 不得使用底線（<u> 或 HTML underline）。
4. 不得為了「看起來整齊」而濫用 Markdown Table；不符合本文件表格條件時，一律改用標題、列表或「主題: 內容」排版。

允許的結構元素

1. 允許 Markdown Header: H1（#）、H2（##）、H3（###）。標題是結構編排的主要手段，應保留。
2. 允許 Number List 與 Bullet List，用於步驟、要點、驗收條件。
3. 允許以冒號區分主題與內容，格式為「主題: 內容」或獨立一行主題後接縮排／列表說明。
4. 允許 Markdown Table，但只限於短小、原子化、欄位固定、需要橫向比較、且在 Text Mode 下不易折行的資料。
5. 允許程式碼區塊（```）僅在需要展示檔案片段或 before/after 對照時使用；區塊內可展示反例，但正文規則仍以本 skill 為準。
6. 允許水平分隔線（---）僅在章節邊界必要時使用，且不宜連續堆疊。

推薦的排版手法

1. 階層: 用 H2 / H3 切大段與小段，不要用視覺強調代替層級。
2. 定義: 用「術語: 說明」一行一條，或「術語」獨立一行後接 bullet 展開。
3. 步驟: 用有序列表 1. 2. 3.；平行要點用 - 或 * 無序列表。
4. 強調語意: 用更精準的用詞與標題命名表達重點，不靠 **加粗**。
5. 篇幅: 刪掉裝飾後應更短；若句子變長，優先拆成列表或多個 H3，而不是加符號。
6. 表格判斷: 先問「這份資訊的主要任務是橫向比較，還是逐段理解」；只有前者才優先考慮表格。

表格使用條件

1. 只有在每個 cell 都短小、原子化時才適合表格，例如狀態、型別、短標籤、短句定義。
2. 只有在所有列都共用同一組固定欄位時才適合表格；若每筆資料結構不同，不要硬塞。
3. 只有在讀者的核心任務是橫向比較欄位差異時才適合表格；若讀者要逐段理解概念，改用段落或小節。
4. 只有在一般 Text Mode 寬度下不易大量折行、欄位不會明顯跑版時才適合表格。
5. 只要任一 cell 出現段落型描述、列表、例外條件、推理說明、多步驟內容，就不應使用表格。

何時不要使用表格

1. 某一格開始超過一兩句話，或需要完整段落才能講清楚時。
2. 某一格需要列 bullet、編號步驟、分情境說明或補充例外時。
3. 每列資料的欄位其實不一致，只是勉強湊成同一張表時。
4. 資訊真正重要的是上下文與敘事順序，而不是欄位對照時。
5. 表格一貼進 Text Mode 就開始頻繁換行、難以編修時。

表格範例

允許使用表格的情況

條件: cell 短、欄位固定、需要橫向比較。

| 動詞 | 類型 | 說明 |
| --- | --- | --- |
| READ | D | 讀檔 |
| WRITE | D | 寫檔 |

不應使用表格的情況

Before（不建議）:

| 能力 | 說明 |
| --- | --- |
| clarify | 當 planner 產出一批待澄清問題時，這個 skill 會先把技術語言翻成白話，再一次性向使用者提問，最後把答案同步回工作流，讓後續 planner 能繼續推進。 |
| specify | 當使用者剛提出功能想法時，這個 skill 會先把需求整理成結構化 spec package，作為後續 clarify、tasks、implement 的上游輸入。 |

After（應產出）:

### clarify

- 角色: 工作流中段的澄清 skill
- 說明: 當 planner 產出一批待澄清問題時，先把技術語言翻成白話，再一次性向使用者提問，最後把答案同步回工作流，讓後續 planner 能繼續推進。

### specify

- 角色: 工作流上游的規格整理 skill
- 說明: 當使用者剛提出功能想法時，先把需求整理成結構化 spec package，作為後續 clarify、tasks、implement 的上游輸入。

撰寫與審查檢查清單

1. 全文搜尋 **、__、*斜體*、<u>，應為零結果（程式碼區塊內示範反例除外）。
2. 若正文出現表格，是否真的符合「cell 短小原子化、欄位固定、需要橫向比較、Text Mode 不易折行」四條條件。
3. 只要某格內容需要段落、列表、例外條件或推理說明，是否已改寫為 H3 + 列表。
4. 在 Text Mode 下直視檔案：標題層級是否一眼可辨、列表是否對齊、無需 Preview 即可編輯。
5. 本 skill 自身的 SKILL.md 亦須遵守以上規則（meta：寫給 AI 時亦同）。

反例（勿模仿）

1. 用 **重要** 標示關鍵字，Text Mode 下只會看到星號噪音。
2. 只因為「表格看起來比較整齊」就把長段落硬塞進表格。
3. 在列表項內再套 **粗體** 當小標；應改為子列表或 H3。
4. 為了「好看」加 emoji、blockquote 裝飾、或過多 --- 分隔；與 Text Mode 掃讀無關的視覺元素應刪除。

Few-Shot Examples

撰寫或改寫 SKILL.md 前，先 READ 本 skill 目錄下的成對範例。每一組都是同一個 skill 主題、同一個檔名，分別放在 Good/ 與 Bad/，用來對照「該怎麼寫」與「不該怎麼寫」。

範例清單

1. pdf-processing

   • Good: examples/Good/pdf-processing/SKILL.md
   • Bad: examples/Bad/pdf-processing/SKILL.md
   • 對照重點: Good 用標題與列表；Bad 濫用粗斜體、底線、blockquote，並把長段落硬塞進表格。

2. mermaid-class-diagram

   • Good: examples/Good/mermaid-class-diagram/SKILL.md
   • Bad: examples/Bad/mermaid-class-diagram/SKILL.md
   • 對照重點: Good 只在符號對照等原子資料用短表格；Bad 把設計說明與長句塞進多欄表格，並用裝飾符號代替結構。

使用方式

1. 先 READ 對應主題的 Bad 版，辨識哪些排版習慣要避開。
2. 再 READ 同主題的 Good 版，對齊應產出的 SKILL.md 風格。
3. 產出或審查目標 SKILL.md 時，以 Good 版為參考、以 Bad 版為反例檢查。
4. 若目標 skill 與上述兩個主題不同，仍套用同一套原則，不要複製範例的 domain 內容。