Metal

リポジトリの概念的DNA — その役割、手順、調整パターン — を汎用的なagentskills.io定義として抽出する。鉱石から貴金属を抽出するように、このスキルはプロジェクトが何であるか（そのエッセンス）と何をするか（その実装）を分離し、プロジェクトの組織的ゲノムを捕捉する再利用可能なスキル、エージェント、チーム定義を生成する — コードベースを再現することなく。

使用タイミング

• 新しいコードベースにオンボーディングし、コードに飛び込む前にその概念的アーキテクチャをマッピングしたい時
• 既存のプロジェクトからエージェントシステムをブートストラップする時 — 暗黙的なワークフローを明示的なスキル/エージェント/チーム定義に変換する
• クロスポリネーションのためにプロジェクトの組織的DNAを研究する時
• リファレンス実装に触発されたスキル/エージェント/チームライブラリを作成する時（コピーせずに）
• プロジェクトの構造が作成者のメンタルモデルとドメイン専門知識について何を明らかにするかを理解する時

入力

• 必須: リポジトリまたはプロジェクトルートディレクトリへのパス
• 必須: 目的の声明 — なぜエッセンスを抽出するのか？（オンボーディング、ブートストラップ、研究、またはクロスポリネーション）
• 任意: フォーカスドメイン — プロジェクトの特定の領域に集中する（デフォルト: 全体）
• 任意: 出力深度 — survey（調査+分析のみ）、extract（完全な手順）、またはreport（抽出+書面レポート）（デフォルト: extract）
• 任意: 最大抽出数 — 生成するスキル+エージェント+チームの合計上限（デフォルト: 15）

鉱石テスト

すべての抽出における中心的な品質基準:

この概念は完全に異なる実装で存在しうるか？

はいの場合 — それはmetal（エッセンス）である。抽出する。 いいえの場合 — それはgangue（実装の詳細）である。残す。

例: 天気アプリの「外部データソースを統合する」という概念はmetalである — サードパーティデータを取得するどのプロジェクトにも適用される。しかし「OpenWeatherMap v3 JSONレスポンスを解析する」はgangueである — 1つのAPIに固有のものである。

抽出されたスキルは特定のインスタンスではなく、タスクのクラスを記述すべきである。抽出されたエージェントはその人ではなく、役割を記述すべきである。抽出されたチームは組織図ではなく、調整パターンを記述すべきである。

手順

ステップ1: 調査 — 鉱床を調査する

判断なしにリポジトリ構造を調査する。採掘の前に地形をマッピングする。

1. ディレクトリツリーをGlobしてプロジェクトの形を理解する:
   • ソースディレクトリとその組織パターン（機能別、レイヤー別、ドメイン別）
   • 設定ファイル: package.json、DESCRIPTION、setup.py、Cargo.toml、go.mod、Makefile
   • ドキュメント: README.md、CLAUDE.md、CONTRIBUTING.md、アーキテクチャドキュメント
   • CI/CD: .github/workflows/、Dockerfile、デプロイメント設定
   • テストディレクトリとその構造
2. プロジェクトの自己記述（README、パッケージマニフェスト）を読み、その宣言された目的を理解する
3. タイプ/言語別にファイルを数えてスコープを把握し、主要な技術を特定する
4. プロジェクトの境界を特定する — どこで始まりどこで終わるか、何に依存し何を提供するか
5. 調査レポートを作成する:

Project: [name]
Declared Purpose: [from README/manifest]
Languages: [primary, secondary]
Size: [file count, approx LOC]
Shape: [monorepo/library/app/framework/docs]
External Surface: [CLI/API/UI/library exports/none]

期待結果: 事実に基づく調査 — 何がここにあるか、どの程度の規模か、プロジェクトが何であると主張しているか。まだ分類や判断はない。レポートはレビューではなく、地質調査のように読めること。

失敗時: リポジトリにREADMEやマニフェストがない場合、ディレクトリ名、ファイル内容、テストの記述から目的を推測する。プロジェクトが大きすぎる場合（ソースファイル>1000）、最もアクティブなディレクトリにスコープを絞る（gitログの頻度やREADMEの参照を使用する）。

ステップ2: 分析 — 組成を分析する

代表的なファイルを読み、プロジェクトが概念レベルで何をするかを理解する。

1. プロジェクトの異なる領域から5-10の代表的なファイルをサンプリングする — 網羅的ではないが多様に:
   • エントリーポイント（メインファイル、ルートハンドラー、CLIコマンド）
   • コアロジック（最もインポート/参照されるモジュール）
   • テスト（実装よりも意図された動作を明確に明らかにする）
   • 設定（運用上の懸念とデプロイメントコンテキストを明らかにする）
2. サンプリングした各領域について特定する:
   • ドメイン: プロジェクトはどの主題領域に触れるか？（例: 「認証」「データ変換」「レポーティング」）
   • 動詞: プロジェクトはどのアクションを実行するか？（例: 「検証」「変換」「デプロイ」「通知」）
   • 役割: コードはどの人間またはシステムのアクターに奉仕するか？（例: 「データエンジニア」「エンドユーザー」「レビュアー」）
   • フロー: どのアクションのシーケンスがワークフローを形成するか？（例: 「取り込み → 検証 → 変換 → 保存」）
3. 各発見について分類する:
   • 本質的: この問題を解決するどの実装にも存在する
   • 偶発的: この実装の技術選択に固有
4. 分析レポートを作成する: ドメイン、動詞、役割、フローの表に本質的/偶発的のタグを付ける

期待結果: コードのウォークスルーではなく、ドメイン用語集のように読めるプロジェクトの概念マップ。技術スタックに馴染みのない人がこのレポートからプロジェクトが何をするかを理解できること。

失敗時: コードベースが不透明な場合（重度のメタプログラミング、生成されたコード、または難読化）、ソースコードよりもテストとドキュメントに頼る。テストが存在しない場合、意図を読み取るためにコミットメッセージを読む。

ステップ3: 瞑想 — 実装バイアスを解放する

コードを読むことから生じる認知的アンカリングをクリアするために一時停止する。

1. どのフレームワーク、言語、またはアーキテクチャパターンがメンタルモデルを支配しているかに気づく — ラベルを付ける
2. HOWへの執着を解放する:「このプロジェクトはReactを使用している」は「このプロジェクトにはユーザーインターフェースレイヤーがある」になる。「PostgreSQLを使用している」は「永続的な構造化ストレージがある」になる。
3. 分析レポートの各発見について鉱石テストを適用する:
   • 「外部データソースを統合する」— どこにでも存在しうる？ はい → metal
   • 「Axiosインターセプターを設定する」— どこにでも存在しうる？ いいえ → gangue
4. 鉱石テストに失敗した発見をより高い抽象レベルで書き直す
5. 複数の視点が役立つ場合、以下のレンズを通じてプロジェクトを考慮する:
   • 考古学者: コードの構造は作成者のメンタルモデルについて何を明らかにするか？
   • 生物学者: 再現可能なゲノムvs特定の表現型は何か？
   • 音楽理論家: 形式（ソナタ、ロンド）vs特定の音符は何か？
   • 地図製作者: どの抽象レベルが有用なトポロジーを捕捉するか？

期待結果: 分析レポートからフレームワーク固有の言語がなくなっていること。すべての発見が鉱石テストを通過する。概念はポータブルに感じられる — どの言語やフレームワークのプロジェクトにも適用できる。

失敗時: バイアスが持続する場合（発見が特定の技術を参照し続ける）、反転を試みる:「このプロジェクトが完全に異なるスタックで書き直された場合、どの概念が生き残るか？」それだけがmetalである。

ステップ4: 精錬 — Metalをスラグから分離する

核心的な抽出ステップ。各本質的概念をスキル、エージェント、またはチームに分類する。

1. 精製された分析レポートの各本質的概念について、そのタイプを決定する:

Classification Criteria:
+--------+----------------------------+----------------------------+----------------------------+
| Type   | What to Look For           | Naming Convention          | Test Question              |
+--------+----------------------------+----------------------------+----------------------------+
| SKILL  | Repeatable procedures,     | Verb-first kebab-case:     | "Could an agent follow     |
|        | workflows, transformations | validate-input,            | this as a step-by-step     |
|        | with clear inputs/outputs  | deploy-artifact            | procedure?"                |
+--------+----------------------------+----------------------------+----------------------------+
| AGENT  | Persistent roles, domain   | Noun/role kebab-case:      | "Does this require ongoing |
|        | expertise, judgment calls, | data-engineer,             | context, expertise, or a   |
|        | communication styles       | quality-reviewer           | specific communication     |
|        |                            |                            | style?"                    |
+--------+----------------------------+----------------------------+----------------------------+
| TEAM   | Multi-role coordination,   | Group descriptor:          | "Does this need more than  |
|        | handoffs, reviews,         | pipeline-ops,              | one distinct perspective   |
|        | parallel workstreams       | review-board               | to accomplish?"            |
+--------+----------------------------+----------------------------+----------------------------+

2. 抽出された各要素について:

   • 汎用化された名前を割り当てる — プロジェクト固有ではなく。「UserAuthService」はidentity-manager（エージェント）になる。「deployToAWS()」はdeploy-artifact（スキル）になる。
   • ソースプロジェクトを知らなくても意味が通じる1行の説明を書く
   • 派生元のソース概念を記録する（再現のためではなく、追跡可能性のため）
   • 鉱石テストを最終的にもう一度適用する

3. 一般的な分類エラーを防ぐ:

   • すべての関数がスキルではない — 個別の操作ではなく手順を探す
   • すべてのモジュールがエージェントではない — 判断を必要とする役割を探す
   • すべてのコラボレーションがチームではない — 異なる専門性を持つ調整パターンを探す
   • ほとんどのプロジェクトは3-8のスキル、2-4のエージェント、0-2のチームを生成する。20以上ある場合、抽出が細かすぎる。

期待結果: 各項目にタイプ（スキル/エージェント/チーム）、汎用化された名前、1行の説明がある分類されたインベントリ。ソースプロジェクトの特定の技術、API、またはデータ構造を参照する項目がないこと。

失敗時: 分類が曖昧な場合（これはスキルかエージェントか？）、問いかける:「これは何かをすること（スキル）か、何かをする誰かであること（エージェント）か？」スキルはレシピ、エージェントはシェフである。それでも不明な場合、デフォルトでスキルとする — スキルは後で構成しやすい。

ステップ5: 癒し — 抽出品質を検証する

抽出が正直かどうかを評価する — 多すぎず少なすぎず。

1. 過剰抽出チェック: 抽出された各定義を読み、問いかける:

   • 元のプロジェクトの独自ロジックをこれから再構築できるか？ → 詳細すぎる
   • 特定のライブラリ、API、データベーススキーマ、またはファイルパスを参照しているか？ → まだgangue
   • これは完全な実装手順か概念レベルのスケッチか？ → スケッチであるべき

2. 過少抽出チェック: 抽出された定義のみを（ソースプロジェクトなしで）表示し、問いかける:

   • これらに触発されたプロジェクトの種類を理解できるか？ → はいであるべき
   • 定義はプロジェクトの本質的な性質を捕捉しているか？ → はいであるべき
   • 表現されていない主要なプロジェクト機能があるか？ → いいえであるべき

3. 汎用化チェック: 各定義について:

   • 名前は異なる技術スタックで意味が通じるか？ → はいであるべき
   • 説明はフレームワークに依存しないか？ → はいであるべき
   • この定義は完全に異なるドメインのプロジェクトに有用か？ → 理想的にはい

4. バランスチェック: 抽出比率をレビューする:

   • 3-8のスキル、2-4のエージェント、0-2のチームがフォーカスされたプロジェクトの典型
   • 合計3未満の抽出は過少抽出を示唆する
   • 合計15以上は過剰抽出または不十分な汎用化を示唆する

期待結果: 抽出が適切な抽象レベルにあるという確信。各定義は異なる土壌で成長できる種であり、元の庭でしか生き残れない挿し木ではない。

失敗時: 過剰抽出の場合、抽象レベルを上げる — 特定のスキルをより広いものに統合し、類似のエージェントを単一の役割に集約する。過少抽出の場合、ステップ2に戻り追加ファイルをサンプリングする。汎用化チェックが失敗した場合、技術への参照を除去して説明を書き直す。

ステップ6: 鋳造 — Metalを型に流し込む

agentskills.io標準の出力ドキュメントを生成する。

1. 抽出された各スキルについて、骨格的な定義を書く:

# Skill: [generalized-name]
name: [generalized-name]
description: [one-line, framework-agnostic]
domain: [closest domain from the 52 existing domains, or suggest a new one]
complexity: [basic/intermediate/advanced]
# Concept-level procedure (3-5 steps, NOT full implementation):
# Step 1: [high-level action]
# Step 2: [high-level action]
# Step 3: [high-level action]
# Derived from: [source concept in original project]

2. 抽出された各エージェントについて、骨格的な定義を書く:

# Agent: [role-name]
name: [role-name]
description: [one-line purpose]
tools: [minimal tool set needed]
skills: [list of extracted skills this agent would carry]
# Derived from: [source role/module in original project]

3. 抽出された各チームについて、骨格的な定義を書く:

# Team: [group-name]
name: [group-name]
description: [one-line purpose]
lead: [lead agent from extracted agents]
members: [list of member agents]
coordination: [hub-and-spoke/sequential/parallel/adaptive]
# Derived from: [source workflow/process in original project]

4. すべての抽出を分析レポートにまとめる — スキル、エージェント、チームのセクションと要約テーブルを含む単一のドキュメント

期待結果: agentskills.io形式のすべての抽出定義を含む構造化されたレポート。各定義は骨格的（概念レベル、実装レベルではない）であり、create-skill、create-agent、またはcreate-teamスキルが詳細化する出発点として機能できること。

失敗時: 出力が15項目を超える場合、中心性で優先順位を付ける — このプロジェクトのドメインに最もユニークな概念を保持する。ほとんどのプロジェクトに存在する汎用概念（「manage-configuration」のような）は、異常なひねりがない限り削除すべきである。

ステップ7: 焼き入れ — 最終検証

完全な抽出を検証し、要約を作成する。

1. 抽出を数える: Nスキル、Nエージェント、Nチーム
2. カバレッジを評価する: プロジェクトの主要なドメインをまたいでいるか？
3. 独立性を検証する: ソースプロジェクトのコンテキストなしで各定義を読む — 単独で成立するか？
4. 完全なセットに対して鉱石テストを最終的に実行する:

Temper Assessment:
+-----+---------------------------+----------+------------------------------------+
| #   | Name                      | Type     | Ore Test Result                    |
+-----+---------------------------+----------+------------------------------------+
| 1   | [name]                    | skill    | PASS / FAIL (reason)               |
| 2   | [name]                    | agent    | PASS / FAIL (reason)               |
| ... | ...                       | ...      | ...                                |
+-----+---------------------------+----------+------------------------------------+

5. 最終要約を作成する:
   • 合計抽出数（スキル / エージェント / チーム）
   • カバレッジ評価（どのプロジェクトドメインが表現されているか）
   • 確信レベル（高 / 中 / 低）と根拠
   • 推奨される次のステップ: どの抽出定義を最初に詳細化すべきか

期待結果: 要約テーブル、確信評価、実行可能な次のステップを含む検証済みの分析レポート。レポートは自己完結的であること — ソースプロジェクトを見たことがない人が読んで抽出された概念を理解できること。

失敗時: 項目の20%以上が最終鉱石テストに失敗した場合、ステップ4（精錬）に戻り、より高い抽象レベルで再抽出する。カバレッジが特定されたドメインの60%未満の場合、ステップ2（分析）に戻り追加ファイルをサンプリングする。

バリデーション

• 調査レポートがプロジェクトの構造、言語、規模、宣言された目的をカバーしている
• 分析がドメイン、動詞、役割、フローを本質的/偶発的分類で特定している
• 瞑想チェックポイントが実装バイアスをクリアしている — 出力にフレームワーク固有の言語がない
• 抽出されたすべての要素が鉱石テストを通過している（実装の詳細ではなくエッセンス）
• スキルは動詞で、エージェントは名詞で、チームはグループ記述子で名前が付けられている
• すべての名前が汎用化されている — プロジェクト固有の参照がない
• 抽出数が典型的な範囲内にある（合計5-15、1でも30でもない）
• 出力定義がagentskills.io形式（フロントマター+セクション）に従っている
• 過剰抽出と過少抽出のチェックの両方が通過している
• 最終的な焼き入れ評価がカウント、カバレッジ、確信度、次のステップを含んでいる
• 完全な分析レポートがソースプロジェクトへのアクセスなしで理解可能である

よくある落とし穴

• ディレクトリ構造のミラーリング: 横断的な概念を抽出する代わりに、ソースファイルごとに1つのスキルを生成すること。metalはプロジェクトのファイルシステムではなく概念的構造を反映すべきである。20ファイルのプロジェクトは20のスキルを持たない。
• フレームワーク崇拝:「configure-nextjs-api-routes」ではなく「define-api-endpoints」を抽出する。フレームワークを除去し、パターンを保持する。鉱石テストがこれを捕捉する:「これはNext.jsなしで存在しうるか？」いいえなら、gangueである。
• 役割の膨張: すべてのモジュールに対してエージェントを作成すること。ほとんどのプロジェクトには異なる専門知識を必要とする本当の役割が2-5あり、20ではない。機能的な違いではなく、判断とコミュニケーションスタイルの違いを探す。
• 鉱石テストのスキップ: 最大の失敗モード。すべての出力は通過しなければならない:「この概念は完全に異なる実装で存在しうるか？」特定のライブラリ、API、またはデータスキーマを参照している場合、それはmetalではなくスラグである。
• 実装ガイドの生成: 抽出されたスキルは概念レベルのスケッチ（3-5の高レベルステップ）であるべきで、完全な実装手順ではない。create-skillで詳細化される種であり、完成品ではない。50ステップの抽出は再現であり、エッセンスではない。
• 名前の汎用化不足:「UserAuthService」はクラス名であり、概念ではない。「identity-manager」は役割である。「manage-user-identity」はスキルである。特定から普遍へと汎用化する。
• 調整パターンの無視: チームは調整がしばしば暗黙的であるため、抽出が最も難しい。コードレビューワークフロー、デプロイメントパイプライン、システム間のデータハンドオフ、承認チェーンを探す — これらがチーム構造を明らかにする。

関連スキル

• athanor — metalがプロジェクトにエッセンス抽出ではなく変革が必要であることを明らかにした場合
• chrysopoeia — コードレベルでの価値抽出; metalはコードの上の概念レベルで動作する
• transmute — 抽出された概念をドメイン間またはパラダイム間で変換する
• create-skill — 抽出されたスキルスケッチを完全なSKILL.md実装に詳細化する
• create-agent — 抽出されたエージェントスケッチを完全なエージェント定義に詳細化する
• create-team — 抽出されたチームスケッチを完全なチーム構成に詳細化する
• observe — 調査フェーズで馴染みのないドメインが明らかになった場合のより深い観察
• analyze-codebase-for-mcp — 補完的: metalは概念を抽出し、analyze-codebase-for-mcpはツールサーフェスを抽出する
• review-codebase — 補完的: metalはエッセンスを抽出し、review-codebaseは品質を評価する