# Skill0 Writer

> skill0 ドキュメントの執筆規約 — ピラミッド構造、行数制限、レイアウトルール。

- Skill: `x-cmd/skill0-writer-11` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add x-cmd/skill0-writer-11`
- Raw SKILL.md: https://api.skillmd.com/api/skills/x-cmd/skill0-writer-11/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-11-15
- Page: https://skillmd.com/skills/x-cmd/skill0-writer-11

---


# skill0-writer

Skill0 ドキュメントは **ピラミッド原則** に従う：エージェントは先頭の 10〜30 行しか読まないかもしれないので、最も重要な情報は前に置く。30 行以降の詳細はボーナスであって、主戦力ではない。

## ルールでは捉えきれないこと

- **明瞭さは簡潔さに優先する。** 誤った答えを返す短いドキュメントは、正しい答えを返す長いドキュメントより劣る。
- **セキュリティ / 安全性の警告は MUST 明示的に** — MUST、NEVER、DO NOT を使うこと。caveat は括弧書きの付記ではなく、完全な文として記述する。
- **常識を展開しない。** 規約の言葉と一〜二文で要点を伝えられるなら、そこでやめる。読者は YAML、git、cache とは何かを知っている；コンテキストはこのリポジトリ特有のものに使ってほしい。理由はよくある冗長要素 — 理由が無く不自然に見えるときだけ一言付ける。（`sw-1200`）
- **表は真のマトリクスのためだけに。** 3+ 列で、行どうしを互いに対比して読む必要があるもの。2 列表は行列表構文を着たただのリストだ — リストとして書け。データセットはドキュメントの隣の外部 `.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:` ブロックの下にカンマ区切りのスカラーとして入れ子にする — 任意で、インデックス・発見・オントロジーフックのための構造を加える。

**サブファイルは YFM を持たない。** `SKILL.md` のみがローダでフィルタされるため、それだけ frontmatter を必要とする。他のすべてのファイル（`references/*`、`usecase/*`、`EXAMPLE.md`、`*.report.md` …）は、それを開くことを既に決めたエージェントによって直接読まれる — そこでの YFM は純粋なトークンコストであり、タイトルと冒頭行が既に与えている目的を復唱するだけだ。これらのファイルは `#` 見出しから始める。逸脱するにはファイル内で理由を述べる。

中国語ローカライズ版は、並行する `SKILL.cn.md`（各 skill ごとに 1 つ）を使う。1 ファイル内に複数言語を混在させない。

## 機械的チェック

[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）、セクション順 install → usage → advanced → links、英語のみ、導入 / 結論 / 反復なし、孤立ファイルなし。

## 切り詰め安全性チェック

書いた後、30 行目でレビューする：ここで読むのを止めたエージェントが誤った理解をしないか？

するのであれば、重要な限定を前に動かす。最初の 30 行は（たとえ不完全でも）正しいメンタルモデルを与えなければならない。30 行を超えたところから詳細で拡張する — ピラミッドは自己修正する。

## 二段ロード：description はマッチング用、body はリファレンス用

Skills ローダ（Claude Code、Cursor、Continue など）は SKILL.md を 2 段階で読み込む：

  1. **YFM `description:`** — マッチングのためにエージェントのカタログへ自動的にロードされる。
     エージェントは description を読んで、その skill をロードするかを決める。
  2. **Body** — マッチ後にオンデマンドでロードされる。リファレンス資料。

意味合い：

- **Description** = *何であるか + いつロードするか* — キーワード密度が高く、トリガが豊富で、簡潔。
- **Body** = *使い方 + リファレンス* — 例、スキーマ、-edge ケース、より深いドキュメントへのリンク。

**二段の間で内容を複製しない。** description が伝えるものは、body が *それを展開* すべきであり、同じ表面を復唱してはならない。特に body の先頭段落は description と同じ特徴を箇条書きにしてはならない — body は二番目のサマリではなく、リファレンスから始める。

実用テスト：description を完全に削除して body の最初の 30 行だけを読んだとき、エージェントはその 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`）や外部の常時更新ドキュメントへ押し出す。

## 外部リンク

2 種類を集める：**root links**（`llms.txt`、ドキュメントインデックスといった入口）と **useful links**（ユースケースの 80% をカバーする 20% のドキュメントへの的を絞ったリンク）。root を先に、useful を後に — AI は順序を理解する。強調が重要な場合を除き、**重複なし**。

## ソフト caveat（判断事項）

- **サブファイル（CLEANUP.md、references/\*）** は SKILL.md より長くてもよいが、最初の 20 行が依然として主戦力だ（同じピラミッド）。
- 親 SKILL.md からすべてのサブファイルへのリンクは **MUST**（前方リンク必須）。サブファイルから親 SKILL.md へのバックリンクは **任意** — usecase ファイルはパスにより親を暗黙に参照する。[skill0-writer.rule.yml](skill0-writer.rule.yml) の `sw-1000-no-orphan-docs` で強制される。
- **推測** — テスト済みの事実を書くか、「untested」とラベルする。
- **絵文字** — skill のトピックが要求する場合を除く。

## Related

- [yfm](../yfm/SKILL.md) — 第 1 層を強制する skill0-writer の YFM 規約
- [naming](../naming/SKILL.md) — 命名も writer ルールに従う
- [skill0-writer.rule.yml](skill0-writer.rule.yml) — 機械的強制

