distill-to-skill

スキルへの蒸留

あらゆる知識ソースを、よく構成されたエージェントスキルに変換します。これはプロセススキルであり、知識を抽出、選別、再構成、形式化する方法を扱います。スキル作成の機械的な部分（ディレクトリ構成、フロントマターの形式、検証、パッケージ化）については、skill-creator スキルを使用してください。

蒸留の考え方

スキルは要約ではありません。タスクに取り組むエージェントのための意思決定ツールです。

蒸留するときは、常に次の点を自問してください。

• 「作業中のエージェントにとって、この情報は役に立つか？」→ 残す
• 「これは背景情報や動機づけか？」→ 削る
• 「特定の言語／フレームワークに固有だが、考え方は普遍的か？」→ 置き換える
• 「エージェントが自分で推測できるか？」→ 削る
• 「エージェントのコードの書き方や意思決定が変わるか？」→ 残す

目標は、エージェントが元のソースを読んでいなくても、このスキルを読み込むだけですぐに、より良いコードを書いたり、より良い意思決定をしたりできることです。

ワークフロー

ステップ 1：ソースを読み込む

ソース資料全体を注意深く読みます。リポジトリの場合は、アーキテクチャ、主要なファイル、パターンを調べます。記事の場合は、最初から最後まで読みます。流し読みは避けてください。最も有益な洞察は、補足、脚注、「ちなみに」といった段落に埋もれていることがよくあります。

記事／ブログ記事の場合：

• URL を取得し、全文を読む
• 中心となる主張を記録する（通常 1～2 文）
• 実践的なルールと説明文を見分ける
• 具体的なコード例やパターンを記録する

リポジトリの場合：

• ディレクトリ構成、エントリーポイント、主要なモジュールを調べる
• 中核となる実装ファイルを読む（テストや設定は除く）
• 個別の実装ではなく、設計パターンを特定する
• TypeScript／型に関するテクニック、アーキテクチャ上の判断、ユーティリティのパターンを記録する
• 意図的に存在しないものを確認する。そこに最も興味深い洞察があることも少なくありません

同じテーマの複数のソースの場合：

• ソース間で共通する要点を見つける
• ソース同士が一致する点を記録する（信頼性の高いパターン）
• 意見が分かれる点を記録する（状況に応じた判断）

ステップ 2：応用可能な核心を抽出する

本質とパッケージングを分けます。

残す	削る
普遍的な原則	著者個人の体験
コードを含む具体的なパターン	動機づけの表現
意思決定ルール（「X の場合は Y を行う」）	この分野が存在する理由の背景説明
アンチパターンと落とし穴	他のアプローチとの比較
コピーして使えるユーティリティ	歴史的背景
チェックリスト	「参考資料」の推奨

判断基準： 元のソースが存在しなかったとしても、このスキル単独で役立つでしょうか？そうであれば、核心を正しく抽出できています。

ステップ 3：スキルの構成を決める

単一の概念で自己完結している → SKILL.md のみ（参照資料なし）

内容を約 100～250 行で完全に表現できる場合に使います。概念に一貫性があり、分割すると流れが失われる場合に適しています。

今日の作業からの例：

• parse-dont-validate — 1 つの中心的な考え方（検証よりパース）と実践的なルール
• karpathy-guidelines — 一連の行動ルール
• agents-md — 特定のファイル形式の書き方

幅広いトピックで深みがある → SKILL.md + references/

エージェントが個別に必要とする可能性のある、複数の異なるサブトピックがある場合に使います。SKILL.md には原則とクイックリファレンスを記載し、詳細は参照資料に記載します。

例：

• lean-ts-patterns — SKILL.md に 7 つの原則、分野別に 5 つの参照ファイル
• agent-first-repo — 3 つの柱と、各柱に関する 3 つの参照ファイル

複数の独立した考え方 → 個別のスキルに分割する

ソースに、異なる状況で必要となる概念が 2 つ以上含まれている場合は、スキルを分けます。相互に参照させることもできます。

例：OpenAI のハーネスエンジニアリングに関する記事は、agents-md（ファイルの書き方）と agent-first-repo（より広範なリポジトリ構成）に分割します。これらは異なる状況で必要となるためです。

判断の目安：

Does this source contain one core idea?
  YES → Single SKILL.md
  NO → Are the ideas used together?
    YES → SKILL.md + references/
    NO → Separate skills that cross-reference

ステップ 4：ユーザーのエコシステムに合わせて翻訳する

ソースは Haskell、Rust、Go、または平易な英語で書かれている場合があります。スキルでは、 ユーザーが希望する言語とエコシステムを使用してください。

• コード例： ターゲット言語で書き直します（通常は TypeScript/Bun）。
• ライブラリの参照： ターゲットエコシステムにおける同等のものに置き換えます。
• イディオム： ターゲット言語のパターンを使用します（例：newtype の代わりにブランド型を使う）。
• そのまま実行できること： スキル内のコードはコピー＆ペーストでき、動作するようにします。

元の洞察が言語に依存しない場合は、例にはターゲット言語を使い、 説明文は普遍的な内容にします。

ステップ 5：スキルを構成する

SKILL.md には次のテンプレートを使用してください。

---
name: skill-name
description: >-
  [What this enables]. [When to use it — specific scenarios].
  Triggers on: [concrete trigger phrases].
---

# Title

[1-2 line summary. Source attribution if from a specific article/repo.]

## [Core Concept / Principles]

[The distilled rules. Concise. Imperative voice. Code examples inline.]

## [Practical Patterns / Copy-Paste Code]

[Things the agent can use immediately. Concrete, not abstract.]

## [Anti-Patterns / What to Avoid]

[Common mistakes. What NOT to do is often more valuable than what to do.]

## [Checklist / Code Review Guide]

[Verification points. Things to check when reviewing code.]

参照ファイルはそれぞれ、次の条件を満たす必要があります。

• 対象範囲をまとめた 1～2 行の要約から始める
• 自己完結していること（SKILL.md を読まなくても理解できる）
• 関連するコンパニオンスキルの名前を記載する（内容全体は含めない）
• 約 300 行以内に収める

ステップ 6：説明を書く（最も重要な行）

YAML の description フィールドだけが、スキルを呼び出すかどうかを決定します。常にコンテキストに読み込まれます。慎重に書いてください。

• スキルが何であるかではなく、何を可能にするかから始める
• 具体的なシナリオとファイル形式を列挙する
• ユーザーが使いそうな具体的なトリガーフレーズを含める
• YAML で 3～5 行に収める

悪い例："型に関するブログ記事のパターン" 良い例："型駆動設計：システム境界で非構造化データを正確な型に変換します。 入力検証の実装、データ型の設計、冗長な null チェックを含むコードのレビュー時に使用します。トリガー：「parse don't validate」、 「make illegal states unrepresentable」、「input validation」。"

ステップ 7：検証する

完了前に、次の項目を確認してください。

• 元のソースを読まなくても、エージェントはこのスキルを使えますか？
• 各セクションは説明的（歴史や動機）ではなく、実行可能（ルール、パターン、コード）ですか？
• コード例はユーザーの希望する言語で書かれ、コピー＆ペーストできますか？
• SKILL.md は約 300 行以内ですか？（超える場合は内容を references/ に移します）
• description には具体的なトリガーフレーズが含まれていますか？
• 検証用のチェックリストまたはコードレビューガイドがありますか？
• コンパニオンスキルは重複させず、名前で参照していますか？
• セクションを削除するとスキルの有用性が下がりますか？下がらない場合は削除してください。

抽出パターン

反転

多くの記事はボトムアップで説明します。問題 → 探索 → 解決策。 スキルではトップダウンにします。ルール → 例 → アンチパターン。

エージェントを納得させる必要はありません。何をすべきかを伝える必要があります。

翻訳

学術的・理論的なソースでは、抽象的な例がよく使われます。ユーザーの領域における具体的で 現実的なシナリオに置き換えてください。

• 「NonEmpty リスト」→ TypeScript の [T, ...T[]] タプル型
• 「Sum 型」→ kind フィールドを持つ判別可能なユニオン
• 「スマートコンストラクター」→ parse 関数を持つブランド型
• 「モナド」→ 非同期パイプライン／Result 型

圧縮

5,000 語の記事は通常、約 150～250 行のスキルにまとめられます。圧縮率はおよそ 10:1～20:1 です。スキルが ソースと同じくらいの長さになっているなら、抽出ではなく要約になっています。

相互参照

他のスキルですでに扱われている概念に触れるソースを抽出する場合は、内容を再度説明せず、参照してください。その概念がここでどのように適用されるかを 2～3 文で説明し、詳しくはコンパニオンスキルを参照するよう案内します。

Parse data at system boundaries into precise types — don't let raw/untyped data
flow deep into business logic. For the full treatment of branded types, smart
constructors, and the shotgun parsing anti-pattern, see the `parse-dont-validate` skill.

ソースごとのヒント

ブログ記事： 通常、中心となるアイデアは1つで、動機が60％、例が30％、実践的なルールが10％です。10％の部分を抽出し、独自の例を加えて掘り下げます。

GitHub リポジトリ： コードそのものがコンテンツです。アーキテクチャのパターン、コピーする価値のあるユーティリティ関数、TypeScript のテクニック、そして意図的に含まれていないものに注目します。CI 設定、テスト基盤、ビルドツールは、要点でない限り無視します。

ドキュメント： すでに構造化されていますが、意思決定ではなく情報検索に最適化されています。「X は何をするか」ではなく、「どんなときに X を使うか」を軸に再構成します。

論文： 洞察が豊富ですが、形式的な記述に埋もれています。重要な定理や洞察を抽出し、実用的なコードパターンに落とし込み、証明は省きます。

動画の文字起こし： 情報密度が非常に低いです。話し手が具体的な指針を示す重要な場面を2〜3か所探し、残りは無視します。

具体的な抽出前後の例については、 references/examples.md を参照してください。