Agent skill

deep-explain

プロジェクト内/外部対象に対する構造化された深層分析を提供する読み取り専用ユーティリティスキル。 スキル、機能、OSS、ライブラリ、技術コンセプトなど「これは何?」に対する一貫した回答を提供する。 例: - /deep-explain feature-pilot - /deep-explain 035 - /deep-explain @tanstack/react-query - /deep-explain <OSS名> - /deep-explain feature-pilot - /deep-explain feature-pilot --no-save

Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/deep-explain

SKILL.md

deep-explain

一言: 分からないことに対して /deep-explain X 一行で構造化された深層分析を受け取り、docs/explain/に自動保存される。


核心原則

  1. 自動検出: 対象タイプを自動で判別して適切なコンテキストソースを探索
  2. 一貫した構造: 常に同じ6セクション構造で出力(スキップ禁止)
  3. 読み取り専用: コード変更なし。分析と説明のみ実行(docs/explain/保存を除く)
  4. コンテキスト優先: 一般知識よりプロジェクト内の実際のファイルベース分析を優先
  5. 視覚化: 複雑なワークフロー/依存関係はdiagram-generatorエージェントでダイアグラム生成
  6. デフォルト保存: 分析結果は常にdocs/explain/に保存(--no-saveで無効化)

EXECUTION PROTOCOL (LIGHT)

このスキルは読み取り専用なので軽量プロトコルを適用する。

Pre-flight (必須)

スキル実行時に必ず以下のチェックリストを出力して確認する。

Pre-flight Checklist
├─ [ ] 分析対象識別: {target}
├─ [ ] 対象タイプ決定: {skill | feature | oss | library | general}
├─ [ ] コンテキストソース確認: {source_files}
└─ [ ] --no-save 有無: {yes | no}

Model Routing

作業 モデル 理由
コンテキスト探索 (Glob/Grep/Read) Haiku 単純なファイル探索、トークン節約
分析および出力生成 Sonnet 構造化された分析品質保証

ダイアグラム生成

分析対象がダイアグラム生成条件に該当すればdiagram-generatorエージェントを呼び出して視覚的ダイアグラム(.drawio + .svg)を一緒に生成する。(--no-save時にはダイアグラムを生成せずテキスト/ASCIIで表現)

ダイアグラム生成条件(1つ以上満たす時):

条件 ダイアグラムタイプ
呼び出す/呼び出されるスキルが3個以上 feature-pilot (15個呼び出し) Dependency ダイアグラム
パイプライン/ワークフローステップが4段階以上 feature-pilotの7 Stepパイプライン Data Flow ダイアグラム
ステートマシンが存在 CONTEXT.jsonの10個状態 State ダイアグラム
アーキテクチャレイヤーが3個以上 presentation/domain/data Architecture ダイアグラム

呼び出し方法(MUST: draw-ioスキル使用):

1. Skillツールで`draw-io`スキルを呼び出して.drawio XML生成
2. drawio CLIでSVG変換: drawio -x -f svg -t -o "{output}.svg" "{input}.drawio"

⚠️ .drawio生成後必ずdrawio CLI.svg変換まで完了する必要がある。 .svg変換が完了してこそダイアグラム生成が完了したことになる。 general-purposeエージェントに委任するとSVG変換を漏らす可能性があるので禁止。

保存場所: docs/explain/diagrams/{target}-{type}.drawio + .svg

SVG挿入(MUST): 生成された.svgファイルは必ず分析文書の該当セクションに挿入する:

  • セクション2(ワークフロー): ![{target} Data Flow](diagrams/{target}-data-flow.svg)
  • セクション6(関連項目マップ): ![{target} Dependency](diagrams/{target}-dependency.svg)

--no-save指定時: ダイアグラムエージェントを呼び出さず、セクション内テキスト/ASCIIダイアグラムで表現する。

Post-flight

なし(読み取り専用スキルなので検証不要)


対象タイプ自動検出

AIは入力を分析して以下のルールで対象タイプを自動決定する。 優先順位順でマッチし、最初のマッチで確定する。

検出ルール

優先順位 条件 タイプ コンテキストソース
1 .claude/skills/{input}/ディレクトリ存在 skill SKILL.md, MANIFEST.json
2 3桁数字またはdocs/features/*{input}*/マッチ feature CONTEXT.json, SPEC.md
3 docs/oss/{input}/またはoss-sources/{input}/存在 oss 分析文書、ソースコード
4 package.jsonのdependenciesに存在 library package.json, context7
5 上記どこにも該当しない general WebSearch、一般知識

タイプ別コンテキスト収集

skill タイプ

1. Read: .claude/skills/{name}/SKILL.md          ← 核心動作/プロトコル
2. Read: .claude/skills/{name}/MANIFEST.json      ← メタデータ/依存性
3. Glob: .claude/skills/{name}/templates/         ← テンプレート(あれば)
4. Grep: "calls".*"{name}" in .claude/skills/     ← 誰がこのスキルを呼ぶか?
5. Grep: "{name}" in CLAUDE.md                    ← プロジェクト指針での役割

── 関連項目収集(セクション6用)──
6. MANIFEST.jsonの"calls"配列 → 各下位スキルのMANIFEST.json読み込み(description, tier, public_api)
7. MANIFEST.jsonの"called_by"配列 → 各上位スキルのMANIFEST.json読み込み
8. Grep: "{name}" in docs/features/*/CONTEXT.json  ← このスキルを使用する機能
9. Grep: "{name}" in docs/                         ← 関連文書(explain/, oss/, technical/)

feature タイプ

1. Read: docs/features/{id}-*/CONTEXT.json        ← 機能コンテキスト(SSOT)
2. Read: docs/features/{id}-*/SPEC-*.md            ← 技術仕様(あれば)
3. Glob: docs/features/{id}-*/screens/             ← UI仕様(あれば)
4. Glob: lib/features/{feature_name}/              ← 実装コード構造
5. Read: docs/features/index.md                    ← 全機能リストでの位置

── 関連項目収集(セクション6用)──
6. CONTEXT.jsonの"dependencies" / "related_features" → 関連機能CONTEXT.json読み込み(title, status)
7. SPEC.mdのimport/provider参照 → 依存する他のfeatureバレルファイル識別
8. Grep: "{feature_name}" in .claude/skills/       ← この機能に関連するスキル
9. Grep: "{feature_name}" in docs/                 ← 関連技術文書/ADR

oss タイプ

1. Read: docs/oss/{name}/ 内全分析文書        ← 既存分析結果
2. Read: docs/oss/_catalog/mechanisms.json         ← カタログ内関連項目
3. Glob: oss-sources/{name}/                       ← ソースコード構造(あれば)
4. Read: oss-sources/{name}/README.md              ← プロジェクト説明(あれば)

── 関連項目収集(セクション6用)──
5. mechanisms.jsonでこのOSS所属メカニズムリスト → 各メカニズムのcontext_fit, decision確認
6. Grep: "{name}" in .claude/skills/               ← このOSSからインスパイアされたスキル
7. Grep: "{name}" in .claude/skills/               ← 関連スキル追加検索
8. Read: docs/oss/ 内他のOSS分析文書           ← 比較対象OSS(あれば)

library タイプ

1. Read: package.json                              ← バージョン、依存性
2. context7: 公式文書検索                          ← 最新API/ガイド
3. Grep: import.*{name} in src/                    ← プロジェクト内実際使用箇所
4. Read: package-lock.json                         ← 正確なインストールバージョン(必要時)

── 関連項目収集(セクション6用)──
5. package.jsonで一緒に使用する関連パッケージ識別(例: @tanstack/react-query → zod, axios)
6. Grep: "{name}" in src/features/                 ← このライブラリを使用するfeatureリスト
7. Grep: "{name}" in docs/                         ← 関連技術文書/ADR

general タイプ

1. WebSearch: "{対象}"最新情報                     ← 一般知識
2. Grep: {対象} in lib/ + docs/                     ← プロジェクト内関連性確認
3. context7: 関連ライブラリ文書(該当時)            ← 技術文書

出力構造(6セクション固定)

すべての分析は必ず以下の6セクションを全部含める。セクションをスキップしない。

情報が不足しているセクションは「情報不足 - {理由}」と表示する。

セクション1: 概要

markdown
## 1. 概要

- **一行要約**: {対象}は{核心機能}を実行する{分類}である。
- **存在理由(Why)**: {なぜ必要か?どんな問題を解決するか?}
- **なければ?**: {これがなければどうなるか?}

セクション2: ワークフロー

markdown
## 2. ワークフロー

- **入力**: {何を受け取るか?}
- **処理**: {内部で何をするか?}
- **出力**: {何を生産するか?}
- **トリガー**: {いつ/どのように実行されるか?}

**実行フロー**:
{テキストまたはダイアグラムでフロー表示}

セクション3: 核心メカニズム

markdown
## 3. 核心メカニズム

### {メカニズム1名}

{動作原理説明}

### {メカニズム2名}

{動作原理説明}

**構成要素関係**:

| 要素 | 役割 | 依存対象 |
| ---- | ---- | -------- |
| ...  | ...  | ...      |

セクション4: 比較分析

markdown
## 4. 比較分析

| 項目       | {対象} | {代案1} | {代案2} |
| ---------- | ------ | ------- | ------- |
| アプローチ | ...    | ...     | ...     |
| 長所       | ...    | ...     | ...     |
| 短所       | ...    | ...     | ...     |
| 適した状況 | ...    | ...     | ...     |

**選択根拠**: {なぜこれを選択したか / どんな状況で選択すべきか}

セクション5: 詳細情報

markdown
## 5. 詳細情報

- **設定/オプション**: {使用可能な設定、フラグ、パラメータ}
- **注意事項**: {よくある間違い、既知の制限事項}
- **関連項目**: {関連スキル/機能/文書リンク}

セクション6: 関連項目マップ(Relationship Map)

核心: 対象を単独で見ず、接続された生態系全体を眺める。 関連項目収集段階で収集したデータを基に作成する。

markdown
## 6. 関連項目マップ

### 呼び出し/依存関係(Dependency Graph)

{対象が呼び出すまたは依存する項目の関係を表示}

| 方向         | 項目              | 役割要約   | 関係                        |
| ------------ | ----------------- | ---------- | --------------------------- |
| → 呼び出し   | {skill/feature名} | {一行役割} | {どんな文脈で呼び出し/依存} |
| ← 被呼び出し | {skill/feature名} | {一行役割} | {どんな文脈で呼び出される}  |

### 関連スキル(Related Skills)

{対象と直・間接的に関連するAgent Skills}

| スキル     | Tier  | 関係タイプ                                     | 説明          |
| ---------- | ----- | ---------------------------------------------- | ------------- |
| {スキル名} | {1-3} | {calls/called_by/shares_data/同じパイプライン} | {1行関係説明} |

### 関連機能(Related Features)

{対象と関連するアプリ機能}

| 機能ID | 機能名   | 状態   | 関係           |
| ------ | -------- | ------ | -------------- |
| {XXX}  | {機能名} | {状態} | {どんな関係か} |

### 関連文書(Related Documents)

{対象を理解するのに役立つ文書}

| 文書     | パス   | 関連性             |
| -------- | ------ | ------------------ |
| {文書名} | {パス} | {なぜ関連があるか} |

タイプ別セクション6作成ガイド:

タイプ 主要焦点
skill calls/called_byスキル分析、所属パイプライン feature-pilotの11個下位スキル各々の役割
feature 依存feature、使用するサービス/スキル、関連SPEC 035の依存: ai_tutor, lesson, review
oss 抽出されたメカニズム、インスパイアされたスキル、カタログ位置 <OSS名> → turbo-mode, persistent-mode
library 一緒に使用するパッケージ、使用するfeatureリスト @tanstack/react-query → zod, axios; 30+ features
general プロジェクト内関連コード/文書(あれば) ATAM → oss-analyzer v3.0で使用

作成規則:

  • 関連項目が5個以下なら各々に対して2-3行説明追加
  • 関連項目が6個以上ならテーブルで要約し、核心3個のみ詳細説明
  • 関連項目がなければ「関連項目なし - {理由}」と表示(セクション自体は省略しない)

デフォルト保存動作

分析結果は常にファイルで保存される。--no-saveフラグで無効化できる。

保存ルール

  • 位置: docs/explain/{target}.md
  • ダイアグラム: docs/explain/diagrams/{target}-{type}.drawio + .svg(生成条件充足時)
  • ディレクトリ自動生成: docs/explain/, docs/explain/diagrams/がなければ生成
  • 形式: 上記6セクション構造 + メタデータヘッダー
  • ダイアグラムリンク(MUST): 生成された.svgは必ず分析文書内該当セクションに挿入:
    • セクション2(ワークフロー): ![{target} Data Flow](diagrams/{target}-data-flow.svg)
    • セクション6(関連項目マップ): ![{target} Dependency](diagrams/{target}-dependency.svg)

ファイルヘッダー

markdown
---
target: { 対象 }
type: { skill | feature | oss | library | general }
generated: { YYYY-MM-DD }
sources:
  - { コンテキストソースファイル1 }
  - { コンテキストソースファイル2 }
---

--no-save オプション

--no-saveが指定されれば対話内でのみ出力してファイルを生成しない。ダイアグラムも生成しない。


エラー処理

状況 対応
対象を見つけられない 類似名候補を提示して選択要請
コンテキストソースが空 general タイプにフォールバック、WebSearch 活用
曖昧な入力(複数タイプマッチ) マッチした候補を表示してユーザーに選択要請

他スキルとの境界

スキル 目的 deep-explainとの違い
oss-analyzer OSS深層Due Diligence + 文書生成 deep-explainは迅速な理解用、ファイル未生成(--save除く)
skill-health-check スキルガバナンス検査 deep-explainはスキル内容説明
feature-doctor CONTEXT.json 診断/復旧 deep-explainは機能説明

原則: deep-explainは「理解」を助けるツール。「変更/検証/生成」は他スキルの責任。


使用例

bash
# スキル分析 - "feature-pilotが何だったっけ?"
/deep-explain feature-pilot

# 機能分析 - "035番機能は何?"
/deep-explain 035

# OSS分析 - "OSSでhooksがどう動作する?"
/deep-explain <OSS名>

# ライブラリ分析 - "@tanstack/react-query staleTimeは何?"
/deep-explain @tanstack/react-query staleTime

# 一般技術 - "ATAMは何?"
/deep-explain ATAM

# 保存なしで対話でのみ出力
/deep-explain feature-pilot --no-save

変更履歴

バージョン 日付 変更
1.3.0 2026-02-07 デフォルト保存に変更: --save → デフォルト動作、--no-saveでオプトアウト。ダイアグラムもデフォルト生成
1.2.0 2026-02-06 diagram-generatorエージェント統合: 複雑なワークフロー/依存関係ダイアグラム自動生成
1.1.0 2026-02-06 セクション6「関連項目マップ」追加: タイプ別関連項目収集・分析、依存グラフ、関連スキル/機能/文書含む
1.0.0 2026-02-06 初期バージョン: 5セクション構造分析、対象自動検出、--saveオプション

Expand your agent's capabilities with these related and highly-rated skills.

Didn't find tool you were looking for?

Be as detailed as possible for better results