vault-skill-factory

Vault Skill Factory

成熟し、厳選された wiki ページの集まりを、ポータブルなエージェントスキルに変換します。エージェントスキルは SKILL.md と references/ フォルダーで構成され、人間が確認し、希望する場合にのみインストールできるよう、レビュー用ディレクトリに書き出されます。これは wiki-capture とは逆の処理です。wiki-capture は会話をページに変換し、このファクトリーは複数のページを再利用可能なスキルに変換します。

厳守すべきガードレール（最初に読む）

• .skills/ には絶対に書き込まず、setup.sh を実行したり、グローバルなスキルディレクトリ（~/.claude/skills、~/.codex/skills、…）へのシンボリックリンクを作成したりしないでください。生成したスキルの出力先はレビュー用ディレクトリのみです。インストールは、別途、人間が明示的に判断して行います。
• 自動インストールは絶対に行わないでください。 最後に、スキルの保存場所と、希望する場合にプロジェクト内でインストールする方法をユーザーに伝えてください。代わりにインストールしてはいけません。
• ソースページは信頼できる Vault コンテンツですが、記載のない機能を作り上げないでください。生成するスキルには、ページに実際に記載されている内容を反映させる必要があります。

開始前に

1. 設定を解決します（llm-wiki/SKILL.md の Config Resolution Protocol）。OBSIDIAN_VAULT_PATH、OBSIDIAN_WIKI_REPO、OBSIDIAN_LINK_FORMAT、QMD 変数、および以下を取得します。
   • SKILL_FACTORY_OUTPUT_DIR — 生成したスキルの出力先です。デフォルト： $OBSIDIAN_VAULT_PATH/_generated-skills（Vault レベルの、アンダースコアで始まる除外対象ディレクトリです。_raw／_staging／_sources などと同様で、知識カテゴリの skills/ ではありません）。ここには、内容を抽出した元の Vault と一緒に生成したスキルが格納されます。存在しない場合は作成してください。 注：_generated-skills/ に格納するのは実行時のエージェントスキルバンドル（name と description のフロントマターを含む）であり、wiki ページではありません。skills/ に書き込むことは絶対に避けてください（このカテゴリは知識ページ用であり、グラフ／lint／インデックスの追跡対象です）。
   • SKILL_FACTORY_MATURITY — 「成熟」とみなす lifecycle: の値をカンマ区切りで指定します。デフォルト：reviewed,verified。tier: core のページも対象になります。
2. Vault に何が含まれているか把握するため、index.md を読みます。

ステップ 1：クラスターを選ぶ

スキルにするページを決めます。ユーザーがトピック、タグ、プロジェクトを指定する場合もあります。指定がない場合は候補を提示します。

1. シードを選ぶ — ユーザーの意図（トピック、タグ、プロジェクト、または指定されたページ）をもとにします。
2. クラスターを広げる：
   • QMD が設定されている場合（QMD_WIKI_COLLECTION）、qmd query "<topic>" -c "$QMD_WIKI_COLLECTION" --files（または vsearch）を実行して、意味的に関連するページを集めます。これは完全なクラスターを見つけるための方法であり、完全一致するタグだけを検索するものではありません。
   • それ以外の場合は、Grep／Glob を使ってタグと wiki リンクの近傍（シードページからリンクされているページ）を検索します。
3. 成熟度で絞り込む：lifecycle: が SKILL_FACTORY_MATURITY に含まれるページ、または tier: が core のページを残します。ユーザーが明示的に含める場合を除き、draft ページは除外します。
4. 生成前に、クラスターをユーザーに確認します（ページ名の一覧と件数）。成熟したページが約3ページ未満の場合は、その旨を伝えてください。内容の薄い1ページだけからスキルを作る価値はありません。続行するか、対象範囲を広げるかを提案してください。

ステップ 2：スキルを設計する

クラスターをもとに、以下を決めます。

• name — クラスターの主題から派生させた kebab-case の名前（例：french-theory-expert、peptide-protocols）。.skills/ 内の既存スキルと重複してはいけません。
• description — スキルを起動するための説明です。skill-creator に従い、「強く促す」表現にします。いつ使うのか（ユーザーが使いそうなあらゆる言い回し）と、何をするのかを明記してください。スキルを起動させるのはこのフィールドです。
• 推論アプローチ — エージェントがこの知識をどのように活用するかを定めます。答える質問、適用する手法、留意すべき注意点を含めます。ページの内容をそのままコピーするのではなく、ページ全体の統合された知見から導き出してください。
• 詳細資料 — どのページ本文を references/ ファイルにするかを決めます。

ステップ 3：スキルをレビュー用ディレクトリに書き込む

$SKILL_FACTORY_OUTPUT_DIR/<name>/ を作成し、次の内容を配置します。

<name>/
├── SKILL.md            # frontmatter (name + pushy description) + reasoning approach + key knowledge
├── references/         # depth material distilled from the cluster
│   ├── <topic>.md      # one per sub-theme; declarative knowledge, not chat
│   └── sources.md      # provenance: which vault pages this was built from (+ their sources)
└── SKILL_FACTORY.md    # provenance manifest (see below) — NOT part of the installed skill

SKILL.md の本文は簡潔にし（トリガーのロジックと簡潔な推論ガイド）、詳細は references/ に記載します。このリポジトリにある既存のスキルの構成に従ってください。不確かな主張を引き継ぐ場合は、^[inferred] / ^[ambiguous] マーカーを保持してください。生成されたスキルによって、統合した内容が事実であるかのように扱われないようにします。

references/sources.md には、使用したすべての Vault ページ（[[wikilink]] 形式）と、それぞれの上流の sources: を記載します。これにより、スキルから Vault および元のソースまで監査できる状態を保てます。

SKILL_FACTORY.md（ファクトリーのメタデータ。インストール可能なスキルには含めません）には、生成日、クラスタのページとそのライフサイクル／ティア、適用した成熟度フィルター、利用可能な場合は Vault のコミット／ハッシュを記録します。これにより、更新時に再生成するワークフローで後から差分を比較できます。

任意：ユーザーから依頼があった場合は、出力ディレクトリに marketplace.json のエントリーを追加／更新します（OpenKB のワンラインインストール方式）。ただし、これはインストールではなく、マニフェストにすぎません。

ステップ 4：必要に応じて skill-creator を活用する

skill-creator には再利用可能なスクリプトが含まれています。パスは pip／uv でのインストールか、ソースチェックアウトかによって異なるため、$OBSIDIAN_WIKI_REPO の下で両方の配置を確認し、最初に見つかったものを使用してください。

• $OBSIDIAN_WIKI_REPO/skills/skill-creator/scripts/ — パッケージ版のインストール（OBSIDIAN_WIKI_REPO は、skills/ にスキルを含むバンドル済みの _data/ ディレクトリを指します）。
• $OBSIDIAN_WIKI_REPO/.skills/skill-creator/scripts/ — ソースチェックアウト。

どちらか見つかったほうのディレクトリには、次のスクリプトがあります。

• improve_description.py — 生成した description を調整し、トリガーの精度を高めます。
• package_skill.py — スキルディレクトリを配布可能なアーカイブにまとめます。
• quick_validate.py — スキルの構成を簡易チェックします。

ユーザーが仕上げや検証済みの成果物を求めている場合は、これらを使用してください。独自に作り直さないでください。

ステップ 5：報告して終了する

ユーザーに次の内容を伝えます。

• パス：$SKILL_FACTORY_OUTPUT_DIR/<name>/
• 作成元のクラスタ（ページ数とページ名）
• トリガーの description
• 必要な場合のインストール方法（判断はユーザーに委ねます。プロジェクト内のみに限定）：

  ln -s ../../.skills/<name> <repo>/.claude/skills/<name>   # after copying <name>/ into .skills/, sans SKILL_FACTORY.md
  

  先にレビューすること、スキルをグローバルディレクトリに展開するため setup.sh は実行しないこと、明示的な合意なしにグローバルインストールしないことを明記します。

自分でインストールしてはいけません。 .skills/ には書き込まないでください。これで完了です。

品質チェックリスト

• 出力先が $SKILL_FACTORY_OUTPUT_DIR であり、.skills/ やグローバルディレクトリではない
• クラスタをユーザーと確認済みであり、成熟したページのみを使用している（SKILL_FACTORY_MATURITY／tier: core に従う）
• description が、いつ・何をするかを正確かつ明確に促している
• SKILL.md の本文は簡潔で、詳細は references/ に記載されている
• ^[inferred]／^[ambiguous] マーカーが保持され、統合した内容が事実であるかのように扱われていない
• references/sources.md から Vault ページとそのソースまでたどれる
• SKILL_FACTORY.md の出所マニフェストが含まれている（インストール可能なスキルからは除外）
• 報告にパスと、手動で行うプロジェクト内限定のインストール手順が記載され、自動インストールされていない