Reference Authoring Standards — Skill reference 撰寫品質規範
Reference Authoring Standards — Skill reference 撰寫品質規範
本文件為 compositional-writing Skill 的 reference 撰寫品質規範。適用對象：新增或修改本 Skill 任何 reference 的作者（人類或代理人）。
自包含聲明：閱讀本文件不需要先讀其他 reference。品質驗收 metric（M1-M2）見
meta-metrics.md；本文件聚焦「如何寫出符合品質的 reference」。
何時參閱本文件
| 觸發情境 | 動作 |
|---|---|
| 新增一份 reference | 遵循本文件的結構模板和品質標準 |
| 修改現有 reference | 確認改後仍符合五項必要要素 |
| 審查 Skill PR/Ticket | 逐項對照本文件的「驗收清單」 |
| 懷疑某 reference 違反原子化 | 執行「職責單一性測試」 |
一份合格 Reference 的五項必要要素
要素 1：情境聲明（何時讀這份文件）
每份 reference 的開頭必須有明確的「情境說明」段落，讓讀者在 30 秒內判斷適用性。
必須回答的問題：
- 這份 reference 服務哪種寫作情境？
- 讀者帶著什麼問題進來？
- 不適用的情境是什麼？
範本：
1本 reference 為「撰寫 prompt / instruction / Agent 派發」情境。
2
3適用：給 AI 模型的指令；Ticket Context Bundle；結構化派發 prompt。
4不適用：文件（見 writing-documents.md）；程式碼註解（見 writing-code-comments.md）。反例（情境不明確）：
1本文件說明寫作原則的應用。要素 2：職責單一性（原子化測試）
每份 reference 只服務一個讀者群體、回答一類問題。
判斷方法（原子化測試）：
| 問題 | 若需要「和」連接兩個答案 | 行動 |
|---|---|---|
| 「這份文件的讀者是誰？」 | 兩個不同讀者群體 | 必須拆分 |
| 「讀者帶著什麼問題來？」 | 兩類不相關問題 | 必須拆分 |
| 「讀完後讀者能做什麼？」 | 兩件不相關的事 | 必須拆分 |
反例（雙重職責）：
一份 reference 同時說明「如何撰寫 prompt」AND「如何撰寫其他 reference」——兩個讀者群體、兩種產出，必須拆分。
要素 3：自包含性（M2 通過）
讀者不看 SKILL.md 和其他 reference 的情況下，能獨立理解並套用。
自包含清單：
- 開頭有情境說明（不依賴 SKILL.md 判斷適用性）
- 文件內所有原則在本文件內展開（不引用其他 reference）
- 專有名詞在首次出現時給出就地定義
- 無「見 writing-xxx.md」的交叉引用（禁止鏈式）
可接受的外部引用：
- 引用外部公認資源（Anthropic 官方文件、業界標準）
- 引用 SKILL.md 觸發路由（只在「閱讀決策」表格中）
- 引用 meta-metrics.md 的量測方式（品質驗收場景）
要素 4：結構一致性
本 Skill 的所有 reference 遵循相同的段落骨架，便於讀者跨文件快速定位。
標準骨架：
1# [Reference 名稱]
2
3[1-3 行情境說明，含適用/不適用聲明]
4
5> **自包含聲明**：[說明閱讀本文件是否需要其他前置文件]
6
7---
8
9## 何時參閱本文件（或：情境定位）
10[觸發情境表格]
11
12## 為什麼 [情境] 需要獨立指引
13[說明此情境的特殊性，與一般文件的差異]
14
15## [核心原則 × 情境] 的應用
16（依情境選擇相關原則展開，每個原則含判斷標準 + 反例 + 正確做法）
17
18## [情境特有章節]
19（例如：Token 節省策略、結構化範例、自檢清單、反模式速查）
20
21## 延伸閱讀（可選）允許調整：
- 章節名稱可隨情境調整（「Token 節省策略」僅適用 prompt；「Log 結構化格式」僅適用 logs）
- 字數無硬性上限，但每個章節應只承載一個概念（M4 候選閾值 ≤ 3000 tokens）
要素 5：范例的具體性
範例必須足夠具體，讀者能「複製後略作修改直接套用」。
範例品質標準：
| 標準 | 說明 |
|---|---|
| 有反例對照 | 每個原則至少一組「錯 vs 對」範例 |
| 反例真實 | 反例應來自真實常見錯誤，不是刻意構造的極端案例 |
| 正例可直接套用 | 正例使用佔位符 {ticket_id} 等，讀者換掉佔位符即可使用 |
| 說明節省量（如適用） | Token 節省策略應標注估計節省比例 |
新增 Reference 的決策流程
在建立新 reference 前，先回答以下問題：
11. 此情境是否已有 reference 覆蓋？
2 是 → 擴充現有 reference（不新增）
3 否 → 繼續
4
52. 此情境的讀者群體是否唯一（原子化測試）？
6 否 → 拆分或重新定義情境邊界
7 是 → 繼續
8
93. 此情境是否需要對核心原則的「情境翻譯」？
10 否 → 考慮是否應放入 SKILL.md 核心原則速查表（不需要獨立 reference）
11 是 → 建立新 reference
12
134. 新 reference 加入後，SKILL.md 路由表的每個情境是否仍然唯一對應？
14 否 → 情境切分重疊，重新設計邊界
15 是 → 確認可新增驗收清單
新增或修改 reference 後，逐項確認：
職責單一性
- 原子化測試通過（一個讀者群體、一類問題）
- 無在標題或聲明中宣稱承擔多重職責
自包含性（對應 M2）
- 情境說明段落存在，30 秒內可判斷適用性
- 核心原則的必要內容在本文件內就地展開
- 無交叉引用其他 reference（只允許外部公認資源引用）
結構一致性
- 遵循標準骨架（情境說明 → 為什麼獨立 → 原則應用 → 情境章節 → 自檢清單）
- 所有原則有反例 + 正例對照
路由一致性（對應 M1）
- SKILL.md 觸發路由表已更新
- Directory Index 已更新
- 新情境與現有情境無重疊
范例品質
- 每個原則有至少一組「錯 vs 對」
- 正例使用 snake_case 佔位符，可直接套用
與 meta-metrics.md 的分工
| 文件 | 職責 |
|---|---|
| 本文件（reference-authoring-standards.md） | 如何寫出合格 reference（撰寫指南） |
meta-metrics.md | 如何量測寫作品質（M1-M5 量化驗收） |
兩者互補：先用本文件的標準寫，再用 meta-metrics.md 的方法量測。
Last Updated: 2026-04-18 Version: 1.0.0 — 從 writing-prompts.md 雙職責拆分：Skill 品質規範獨立為本檔，writing-prompts.md 保留 prompt 寫作情境