x-teach-me

name	x-teach-me
description	ドキュメント・実装・アーキテクチャを、調査・推測・実地検証を踏まえて段階的に解説し、その過程と結論をMarkdownドキュメントとして書き出すスキル。「〇〇の仕組みを理解したい」「コードベースを読み解きたい」「設計の意図まで把握したい」「他の人に説明できるレベルで学びたい」「調査結果をドキュメントに残したい」など、深い理解や学習記録の作成を目的とする依頼に使用する。複数ファイルにまたがる調査や、Markdownドキュメントとして残す必要がある場合は積極的に起動する。「〇〇って何？」「ざっくり教えて」など2〜3文で答えられる一問一答の質問には使わない。
allowed-tools	["AskUserQuestion","Read","Bash","Glob","Grep","Write","Edit","WebFetch","mcp__playwright__*","mcp__*","TaskCreate","TaskUpdate","TaskList"]

対象のドキュメント・実装・アーキテクチャを調査し、その目的・構造・意思決定を段階的に解説します。読解だけでなく、ローカルでの実行・観察・小さな改変、および利用可能なMCPツール(Playwright・WebFetch・各種コネクタ)を組み合わせ、過程と結論をMarkdownドキュメントとして書き出します。

着手前に学習の目的と完了条件をユーザーと合意し、章立てが完了条件に沿っているかを常に確認しながら進めます。最終的にユーザーが自分で応用・拡張できる理解と、後から読み返せる学習記録を残すことを目指します。

詳細ルールは以下の参照ファイルに分割しています。各フェーズの着手前に必ず読んでください。

• references/document-rules.md — 成果物のMarkdownルール(コードブロック・図表・文章スタイル)
• references/question-guide.md — AskUserQuestionの使い方と質問テンプレート
• references/doc-template.md — ドキュメントの初期テンプレート

スキルを起動したら、作業を始める前にreferences/doc-template.mdを読んで成果物の構造を把握します。どんなドキュメントを作るかを先に理解しておくと、各フェーズで何を読み・何を書くかが明確になります。

タスク登録（実行開始時に必ず実施）

フローを開始する前に、全ステップをTaskCreateで登録します。各ステップを開始するときTaskUpdateでin_progressへ、完了したときcompletedへ更新します。

#	subject	blockedBy
1	目的とゴールの合意	—
2	出力先の合意とファイル作成	1
3	静的探索	2
4	動作環境の把握	3
5	構造と意思決定の推測	4
6	解説計画の提示	5
7	段階的な解説	6
8	小さな改変による定着	7
9	完了判定とまとめ	8

流れ

1. 目的とゴールの合意(ドキュメント作成前)

学習の目的・完了条件・スコープ外を確認します。目的が曖昧なまま進めると章立てが発散するため、question-guide.mdの「フェーズ境界の質問の型」を参照してAskUserQuestionで1問ずつ確認します。合意できたら内容を口頭(チャット)で復唱してからファイル作成に進みます。

2. 出力先の合意とファイル作成

出力先(既定: docs/learn/<topic>.md)・粒度・実行範囲をAskUserQuestionで確認します。doc-template.mdのテンプレートを使い、目的・完了条件・スコープ外を埋めた状態とし、Writeを呼び出して初期ファイルを作成します。

3. 静的探索

Glob/Grepで関連ファイル(import元・呼び出し元・テスト・型定義・設計ドキュメント・設定ファイル)を洗い出します。Readで対象本体とREADME・コメント・package.jsonなどを読み、「参照一覧」セクションとしてドキュメントに記録します。

4. 動作環境の把握

依存関係・ビルド・実行・テスト・型チェック方法を特定します。すぐ動かせる例(examples/・fixtures/・CLIの--help)を探します。利用可能なMCPツールを棚卸しし(Playwright・WebFetch・接続済みコネクタ)、対象の性質と照らしてどのツールがどの検証に使えるかを「動かし方」セクションに併記します。

5. 構造と意思決定の推測

責務・入出力・依存先・呼び出し関係を整理したら、まずMermaid図として可視化します。図を先に書くことで関係性の抜けや矛盾に気づきやすくなるため、文章での解説はその後に書きます。設計上の選択を推測し、根拠(構成・命名・依存・コミット履歴)を併記します。静的事実・実行で検証すべき推測・実行しても確かめにくい意図、の3層に整理します。

6. 解説計画の提示

章立て(例: 全体像 → 動作確認 → 主要コンポーネント → 個別の意思決定 → 応用ポイント)をドキュメントの目次に書き出します。各章で「読む」「動かす(Bash/MCP)」「変えてみる」のどれを行うかを明示し、各章がどの完了条件に貢献するかを併記します。貢献しない章は計画から外します。AskUserQuestionで開始章・粒度・実行範囲を確認します。

7. 段階的な解説(章ごとに 読む → 動かす → 解釈する → 書く)

章ごとに以下を繰り返します。構造を説明する章では必ず図を先に書いてから文章で補足します。図のないまま箇条書きだけで済ませることはしません。

1. 静的に読み取れる内容をドキュメントに書きます
2. 仮説を立て、最小コストで確かめられる実行手段を提示します
3. ユーザー同意のもと実行し、結果をコマンドと出力のブロックとしてドキュメントに残します
4. 結果と仮説の差分を解釈し、推測を事実に格上げするか、別の仮説を立てます
5. 章の末尾に「この章で確かめられたこと/残った疑問」を3〜5行で書きます

章を書き終えたらAskUserQuestionで確認し、修正・補足・次章の方向を決めます。短いトピックでも省略しません。

解説のルールを守ります。

• 全体像(目的・責務・境界)から始め、徐々に詳細に降りていきます
• 「何をしているか」だけでなく「なぜそうなっているか」を伝えます
• 静的事実・実行で確認した事実・推測の3層を明確に区別し、文中で明示します(例:「(コードより)」「(実行で確認)」「(推測)」)
• 推測は可能な限り実行で検証し、事実に格上げします
• 抽象的な記述には必ず具体的な参照(ファイルパス・行番号・コード片・実行結果)を添えます

8. 小さな改変による定着(任意)

ユーザーが希望すれば、安全な範囲で改変実験を行います(例: ログ追加・分岐の差し替え・テスト追加)。改変前後の差分・観察結果・解釈をドキュメントの「実験ログ」章に残します。変更はコミットせず、確認後に元へ戻します。

9. 完了判定とまとめ

冒頭で合意した完了条件を1つずつ照合し、達成度を「完全/部分/未達」のいずれかで明示します。未達のものは「なぜ達成できなかったか」「次に何があれば達成できるか」を書きます。「確認できた事実/残った推測/踏み込まなかった領域/次の一歩」をドキュメント末尾にまとめます。進行中マーカーを外して完成版とし、出力先のファイルパスをユーザーに提示して締めます。

実行・実験のルール

• 実行は読解の補強であり、目的化しません。動かしただけで終わらせず、必ず解釈に戻してドキュメントに書きます
• 副作用の小さい操作を優先します(--help・--dry-run・--version・テスト実行・型チェック・ls/tree/cat系)
• 破壊的な操作・外部ネットワーク呼び出し・認証情報を要する操作は、実行する前にユーザーへ必ず確認します
• 既存のテスト・スクリプト・例があれば、まずそれを動かします
• 実験は仮説と対で行います(「もし〜なら、〜という出力になるはず」を先に書いてから実行します)
• 失敗・予期しない出力こそ学習機会として扱い、解釈をドキュメントに残します

MCPツールは積極的に使います。WebUIを含む対象ではPlaywright MCPを必ず検討します。ライブラリやフレームワークが対象のときはWebFetchで公式READMEやAPIリファレンスを直接取得して引用します。ツール選択は「何を確かめたいか」から逆算し、スクリーンショットを目的ではなく仮説の検証手段として使います。取得したスクリーンショット・ログ・引用は出力先ドキュメントの近くに配置し、本文から相対パスで参照します(例: docs/learn/<topic>.assets/01-initial-state.png)。