指令用途

/writing-for-agents 涵蓋任何代理會消費的文件 —— 不只是 skills：

• Skills（這個 repo 的 SKILL.md 們）
• AGENTS.md / CLAUDE.md —— repo 層級的給代理的指令
• 代理透過指標讀到的文件（例如一個 skill 指向的共筆參考）

它是你建立或編輯 skills、或修改 AGENTS.md/CLAUDE.md 時的參考。它是模型觸發的 —— 當你在建立或編輯 skills、或改 AGENTS.md/CLAUDE.md 時，它會自動發動。

名稱變更：前身為 writing-great-skills，現已重構並改名為 writing-for-agents。舊名已移除（無別名）—— 在新名下重裝即可。

核心觀念

單一真相來源（Single source of truth）

現在「單一真相來源」延伸到文件之外的環境 —— package.json scripts、config 檔、目錄結構、--help 輸出，這些本身就是權威的。一份重述它們的文件，是查詢的快取，只有在查詢昂貴時才值得它的負載。

正向目標：快取代理無法靠查得知的東西（未寫下來的慣例、選擇背後的理由、config 不會自白的 gotcha），把一檔一查的東西留給環境 —— 它們在那裡不會過時。

快取（Cache，修剪觀念）

GLOSSARY.md 已合併進 SKILL.md（一個 term 一份權威處理；_Avoid_ 同義詞清單與獨立的 Predictability 定義已移除）。skill 專屬的機制（frontmatter、model- vs user-invoked、router skills、invocation 切分）揭露到新的 SKILL-MECHANICS.md。

轉向（Steering）—— 語言的兩個失敗模式

在 /writing-great-skills 旁加了兩個 Steering 失敗模式，都關於「你以為無關」的語言仍在轉向代理：

• 否定（Negation）—— 大象：用禁止來轉向。命名不要做什麼會把被禁止的行為拉進 context，讓它更可用，而非更少（別想大象）。解法是提示正向。
• 負空間（Negative Space）—— 空無：對你省略的東西所做的轉向視而不見。skill 不表的每一個決策，都被委派給代理的先驗，而非保持中立 —— 所以解法是讀一遍草稿、為它的沉默負責，每個省略都刻意決定（填補，或留作真實的分支）。

兩者作為兩個 entry，不合一 —— 它們帶不同診斷與不同解方，各自是完整的 SKILL.md 失敗模式項目。

實戰對話範例

範例一：自動觸發（模型觸發）—— 建立新 skill

• You:

  我想建一個 skill 來自動產生 changelog。

• AI:

  我在寫這個 skill 時會套用 writing-for-agents。幾個關鍵：

  • 單一真相來源：package.json 已經有 version 與 scripts，skill 不該重述它們 —— 而是快取「為什麼用 conventional commits」「commit type 對應 changelog section 的映射」這種查不到的。
  • 否定 → 正向：不寫「不要包含 test commits」，改寫「只包含 feat:、fix:、BREAKING CHANGE」。
  • 負空間：我草稿裡沒講的 —— 例如要不要含 merge commit？我刻意決定：不含，並留作 branch（讓 user 明確覆寫）。

範例二：編輯 CLAUDE.md

• You:

  幫我review一下我們 repo 的 CLAUDE.md。

• AI:

  用 writing-for-agents 檢查：

  • 快取味：## Build 區塊 restates 了 package.json 的 scripts（pnpm build、pnpm test）—— 這是查詢的快取，移除；改成指向「看 package.json 的 scripts」即可。
  • 負向轉向：「不要直接 push 到 main」—— 大象。改成正向：「所有變更走 PR，base 是 main」。
  • 負空間：你沒提 deploy 流程 —— 如果代理不該碰 deploy，明說「deploy 由 CI 自動執行，手動 deploy 不要做」；否則代理會用它的先驗猜。

SKILL-MECHANICS.md 揭露的機制

這個 skill 把過去藏在 SKILL.md 內的 skill 專屬機制揭露到獨立的 SKILL-MECHANICS.md：

• frontmatter：name、description、disable-model-invocation 的用法。
• model-invoked vs user-invoked：誰能觸發、何時自動觸發。
• router skills：像 /ask-matt 這種作為索引、不直接做事的 skill。
• invocation 切分：user-invoked skill 可呼叫 model-invoked skill，但絕不呼叫另一個 user-invoked skill。

何時應該使用

• 建立新 skill：套用單一真相、正向表述、負空間檢查。
• 編輯既有 skill：特別是它變得冗長或失效時。
• 改 AGENTS.md / CLAUDE.md：這些是代理讀的指令，同樣原則適用。
• 驗證 skill 在佈署前有效。

何時不應該使用

• 寫給人類讀的文件（README、教學）—— 這是為代理讀的文件，人類文件的標準不同。
• 一次性 ad-hoc 指令：不必上 skill 工藝，直接打在聊天裡。
• 純程式碼變更：這是文件工藝 skill，不是程式碼 skill。

與其他技能的關係

/writing-for-agents 是 productivity bucket 的模型觸發 skill —— 當你在建立/編輯 skills 或改 AGENTS.md/CLAUDE.md 時自動發動。它是這個 repo 自己維護 skills 時用的 meta-skill。不確定該用哪個 skill 時，用 /ask-matt 來路由。