AltrinaAI/skill-miner

Skill Miner

コーディングエージェントとの過去のセッションに埋もれたシグナルを、新規または既存の 「エージェントスキル」に変換します。セッションがスキルになるのは、以下のゲートをクリアした場合のみです — 繰り返し可能かつ（改善の余地がある、または繰り返し依頼がある）:

1. 繰り返し可能 — タスクや知識が繰り返し発生する、または明らかに発生し得る。過去の繰り返しが最も強い証拠ですが、もっともらしく繰り返されるタスクも対象となります。真に一度きりのタスクは対象外です。 (必須)
2. 改善の余地がある — 意味のあるフィードバックがあり、次回が初回より優れていること:
   • 環境フィードバック — 作業の実行によって明らかになったもの: 失敗、この環境の繰り返し発生する癖、回りくどい経路とそのショートカット、苦労して得たヒューリスティック。これらは文字通りスキルです。
   • ユーザーフィードバック — ユーザーは専門家であり、そのフィードバックは貴重です。ユーザーの知識を引き出すために採掘します（訂正、ユーザーが知っていたより良い方法、誤った事実）。
3. 繰り返し依頼がある — ユーザーが同じことを繰り返し依頼する。一度抽出してしまえば、ユーザーは再度依頼する必要がなくなります。

パイプライン: 発見 → 抽出（安価なLLM、会話ごと） → グループ化、判断、生成。

0. 前提条件

小さなLLMにアクセス可能である必要があります。まず確認します:

python3 scripts/llm.py --check   # 使用するバックエンド、または有効化方法を表示します

OPENAI_API_KEY / GEMINI_API_KEY / OPENROUTER_API_KEY のいずれかを設定するか、claude / codex / gemini CLI をPATHに含めてください。モデルを上書きするには SKILL_MINER_MODEL を、バックエンドを強制するには SKILL_MINER_LLM を設定します。

1–2. パイプラインの実行（スクリプトが重い処理を安価なLLMで行います）

作業ディレクトリは起動ディレクトリのままにしてください。すべてのアーティファクトは ./out 以下に生成されます。

OUT=./out
python3 scripts/discover.py  --since 35 --out $OUT/inventory.jsonl       # エージェント間でトランスクリプトを検索
python3 scripts/extract.py   --inventory $OUT/inventory.jsonl --out $OUT/conversations.jsonl --workers 10

• discover.py は common.py:ADAPTERS（Claude Code、Codex、opencode。必要に応じて追加）の各アダプターを走査し、--since 日以内のセッションを保持します。ユーザーが明示的に要求しない限り、最大100会話から始めてください。高速サンプリングするには extract.py に --limit 15 を追加します。
• extract.py は各会話を解析し、JSONL行を出力します: agent, session_id, path, main_dir, datetime, n_user_turns, topics[], tasks[], skills_used[], env_feedback[], user_feedback[]。 main_dir は最も作業が行われた最深のフォルダ（編集/読み取り/言及されたファイルから判断）、起動cwdではありません。topics はスコープ（通常は1つで、グループ化の見出しとして機能）。tasks、env_feedback、user_feedback は、安価なLLMがユーザー自身の言葉からコピーした短い配列です（各 [] は典型的なセッション向け）。これらはゲートの3つの次元に対応します。安価な呼び出しはユーザーターンのみを参照するため、env_feedback は実行されたものについてユーザーが 言及した 内容であり、生のツール出力ではありません。ステップ4で検証してください。

3. 会話のグループ化

conversations.jsonl を読みます — 1行が1セッションです。行数が100以下の場合、ファイル全体がコンテキストに収まるため、そのまま読みます。（より多くの行を採掘した場合は、まず jq/grep で env_feedback / user_feedback が空でない行をざっと確認し、興味深い部分を読みます。）topics が <error> または些細/空の行は無視します。

タスクアーキタイプでクラスタリングします — 作業の 種類 であり、単なるディレクトリではありません（例：「CIデプロイデバッグ」「設定UIの反復」「依存関係移行」）。これにより 次元1（繰り返し可能） を判断します: どのタスクが繰り返されるか、または繰り返され得るか。次に、行全体から他の2つの次元を収集します:

• 次元2 — 次回タスクをより良く実行する方法を示す env_feedback と user_feedback（環境フィードバックを優先）。単一の苦労して得た教訓でも、それを中心にクラスターがなくてもリードになります。
• 次元3 — 多くのセッションの tasks に繰り返し現れる詳細（ユーザーが同じことを繰り返し依頼している）。

一度きりのセットアップ手順や単独の何気ない発言は除外します。簡潔なメモを残します: 名前付きグループ、その会話数、支配的な main_dir、それが持つフィードバック/繰り返し依頼、証拠として開くためのいくつかの例示的な path。

4. 判断と生成

references/quality-bar.md を読み、そのゲートを適用します: 繰り返し可能かつ（フィードバックまたは繰り返し依頼がある）。

1. 状況を把握する。 既存のスキルを確認し、拡張できるものがないか調べます — 特に、フィードバックが不足を示しているスキル。候補が重複する場合は、その SKILL.md を開き、その場で編集します。スキルファイルのパスを見つけるには:

   python3 scripts/skills_inventory.py
   

   これは編集するファイルを見つけるためだけに使用します。状況の把握については、あなたのコンテキストが真実の源泉です。候補が特定のリポジトリに焦点を当てている場合は、そこに既存のMarkdownドキュメント（README.md、設計ドキュメント、計画）がないか確認します。繰り返し発生する知識がスキルではなくそれらのドキュメントに属する場合は、レポートでユーザーにその旨を推奨します。
2. トランスクリプトで確認する。 各リードについて、1〜3のサンプルトランスクリプト（path フィールド）を開き、シグナルが本物であること、および 具体的内容（正確なルール、正確なエラーと回避策、ユーザーが示したより良いパス、繰り返し依頼）を捉えます。訂正箇所や [skill used: X] マーカーの周辺のユーザーの言葉を読みます。凝縮された行はユーザーターンのみを示しているため、トランスクリプトは環境が実際に何をしたかを検証する場所です。繰り返し発生する癖（詳細に記録）と一度きりのセットアップ（最大でも一行の落とし穴）を区別します。
3. ゲートに照らして決定する。 リードがスキルになるのは、それが繰り返し可能であり、かつ改善の余地（フィードバック）または繰り返し依頼のいずれかがある場合のみです。3つの次元は同等の重みを持ちます。タスクが一度しか出現しなくても明らかに繰り返される場合は、苦労して得た教訓を落とさないでください。また、改善点がなく繰り返し依頼もない繰り返し可能なタスクをリリースしないでください。
4. 最大5つのスキルを生成/変更する。 各スキルは具体的な内容として記述します: ルール、トリガー、手順/コマンド、癖と回避策 — ファイルパスは リポジトリルートからの相対パス（src/pages/Run.tsx）を使用し、トランスクリプトからコピーしたマシン固有の絶対パス（/home/<user>/…）は使用しません。配置場所:
   • 既存のスキルを拡張する場合 → スキルパスでそのままその場で編集します。フォークやコピーは行いません。
   • まったく新しいスキルの場合 → ~/.agents/skills/generated-skills/<name>/ 以下に、ユーザーがレビューおよびプロモートするためのステージングとして作成します。新しいスキルを直接ライブホームに配置しないでください。
5. 報告する。 作成/変更した内容と、それぞれがどの次元（複数可）から来たかをリストアップします。注目すべき却下された候補については、どの次元を満たさなかったかを1行で述べます。スキルの変更に加えて、または代わりに更新すべきリポジトリドキュメントがあれば含めます。

他のエージェントへの拡張

エージェントごとにトランスクリプトの保存方法は異なります。新しいエージェント（Gemini CLI、Cursorなど）をサポートするには、正規化されたレコード（_norm(...)）を生成する (discover_fn, parse_fn) のペアを common.py:ADAPTERS に追加します。パイプラインの残りの部分は変更不要です。Cursor（sqlite state.vscdb）はまだ配線されていません — opencodeのアダプター（DBバックエンド、SQLite）がテンプレートとして参考になります。

注意事項

• トランスクリプトに対する読み取り専用です。唯一の書き込みは --out アーティファクトと、生成または改善を選択したスキルです。新しいスキルは ~/.agents/skills/generated-skills/ 以下にステージングされ、編集は既存のスキルにその場で行われます。
• サブエージェント/レビュースレッド（Claude Codeのサイドチェーン、Codexの thread_source: subagent）はフィルタリングされます。実際のユーザー会話のみが採掘対象です。

結果の表示

単独で実行した場合、結果はプレーンファイルです: ./out 以下のアーティファクトと、変更したスキル（その場で編集、または generated-skills/ 以下にステージング）。このスキルには Skill Studio も同梱されています。これはデスクトップアプリで、ユーザーは実行をライブで監視し、generated-skills/ 以下にステージングされた各新しいスキルを Proposed カードとしてレビューして Accept または Discard でき、その場での編集はgit追跡された変更としてバージョン保存または元に戻すことができます。