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 のみ
---
name: <slug> # ディレクトリ名と一致する必要がある
description: <1-2 sentence summary an agent uses to decide whether to load>
---
name と description は load-bearing。残りはすべて yfm の metadata: ブロックの下にカンマ区切りのスカラーとして入れ子にする — 任意で、インデックス・発見・オントロジーフックのための構造を加える。
サブファイルは YFM を持たない。 SKILL.md のみがローダでフィルタされるため、それだけ frontmatter を必要とする。他のすべてのファイル(references/*、usecase/*、EXAMPLE.md、*.report.md …)は、それを開くことを既に決めたエージェントによって直接読まれる — そこでの YFM は純粋なトークンコストであり、タイトルと冒頭行が既に与えている目的を復唱するだけだ。これらのファイルは # 見出しから始める。逸脱するにはファイル内で理由を述べる。
中国語ローカライズ版は、並行する SKILL.cn.md(各 skill ごとに 1 つ)を使う。1 ファイル内に複数言語を混在させない。
機械的チェック
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 段階で読み込む:
- YFM
description:— マッチングのためにエージェントのカタログへ自動的にロードされる。 エージェントは description を読んで、その skill をロードするかを決める。 - 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 の
sw-1000-no-orphan-docsで強制される。 - 推測 — テスト済みの事実を書くか、「untested」とラベルする。
- 絵文字 — skill のトピックが要求する場合を除く。