| 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. 段階的な解説(章ごとに 読む → 動かす → 解釈する → 書く)
章ごとに以下を繰り返します。構造を説明する章では必ず図を先に書いてから文章で補足します。図のないまま箇条書きだけで済ませることはしません。
- 静的に読み取れる内容をドキュメントに書きます
- 仮説を立て、最小コストで確かめられる実行手段を提示します
- ユーザー同意のもと実行し、結果をコマンドと出力のブロックとしてドキュメントに残します
- 結果と仮説の差分を解釈し、推測を事実に格上げするか、別の仮説を立てます
- 章の末尾に「この章で確かめられたこと/残った疑問」を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)。
