# Skill0 Writer

> skill0 文檔的寫作約定 —— 金字塔結構、行數上限、佈局規則。

- Skill: `x-cmd/skill0-writer-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add x-cmd/skill0-writer-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/x-cmd/skill0-writer-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: x-cmd (https://skillmd.com/u/x-cmd)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/x-cmd/skill0-writer-2

---


# skill0-writer

Skill0 文檔遵循 **金字塔原則**：agent 可能只讀前 10–30 行，所以最重要的信息必須前置。30 行之後的細節是 bonus，不是主力。

## 沒有規則能約束的事

- **清晰優先於簡潔。** 給錯答案的短文檔比給正確答案的長文檔更糟。
- **安全 / 警告必須 顯式** —— 使用 MUST、NEVER、DO NOT。把 caveat 寫成完整陳述，而不是括注。
- **不要展開常識。** 一個約定詞加一兩句話能講清就停。讀者已經知道 YAML、git、cache 是什麼；把 context 花在倉裏特有的東西上。理由是常見冗餘 —— 只在"看起來不對"時給一句理由。（`sw-1200`）
- **表只為真正的矩陣服務。** 3+ 列、行需要互相對照的。兩列表格是穿表格外衣的列表 —— 寫成列表。數據集應放在文檔旁的外部 `.tsv`，鏈過去，讓 `x tsv` 可以查詢。（`sw-1250`）

## YFM —— 僅 `SKILL.md`

```yaml
---
name: <slug>                  # 必須等於目錄名
description: <1-2 sentence summary an agent uses to decide whether to load>
---
```

`name` 與 `description` 是 load-bearing。其他都嵌套在來自 [yfm](../yfm/SKILL.md) 的 `metadata:` 塊下，做逗號分隔的 scalar —— 可選，為索引、發現、本體鈎子增加結構。

**子文件不帶 YFM。** 只有 `SKILL.md` 被 loader 過濾，所以只有它需要 frontmatter。其他文件（`references/*`、`usecase/*`、`EXAMPLE.md`、`*.report.md` …）由已經決定打開它的 agent 直接閲讀 —— 那裏的 YFM 是純 token 成本，重述標題與首行已經給出的目的。這些文件從 `#` 標題起。需要偏離就在文件內聲明原因。

中文本地化版本使用平行的 `SKILL.cn.md`（每個 skill 一份）。不要在一份文件裏混語言。

## 機械檢查

見 [skill0-writer.rule.yml](skill0-writer.rule.yml)。運行 `x rule lint skill0-writer.rule.yml` 與 `x rule check -r skill0-writer.rule.yml lib/skill0/`。覆蓋：YFM 存在 + name/description 字段、name 格式、行數 ≤ 100（理想 50）、section 順序 install → usage → advanced → links、純英文、無引言 / 無結論 / 無重複、無孤兒文件。

## 截斷安全性檢查

寫完後，停在第 30 行檢查：只讀到這裏的 agent 會不會形成錯誤理解？

如果是，把關鍵限定前置。前 30 行必須給出（即便不完整的）正確心智模型。30 行之後，再用細節擴展 —— 金字塔是自我修正的。

## 雙層加載：description 負責匹配，body 負責參考

Skills loader（Claude Code、Cursor、Continue 等）分兩階段加載 SKILL.md：

  1. **YFM `description:`** —— 自動載入 agent 的目錄用於匹配。agent 讀 description 決定是否加載該 skill。
  2. **Body** —— 匹配後按需加載。參考材料。

含義：

- **Description** = *它是什麼 + 何時加載* —— 關鍵字密集、觸發詞豐富、簡練。
- **Body** = *如何使用 + 參考* —— 示例、schema、邊緣情況、鏈向更深文檔的鏈接。

**不要在兩層之間複製內容。** description 傳達的，body 應該 *展開*，而不是複述同一面。body 的開頭段尤其不得羅列與 description 相同的特性 —— body 以參考領起，而非第二份摘要。

一個實操測試：完全刪掉 description，只讀 body 的前 30 行，agent 應該仍能看到 skill 做什麼、何時加載。如果只有 description 承載那些信息，body 在頂部就無可加 —— 把解釋挪進 body，讓 description 只帶標題。

## skill 是知識包，不是教程

skill body 是 **給 LLM 的簡報**，不是給初學者的課程。

- **能力** 在 LLM 裏。body 不教。
- **知識** 在 x-cmd 數據工具（`x wkp` / `x rfc` / `x cve`，NVD / MITRE / GHSA）與外部來源中。body 只指；agent 自己再取。
- **框定** 是 skill 的工作：命名問題形態、約定、結構化輸出、要用的 x-cmd 工具。

skill 承載解題角度、約定、輸出形態與源指針。它 **不** 承載能力（LLM 已經有了）、靜態數據（會腐）、或教程（用 sidecar）。

具體太細或太新的部分，推到 sidecar（`references/`、`ANALYTICS.md`）或外部常更文檔。

## 外部鏈接

收集兩類：**root links**（入口如 `llms.txt`、docs index）與 **useful links**（覆蓋 80% 用例的 20% 文檔的定向鏈接）。root 在前，useful 在後 —— AI 理解順序。**不重複** 除非強調至關重要。

## 軟 caveat（判斷題）

- **子文件（CLEANUP.md, references/*）** 可以比 SKILL.md 長，但前 20 行仍承重（同樣金字塔）。
- **必須** 從父 SKILL.md 鏈接每個子文件（前向鏈接必須）。從子文件回鏈父 SKILL.md **可選** —— usecase 文件通過路徑隱式引用父文件。由 `sw-1000-no-orphan-docs` 在 [skill0-writer.rule.yml](skill0-writer.rule.yml) 中強制。
- **猜測** —— 寫經過測試的事實，或標註"untested"。
- **Emoji** —— 除非 skill 主題需要。

## Related

- [yfm](../yfm/SKILL.md) — skill0-writer 強制第 1 層的 YFM 約定
- [naming](../naming/SKILL.md) — 命名也遵循 writer 規則
- [skill0-writer.rule.yml](skill0-writer.rule.yml) — 機械強制