writing-for-agentslisted

為任何代理消費的文件撰寫的參考 — 一個技能、一份 `AGENTS.md` / `CLAUDE.md`、一份透過指標觸達的文件。包裝不同；寫法不同不是問題：相同的槓桿讓每一份都可預測 — 代理每次執行都採取相同的_流程_，而不是產出相同的結果。 當您撰寫的文件是技能時，閱讀 [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md) 了解 frontmatter、呼叫選擇與路由器技能。 ## 脈絡指標（Context pointers） **脈絡指標**是代理脈絡中持有的引用，它指名某個不在脈絡中的材料，並編碼了觸達它的條件。技能的 description 是一個；`AGENTS.md` 中指名一份文件的一行是同一種物件。指標的_措辭_，而不是它的目標，決定了代理何時觸達該材料 — 以及多可靠。一個措辭軟弱卻指向必備目標的指標，是變異 bug：先磨利措辭，只有磨利失敗時才內嵌材料。 指標做兩件工作 — 說明材料是什麼，並列出應該觸發觸達它的**分支**（分支是文件處理的一個不同案例，因此不同的執行會走過不同的路徑）。每個永遠載入的指標的每個字都會在每一輪耗費成本，因此它比正文更需要毫不留情的修剪： - **前置第一個字** — 指標正是它做觸發工作的地方。 - **每個分支一個觸發詞。** 為單一分支改名的一系列同義詞是同一個分支寫了兩次；把它們合併，只保留真正不同的分支。 - **刪掉正文已承載的身分資訊。** ## 兩種負載（The two loads） 您新增的每份文件與指標都花費兩種預算之一： - **脈絡負載（Context load）** — 永遠載入的材料對代理視窗的成本：一行 `AGENTS.md`、一個技能 description、任何每輪都坐在脈絡裡的東西，無論是否觸發都花費 token 與注意力。 - **認知負載（Cognitive load）** — 施加在人類身上的成本：存在哪些文件，以及何時取用每一份。人類就是索引。這不是一個要最小化的成本 — 它是人類能動性的代價；把它花在人判斷重要的地方，在它不重要的地方移除它。 只有透過指標觸達的材料，以指標自身那行的代價逃離脈絡負載；完全沒有指標的材料則整個落在認知負載上。 ## 資訊階層（Information hierarchy） 一份文件由兩種內容類型組成 — **步驟**（代理執行的有序動作）與**參考**（按需查閱的定義、規則、事實）— 它們可以自由混合：全是步驟（一份配方）、全是參考（一份審查的規則、本技能）、或兩者兼具。核心決策是每個片段落在**資訊階層**的哪個位置，這是一個按代理多迫切需要該材料來排序的階梯： 1. **檔案內步驟** — 主要層級：代理做什麼，依序。 2. **檔案內參考** — 按需查閱。通常是一組名正言順的平坦同級（一份審查的每個規則在同一個橫檔上）— 這是恰當的安排，不是壞味道。 3. **揭露的參考** — 被推出��到一個獨立檔案，透過脈絡指標觸達，只在指標觸發時才載入。從同一資料夾中的同級檔案，跨到完全外部的參考，可以存放在任何地方、任何文件都可以指向它。 推太少下去，頂層會臃腫；推太多，您會藏起代理真正需要的材料。那個張力就是全部的決策。 **漸進式揭露（Progressive disclosure）** 是往階梯下走的動作 — 移出主檔案並放到指標後面 — 這樣頂層保持可讀。這��要不是 token 最佳化：這是階層被保護的方式。分支是最乾淨的揭露測試：內嵌每個分支都需要