# Explain

> 作業ディレクトリのプロジェクトを read-only で調べ、目的・技術スタック・ディレクトリ構成・動かし方(実行 / ビルド / テスト)・重要ファイル・注意点を、確認した事実と推測を分けて簡潔に説明する。「このプロジェクトを説明して」「このリポジトリ何?」「構成を教えて」「どうやって動かす?」「まず全体像を把握して」「オンボードして」時に使用。ファイルは変更しない。AGENTS.md や rules の生成は agents-onboarding、CLAUDE.md の生成は /init の仕事。

- Skill: `ktaroabobon/explain` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ktaroabobon/explain`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ktaroabobon/explain/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: ktaroabobon (https://skillmd.com/u/ktaroabobon)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/ktaroabobon/explain

---


# explain

プロジェクトを調べて説明する。**読むだけ。** 説明を README やオンボーディング文書として書き出す依頼があっても、このスキルの中では書かない(保存先を提案して、別ターンで明示的な指示を受けてから書く)。

`disallowed-tools` で Write / Edit を外している。「説明のついでに README を直す」が起きると、説明の正確さよりも書いた内容の正当化に引っ張られる。

## 原則

**読んだものだけを事実として書き、読んでいないものは推測と明示する。**

全部は読めない。だから「どこを読んで何が分かったか」と「読んでいないが構成からこう見える」を分けて書く。読み手はそれで、説明をどこまで信じて次に何を見るべきかを判断できる。

## 引数

- `path`: 対象ディレクトリ。省略時はカレント
- `--for user | agent`: 読み手。省略時は `user`
  - `user`: 人向け。プロジェクトの説明として読める文章
  - `agent`: 自分(エージェント)向け。以後の作業に要る情報(コマンド、規約、触ってはいけない場所、次に読む場所)に寄せる

## Step 1: プロジェクトの指示を先に読む

`AGENTS.md` / `CLAUDE.md` / `.agents/` / `.claude/` / `.codex/` / `README.md` / `docs/` の入口を読む。プロジェクトの指示は一般的な推測より優先する。ここに書かれたコマンドや規約は、後の節でそのまま使う。

## Step 2: スタックを特定する

マニフェスト・設定ファイルから判断する: `package.json` / `pnpm-lock.yaml` / `pyproject.toml` / `requirements.txt` / `go.mod` / `Cargo.toml` / `Gemfile` / `pom.xml` / `build.gradle` / `CMakeLists.txt` / `platformio.ini` / `compose.yaml` / `Dockerfile` / `.github/workflows/` / `Makefile` / `Taskfile.yml` / `justfile`。

実行・ビルド・テストのコマンドは**ドキュメントか設定ファイルに書かれているもの**を拾う。書かれていない推測コマンドは「(未確認)」と付ける。**コマンドを実行して確かめない** — 説明のためにビルドやテストを走らせると、副作用や時間がかかる。

## Step 3: 構造を地図にする

```bash
git ls-files | head -200      # git 管理下なら。深さ 2〜3 までで全体像を掴む
```

`node_modules/` / `.venv/` / `vendor/` / `dist/` / `build/` / `target/` / キャッシュ / 生成物は読まない。巨大なツリーを丸ごと出力しない。

## Step 4: 代表的なファイルを読む

構成を理解するのに必要な分だけ読む: エントリポイント、主要モジュール、ルーティング / コマンド定義、設定、テストの置き場所と書き方。プロジェクト種別で変える(Web アプリならルートとモデル、CLI ならコマンド定義、組み込みならターゲットと HAL、ライブラリなら公開 API)。

## Step 5: 説明を書く

次の構成で、短い節を並べる。該当が無い節は「該当なし」と 1 行で残す(何を見なかったかが伝わる)。

1. **概要** — 何をするものか、誰のためか(1〜3 文)
2. **スタック** — 言語 / フレームワーク / パッケージ管理 / 主要な依存
3. **ディレクトリ** — 主要なディレクトリと役割(表)
4. **動かし方** — 実行 / ビルド / テスト / lint のコマンド。出典(ファイル名)を添える
5. **重要なファイル** — 最初に読むべきもの 5 個前後
6. **構成の要点** — データの流れ、境界、規約、目立つ設計判断
7. **注意点と不明点** — リスク、壊しやすい場所、読んでいない領域、矛盾して見える箇所
8. **次に見るべき場所** — この説明の次に読む・試すと理解が進むもの

`--for agent` のときは 4・6・7・8 を厚く、1・2 を薄くする。

## やらないこと

- ファイルを作らない・変えない。書き出しを求められたら保存先を提案して待つ
- ビルド・テスト・インストールを実行しない
- 読んでいないファイルの中身を断定しない

## 完了時に返すもの

Step 5 の構成の説明。末尾に 1 行で、読んだファイルの数と主要なもの、読んでいない領域を書く。