feat(reference): UnityCsReference のローカルキャッシュ参照機構（Phase 1）

.agents/skills/unity-csharp-reference

@@ -0,0 +1 @@
+../../.claude-plugin/plugins/unity-cli/skills/unity-csharp-reference

.claude-plugin/plugins/unity-cli/skills/unity-csharp-edit/SKILL.md

@@ -15,6 +15,7 @@ metadata:
     - setting
   siblings:
     - unity-csharp-navigate
+    - unity-csharp-reference
     - unity-editor-tools
     - unity-cli-usage
     - unity-gameobject-edit

.claude-plugin/plugins/unity-cli/skills/unity-csharp-navigate/SKILL.md

@@ -14,6 +14,7 @@ metadata:
     - symbol
   siblings:
     - unity-csharp-edit
+    - unity-csharp-reference
     - unity-scene-inspect
 ---
 

.claude-plugin/plugins/unity-cli/skills/unity-csharp-reference/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: unity-csharp-reference
+description: Browse Unity Technologies' official UnityCsReference C# source as a read-only local cache. Use when the user asks about the exact signature, behavior, or internal implementation of a Unity API, when comparing API differences between Unity versions, or when validating LLM-suggested Unity code against the canonical source. Do not use for editing project code (use `unity-csharp-edit`). Do not use for project-local script reading (use `unity-csharp-navigate`).
+allowed-tools: Bash(unity-cli:*), Read, Grep, Glob
+metadata:
+  author: akiojin
+  version: 0.1.0
+  category: code
+  triggers:
+    - reference
+    - unity-api
+    - signature
+    - unity-source
+    - version-diff
+  siblings:
+    - unity-csharp-navigate
+    - unity-csharp-edit
+    - unity-scene-inspect
+---
+
+# Unity C# Reference
+
+Browse Unity Technologies' official UnityCsReference C# source as a read-only local cache. This skill is the sibling of `unity-csharp-navigate` (project sources) and `unity-csharp-edit` (writes). Hand off as soon as the request implies project-level reading or a write.
+
+## Use When
+
+- The user asks about the exact signature, attributes, or behavior of a Unity API such as `UnityEngine.Animator.Play` or `UnityEditor.AssetDatabase.Refresh`.
+- The user wants to read the internal implementation of a Unity type to predict performance characteristics or side effects.
+- The user compares API differences between Unity versions (LTS vs Tech release branches).
+- The user wants to validate an LLM-suggested Unity script against the canonical Unity source.
+
+## Do Not Use When
+
+- The user wants to read project-local scripts; use `unity-csharp-navigate`.
+- The user wants to write or refactor C# code; use `unity-csharp-edit`.
+- The user wants Unity scene state, packages, or assets; use the matching scene, asset, or editor skill family.
+
+## Preferred Flow
+
+1. Run the runtime checklist in [runtime-checklist.md](references/runtime-checklist.md) before the first fetch in a new environment.
+2. Populate the cache for the project's Unity version with `unity-cli reference fetch --accept-license` (one-time per version).
+3. Use `unity-cli reference grep` for line-level pattern lookups with optional context, or `unity-cli reference search` for filtered file hits.
+4. Open the candidate file with `unity-cli reference view --start-line N --max-lines M` to read the relevant span.
+5. Confirm the signature or behavior, then hand off to `unity-csharp-navigate` for project sources or `unity-csharp-edit` for writes.
+
+```bash
+unity-cli reference fetch --accept-license
+unity-cli reference status --output json
+unity-cli reference grep "class Animator " --context 3
+unity-cli reference view Runtime/Export/Animation/Animator.bindings.cs --start-line 100 --max-lines 60
+unity-cli reference clean --keep 1 --dry-run
+```
+
+## Examples
+
+- "Show me how Unity implements `Animator.Play` so I can predict whether it allocates."
+- "Compare `UnityWebRequest.Get` between Unity 2022.3 and Unity 6 staging."
+- "Confirm the exact signature of `EditorApplication.delayCall` before I wire it into the build pipeline."
+
+## References
+
+- [runtime-checklist.md](references/runtime-checklist.md): runtime prerequisites and license acceptance before the first fetch.
+- [fetch-and-cache.md](references/fetch-and-cache.md): `reference fetch`, `status`, and `clean` command details and branch mapping per Unity version.
+- [symbol-lookup-playbook.md](references/symbol-lookup-playbook.md): the canonical reference → navigate → edit workflow when validating LLM-suggested Unity code.

.claude-plugin/plugins/unity-cli/skills/unity-csharp-reference/references/fetch-and-cache.md

@@ -0,0 +1,75 @@
+# Fetch and Cache
+
+Operational guide for the `unity-cli reference` cache commands.
+
+## Cache Layout
+
+```
+~/.unity/cache/UnityCsReference/
+  <unity-version>/
+    .git/
+    Runtime/
+    Editor/
+    Modules/
+    .unity-cli-meta.json   # { version, branch, commit_sha, fetched_at, source_url }
+```
+
+Override the base path with `UNITY_CLI_CACHE_ROOT` (defaults to `~/.unity/cache`). Each Unity version lives in its own directory and is independent of `~/.unity/tools/` (which stores managed binaries).
+
+## Branch Mapping
+
+The CLI maps the active Unity version (read from `ProjectSettings/ProjectVersion.txt`) to a UnityCsReference branch using a static table:
+
+| Unity major.minor | Branch       |
+|-------------------|--------------|
+| `2020.3`          | `2020.3/staging` |
+| `2021.3`          | `2021.3/staging` |
+| `2022.3`          | `2022.3/staging` |
+| `2023.1`          | `2023.1/staging` |
+| `2023.2`          | `2023.2/staging` |
+| `6000.0`          | `6000.0/staging` |
+
+Unmapped versions require `--branch <name>` so the CLI can fetch without guessing.
+
+## Commands
+
+### Fetch
+
+```bash
+# Auto-detect Unity version from the current project
+unity-cli reference fetch --accept-license
+
+# Explicit version + branch
+unity-cli reference fetch --version 2023.2.20f1 --branch 2023.2/staging --accept-license
+
+# Refetch an existing snapshot
+unity-cli reference fetch --version 2023.2.20f1 --force --accept-license
+```
+
+Fetch uses `git clone --depth 1 --single-branch --branch <branch>` so the on-disk footprint stays close to the source tree size. The `GITHUB_TOKEN` / `GH_TOKEN` environment variable is injected as `http.extraHeader=Authorization: token ...` to relieve rate limits when set.
+
+### Status
+
+```bash
+unity-cli reference status --output json
+```
+
+Returns `{ ok: true, versions: [ { version, branch, fetchedAt, sizeBytes, path } ... ] }`. Use this to confirm a fetch completed and to monitor disk usage.
+
+### Clean
+
+```bash
+# Show what would be removed (LRU by mtime)
+unity-cli reference clean --keep 1 --dry-run
+
+# Actually remove old snapshots
+unity-cli reference clean --keep 1
+```
+
+`clean` retains the newest `--keep` snapshots (mtime descending) and removes the rest. The CLI prints the removed paths so they can be re-cached on demand.
+
+## Troubleshooting
+
+- `git binary not found`: install `git` or point `PATH` at a working installation.
+- `Unity Companion License`: pass `--accept-license` or export `UNITY_CLI_ACCEPT_LICENSE=1`.
+- `Unity version ... not in the static branch map`: pass `--branch <name>` explicitly; consider opening an issue to extend the static table.

.claude-plugin/plugins/unity-cli/skills/unity-csharp-reference/references/runtime-checklist.md

@@ -0,0 +1,34 @@
+# Runtime Checklist
+
+Run these checks before the first `reference fetch` in a new environment or worktree.
+
+## Prerequisites
+
+- `git` is on `PATH`. Verify with `git --version`.
+- The target project has `ProjectSettings/ProjectVersion.txt` so Unity version detection can run automatically. Without a project, pass `--version <X.Y.Zfn>` and `--branch <branch>` explicitly.
+- Network connectivity to `github.com` is available. For rate-limited environments, export `GITHUB_TOKEN` or `GH_TOKEN` before fetching.
+- Disk budget: budget roughly 400-600 MB per cached Unity version. Use `unity-cli reference status --output json` to inspect current usage.
+
+## License Acceptance
+
+UnityCsReference is distributed under the Unity Companion License. The CLI refuses to fetch without explicit consent:
+
+- Pass `--accept-license` to `reference fetch`, or
+- Export `UNITY_CLI_ACCEPT_LICENSE=1` for non-interactive sessions.
+
+Local caches are for personal reference only. Do not redistribute the cached source.
+
+## First-Run Verification
+
+```bash
+unity-cli reference fetch --accept-license
+unity-cli reference status --output json
+```
+
+Expected: `status` reports a single cached entry with `version`, `branch`, `fetchedAt`, `sizeBytes`, and `path`. Re-running `fetch` without `--force` skips with a notice.
+
+## Recovery
+
+- Fetch failed half-way: rerun with `--force` to wipe the version directory and clone again.
+- Cache directory unreadable: remove `~/.unity/cache/UnityCsReference/<version>` and re-fetch.
+- Disk pressure: `unity-cli reference clean --keep 1` keeps the newest snapshot and removes the rest.

.claude-plugin/plugins/unity-cli/skills/unity-csharp-reference/references/symbol-lookup-playbook.md

@@ -0,0 +1,56 @@
+# Symbol Lookup Playbook
+
+The canonical reference → navigate → edit workflow when validating LLM-suggested Unity code.
+
+## When to Reach Here
+
+- The user (or an LLM) proposed a Unity API call and you need to confirm the exact signature or behavior.
+- An LLM suggested code that compiles but you suspect it relies on a different overload, attribute, or version-specific behavior.
+- The user is comparing two Unity versions and needs API-level evidence.
+
+## Workflow
+
+### 1. Locate the symbol in the official source
+
+```bash
+unity-cli reference grep "class Animator " --context 0
+unity-cli reference grep "void Play\(" --file-glob "Animator*.cs" --context 2
+unity-cli reference search "AssetDatabase.Refresh" --max-results 10
+```
+
+`grep` emits `{ path, line, text, context_before, context_after }` so the surrounding context survives a follow-up `view`.
+
+### 2. Read the relevant span
+
+```bash
+unity-cli reference view Runtime/Export/Animation/Animator.bindings.cs --start-line 100 --max-lines 60
+```
+
+Use the line number from `grep` to anchor a tight `--start-line` / `--max-lines` window. Avoid dumping entire files: the LLM context budget is finite and the surrounding code is rarely needed.
+
+### 3. Cross-check against the project
+
+Switch to [unity-csharp-navigate](../../unity-csharp-navigate/SKILL.md) for project sources:
+
+```bash
+unity-cli raw find_refs --json '{"name":"Animator.Play","scope":"assets"}'
+```
+
+This catches callers that depend on the exact overload you just confirmed.
+
+### 4. Apply the change
+
+Hand the validated signature to [unity-csharp-edit](../../unity-csharp-edit/SKILL.md) for the write step:
+
+```bash
+unity-cli raw apply_csharp_edits --json '{ ... }'
+```
+
+Keep the original `reference view` excerpt in the conversation context so the editor can quote the canonical implementation when justifying the change.
+
+## Anti-Patterns
+
+- Skipping the reference lookup and trusting the LLM-suggested API name verbatim.
+- Reading the entire `Runtime/Export` tree instead of using `grep --file-glob` to narrow the scope.
+- Caching multiple versions you do not actively compare; rely on `unity-cli reference clean --keep 1` to control disk usage.
+- Mixing project sources and reference sources in the same write tool call; the reference cache is read-only on purpose.

.claude-plugin/plugins/unity-cli/skills/unity-scene-inspect/SKILL.md

@@ -16,6 +16,7 @@ metadata:
     - unity-scene-create
     - unity-gameobject-edit
     - unity-csharp-navigate
+    - unity-csharp-reference
 ---
 
 # Scene Inspect

.claude/skills/unity-csharp-reference

@@ -0,0 +1 @@
+../../.claude-plugin/plugins/unity-cli/skills/unity-csharp-reference

ATTRIBUTION.md

@@ -143,3 +143,34 @@ MIT License
 4. **ドキュメント**: アプリケーションのユーザーマニュアルやオンラインドキュメントに表記します。
 
 `unity-cli-bridge` は Editor 専用パッケージ（Unity Editor 内でのみ動作し、ビルドには含まれない）であるため、出荷ビルドでの帰属表示は厳密には不要な場合があります。ただし、ソースコードを再配布または改変する場合は帰属表示が必要です。
+
+---
+
+## Third-Party: UnityCsReference (Unity Companion License)
+
+`unity-cli reference fetch` clones the official Unity C# reference source from
+[`Unity-Technologies/UnityCsReference`](https://github.com/Unity-Technologies/UnityCsReference)
+into a local read-only cache (`~/.unity/cache/UnityCsReference/<version>/`).
+The cached source is © Unity Technologies and is distributed under the
+[Unity Companion License](https://unity.com/legal/licenses/unity-companion-license).
+
+- Purpose: local read-only reference for LLM-assisted Unity C# implementation.
+- Acceptance: required via the `--accept-license` flag or the
+  `UNITY_CLI_ACCEPT_LICENSE=1` environment variable before any fetch runs.
+- Restriction: do not redistribute the cached source. The cache is for
+  personal local use only.
+
+### Unity Companion License（日本語要約）
+
+`unity-cli reference fetch` は Unity 公式の C# リファレンス
+（`Unity-Technologies/UnityCsReference` リポジトリ）を
+`~/.unity/cache/UnityCsReference/<version>/` 配下にローカル読み取り専用で
+キャッシュします。キャッシュされたソースは Unity Technologies の著作物で、
+[Unity Companion License](https://unity.com/legal/licenses/unity-companion-license)
+に従って利用してください。
+
+- 用途: LLM 支援による Unity C# 実装の参照用ローカルキャッシュ。
+- 同意: `--accept-license` フラグ、または `UNITY_CLI_ACCEPT_LICENSE=1`
+  環境変数で同意を明示してから fetch を実行してください。
+- 制限: キャッシュ済みソースの再配布は禁止です。利用は個人のローカル参照に
+  限定してください。

README.ja.md

@@ -9,6 +9,7 @@
 
 - Claude Code から、用途別スキルと typed コマンドで Unity を操作できます。
 - シーン、アセット、コード、テスト、UI、Editor を含む `101` 個の Unity Tool API を利用できます。
+- Unity 公式 C# リファレンス（[UnityCsReference](https://github.com/Unity-Technologies/UnityCsReference)）を `unity-cli reference fetch` でローカルキャッシュし、`unity-csharp-reference` スキルから読み取り専用で参照できます。
 - 単一バイナリで高速起動、低オーバーヘッドです。
 
 ## 仕組み

docs/tools.md

@@ -249,6 +249,38 @@ unity-cli tool schema input_keyboard --output json
 unity-cli tool schema package_manager --output json
 ```
 
+## Reference Cache (6 tools)
+
+The `unity-cli reference *` family provides a local read-only mirror of the
+official [UnityCsReference](https://github.com/Unity-Technologies/UnityCsReference)
+source. Use it when you need the canonical signature or internal
+implementation of a Unity API. The cache lives under
+`~/.unity/cache/UnityCsReference/<version>/` (override with
+`UNITY_CLI_CACHE_ROOT`). License acceptance is mandatory before the first
+fetch via `--accept-license` or `UNITY_CLI_ACCEPT_LICENSE=1`.
+
+| Tool | Description |
+| --- | --- |
+| `reference_fetch` | Shallow-clone UnityCsReference for the active Unity version into the local cache. |
+| `reference_status` | List cached UnityCsReference versions, branches, fetched-at, and disk usage. |
+| `reference_search` | Search the cached reference source for a pattern with optional path and result limits. |
+| `reference_grep` | Grep the cached reference source line-by-line with optional file glob and context lines. |
+| `reference_view` | Display a slice of a file in the cached reference source by line range. |
+| `reference_clean` | Remove old UnityCsReference snapshots, keeping the newest entries. |
+
+Typed CLI equivalents:
+
+```bash
+unity-cli reference fetch --accept-license
+unity-cli reference status --output json
+unity-cli reference grep "class Animator " --context 3
+unity-cli reference view Runtime/Export/Animation/Animator.bindings.cs --start-line 100 --max-lines 60
+unity-cli reference clean --keep 1 --dry-run
+```
+
+See `.claude-plugin/plugins/unity-cli/skills/unity-csharp-reference/` for the
+companion skill and the `reference -> navigate -> edit` workflow.
+
 ## Regenerate This Catalog
 
 ```bash