Corpus2Skillの中核は、文書コーパスを一度だけオフラインで処理し、ナビゲート可能なスキルツリーへ「蒸留」するコンパイルパイプラインです。本ページでは、Load・Embed・Cluster・Summarize・Label・Buildの6段階を順に取り上げ、それぞれが何を入力し、何を出力するのかを具体的に解説します。
パイプラインの全体像
コンパイルパイプラインは、生の文書群を入力として受け取り、階層的に整理されたスキルディレクトリを出力する一方向の変換処理です。全体は6つの段階で構成され、前半の3段階（Load・Embed・Cluster）が構造の発見を、後半の3段階（Summarize・Label・Build）が意味づけと実体化を担当します。
重要なのは、この処理がコーパスの更新時にのみ実行されるという点です。LLMによる要約・ラベル生成のコストはコンパイル時に一度だけ発生し、サーブ時のクエリ処理には影響しません。検索インデックスの再構築に相当する作業を、意味構造の再蒸留として行うイメージです。
また、コンパイルの成果物が通常のファイル群である点は、開発運用の観点で見逃せない特性です。出力ディレクトリをそのままGitなどでバージョン管理すれば、「いつの時点のナレッジでどのようなツリーが生成されたか」を差分として追跡できます。パラメータを変えて再コンパイルした結果の比較も、ファイル差分の確認として実施できます。データベースのスナップショット管理に比べて、変更の見通しがはるかに良いワークフローです。
Load・Embed：読み込みとベクトル化
Load（読み込み）
最初の段階では、対象コーパスをファイルシステムから読み込みます。対応フォーマットは.txt、.md、.json、.jsonlの4種類です。社内マニュアルやヘルプセンター記事、FAQ集など、テキスト化できるナレッジであれば幅広く投入できます。この段階で各文書には内部IDが割り当てられ、以後のすべての処理と最終的なdocuments.jsonで参照されます。
投入前の準備として重要なのは、文書の単位を意識することです。Corpus2Skillは文書単位でクラスタリングとリーフへの割り当てを行うため、1ファイルに雑多な話題を詰め込んだ巨大文書よりも、話題ごとに分かれた適度な粒度の文書群のほうが、質の高いツリーになります。既存のヘルプセンターであれば記事単位、社内規程であれば章や条項のまとまりを1文書とするのが自然な出発点です。逆に、従来RAGで必要だった細かなチャンク分割の設計は不要です。
Embed（埋め込み）
次に、各文書をsentence-transformers系の埋め込みモデルでベクトル化します。既定のモデルはQwen3-Embedding-0.6Bで、多言語に対応した比較的軽量なモデルです。CLIの--embed-modelオプションで別のモデルに差し替えることもできます。ここで得られるベクトルは、次のクラスタリング段階で「意味的に近い文書同士」を見つけるための座標として機能します。
埋め込みモデルの選択は、ツリーの品質を左右する重要な設計判断です。既定のQwen3-Embedding-0.6Bは多言語対応のため日本語コーパスにも適用できますが、専門用語の多いドメインでは、その分野に強いモデルへ差し替えることでクラスタの意味的なまとまりが改善する場合があります。なお埋め込みはコンパイル時にのみ実行されるため、モデルを差し替えて再コンパイルし、生成されたツリーを見比べるという試行錯誤が、サーブ環境に影響を与えずに行える点も従来RAGとの違いです。
Cluster：再帰的クラスタリングによる階層構築
Cluster段階は、パイプラインの中で最もアルゴリズム的な工夫が詰まった部分です。文書ベクトルの集合に対して再帰的なK-meansを適用し、大きなクラスタをさらに小さなクラスタへ分割していくことで、ツリー構造を作り上げます。分割の粒度はCLIの--pオプション（分岐率）で制御され、1ノードからおおよそ何本の枝を伸ばすかが決まります。
単純な再帰分割だけでは、意味的にほぼ同じ内容のクラスタが別々の枝に分かれてしまうことがあります。そこでCorpus2Skillは凝集マージ（agglomerative merging）を組み合わせ、類似度の高いクラスタ同士を統合します。分割と統合を両方使うことで、「深すぎず浅すぎず、意味のまとまりが自然な」階層が得られます。トップレベルに並ぶスキルの最大数は--max-topで制限でき、エージェントが最初に読む鳥瞰ビューが煩雑になることを防ぎます。
Summarize・Label：LLMによる意味づけ
ツリーの骨格ができた後は、各ノードに「人間にもエージェントにも読める意味」を与える段階に移ります。Summarize段階では、クラスタごとに含まれる文書の内容を踏まえた説明文をLLMが生成します。この説明文は、エージェントが「この枝に降りるべきか」を判断する材料になるため、単なる要約ではなく、そのクラスタが扱う話題の範囲や特徴を伝える書き方が求められます。
Label段階では、ナビゲーション時の見出しとして機能する短いトピックラベルを、同じくLLMが生成します。ファイル名やディレクトリ名としても使われるため、簡潔さと識別性の両立が重要です。要約とラベルを別の段階に分けているのは、それぞれで求められる出力の性質（詳しさと短さ）が異なるためです。生成に用いるLLMは、CLIの--modelオプションで指定できます（例：claude-sonnet-4-6）。
日本語コーパスに適用する場合は、要約とラベルが日本語として自然に生成されているかを必ず確認してください。要約はエージェントの判断材料であると同時に、運用担当者がツリーを検証する際の読み物でもあります。業務用語や製品名が正しく保存されているか、ラベルが社内で通じる言葉になっているかは、生成後のSKILL.mdとINDEX.mdを数ノード分読むだけでも概ね判断できます。
この2段階はコンパイル処理の中で最もLLMトークンを消費する部分でもあります。コーパスが大きいほどノード数が増え、要約・ラベル生成の回数も増えるため、コンパイルコストの見積もりでは文書数だけでなく、生成されるツリーの規模を意識する必要があります。コスト全体の考え方は「コスト構造とプロンプトキャッシュ最適化」で詳しく扱います。
Build：スキルツリーの実体化と出力
最後のBuild段階では、これまでの成果物をファイルシステム上のスキルディレクトリとして書き出します。各ノードはディレクトリとなり、そのノードの説明を記したSKILL.md、子ノードへの案内をまとめたINDEX.md、そしてリーフが参照する文書本体を格納したdocuments.jsonが配置されます。ディレクトリ構成は.claude/skills/規約に準拠しており、Anthropic Skills APIと互換です。つまり、コンパイル結果はそのままClaude系エージェントの「スキル」として読み込ませることができます。
# コンパイルの実行例
python -m corpus2skill \
--input ./corpus_dir \
--output ./compiled_output \
--p 10 \
--max-top 8 \
--model claude-sonnet-4-6 \
--embed-model Qwen/Qwen3-Embedding-0.6B主なオプションの意味は次のとおりです。--pは分岐率で、各ノードから伸ばす枝の目安数を定めます。--max-topはトップレベルスキルの最大数です。また--compactを付けると、リーフのインデックスを統合したコンパクトな出力になり、小規模コーパスでのナビゲーション段数を減らせます。具体的な導入手順とサーブ方法は「導入手順」をご参照ください。
出力されたツリーの検証
Build段階の出力は人間が読めるMarkdownとJSONであるため、コンパイル後の検証を強くおすすめします。確認すべき観点は3つあります。第一に、トップレベルのスキル分割が業務の感覚と合っているか。担当者が見て「この分け方なら探せる」と思える分割になっていることが、エージェントにとっても良い鳥瞰ビューである可能性が高いといえます。第二に、SKILL.mdの要約が文書の内容を正しく代表しているか。要約が偏っていると、エージェントは誤った枝に誘導されます。第三に、ラベルの識別性です。似通ったラベルが並んでいる場合は、分岐率やコーパスの文書粒度を見直すサインです。この検証のしやすさは、ブラックボックスになりがちなベクトル検索インデックスとの大きな違いです。
- コンパイルは Load→Embed→Cluster→Summarize→Label→Build の6段階で、オフラインで一度だけ実行します。
- 埋め込みとクラスタリングで構造を発見し、LLMが要約とラベルで意味づけを行います。
- 出力は.claude/skills/規約のスキルディレクトリで、Anthropic Skills API互換です。
