# Explain

> 把複雜的東西（系統架構、技術決策、debug／review 結論、剛發生的事）做成 self-contained 互動式 HTML 解釋，serve 成本機 HTTP server 給使用者用瀏覽器看。先診斷主題特徵、再選對應的視覺方法，不要無腦套同一個樣板。Trigger：使用者要「解釋／視覺化」某件複雜的事、一個重要決策／架構值得用圖講清楚、或他說「我看不懂、給我更完整 context」。

- **Type:** Skill
- **Install:** `agentstack add skill-j0214ack-claude-skills-better-human-decisions-explain`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [j0214ack](https://agentstack.voostack.com/s/j0214ack)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [j0214ack](https://github.com/j0214ack)
- **Source:** https://github.com/j0214ack/claude-skills-better-human-decisions/tree/main/skills/explain

## Install

```sh
agentstack add skill-j0214ack-claude-skills-better-human-decisions-explain
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# /explain：互動式視覺解釋

本 skill 產出完整前因後果＋視覺化／互動式的解釋。

核心原則：**先診斷這次主題是什麼形狀、讀者是誰，再對照下面 Tier C 選方法。** 不要把上一次的樣板原封套上去。下面分三層：A 永遠做、B 幾乎永遠做（按複雜度縮放）、C 看主題特徵才選。

**交付方式：起一個本機 HTTP server、把網址給使用者**（HTML 是 single-file，能直接用瀏覽器開也行）。

## Tier A：永遠做（交付品質，跟主題無關）

- **對 ground truth 驗證**：每個 claim 先自己 grep／Read／查證過再畫。錯的漂亮圖比沒圖更糟。
- **截圖反向驗證**：交付前用 headless Chrome（chrome-devtools）開頁、`take_screenshot` 看實際 render，破版／錯字／em-dash 當場抓。不能只看檔案存在。
- **single-file、self-contained**：CSS／JS 全內嵌，零外部 CDN／lib（離線載不到會破版）。
- **serve 成本機 HTTP server、給 URL**。
- **跟著使用者的語言輸出**：英文只留代碼識別字（class／method／檔名）和標準縮寫（MCP／API／SQLite…）。
- **不用破折號（U+2014 em-dash）**：rendered 文字掃到零（改用一般標點斷句）。
- **不編造**：不確定的標出來。

## Tier B：幾乎永遠的方法（但按主題複雜度縮放）

1. **概念先行（DDD 共通語彙）**：先建立共通詞彙再講細節。jargon 重的主題→放一塊分組詞彙表（中文名（English）＋1-2 句定義）擺在任何圖之前；簡單主題→一兩句帶過。這同時是「術語一次講白」的地方。
2. **深度分層**：表面簡單、深度收在底下。注意「分層 ≠ 一定多頁」：
   - 大主題（部件多）→ 分層多頁（top-level 總覽連各 submodule detail、互相 hyperlink、設計系統一致；先做 top-level 當樣板確認，OK 再用同套生其餘）。
   - 小主題 → 單頁內用 drawer／section 分層即可。

## Tier C：看主題特徵才選（先診斷、再對照）

> 視覺類的選擇大多在這層。先重判一次主題特徵，別套上一次的樣板。

| 問這個 | 是 → 用 | 否／反面 → 改用 |
|---|---|---|
| 主題是程式碼、有 repo + commit？ | file:line 永久連結（一個 helper 加前綴 `///blob//#L`）、commit 快照戳記、對源碼驗證 | 商業決策／事故時間線／市場分析：沒 repo 可連，這些全跳過 |
| 主題本質是「實體」（有身分的物件／模組／服務＋關係），還是「流程／時序」？ | 實體形 → 非正規 UML class diagram 當**主**視角，sequence 當次視角 | 流程／時序形 → flow／sequence／timeline 當主視角（別預設，先判） |
| 體量大、部件多，還是小、少？ | 大 → 寬白板（full-bleed）、box 拉開、收合 tile | 小 → 單頁攤開、box 直接全顯示、免白板 |
| 每個部件細節深，還是一句話講完？ | 深 → 漸進揭示：tile 只放名稱＋短標籤，點開右側 drawer 看完整內容 | 淺 → 細節直接標在圖上、不用 drawer |
| 關係圖很密，還是疏？ | 密 → 關係線預設淡灰、hover／選中才高亮、其餘變淡 | 疏 → 全部畫實線就好 |
| 讀者技術、要自己 verify，還是非技術？ | 技術 → file:line 連結、技術深度、可跳源碼 | 非技術 → 砍 file:line、用類比、簡化詞彙 |
| 互動元素點得下去嗎？ | 是 → 在圖標題附近明說「點卡片看詳情」，別讓人猜 | 純靜態 → 不需要 |

## 步驟

1. **整理＋診斷**：把素材寫成前因後果（背景 → 為什麼 → 證據（引實際檔案／行）→ 選項／結論），**先對 ground truth 驗證**；同時跑一遍 Tier C 的診斷，決定這次用哪些方法。
2. **派 subagent 生 HTML**（Agent tool、general-purpose、opus）：把 Tier A ＋ B ＋（診斷後選定的）C 寫進 brief，要它對照 source 驗證每個 claim 再畫，寫到 `/tmp/explainers/.html`（先建目錄）。多頁時先 top-level、再用它當樣板生 detail（reuse 同一份 CSS／JS、只換資料）。
3. **截圖反向驗證**（Tier A）。
4. **Serve（背景）**：
   ```bash
   cd /tmp/explainers && python3 -m http.server 8088
   ```
   `run_in_background: true`。port 8088 被佔就換。多頁共用同一 server（serve 整個目錄）；已在跑就重用、別重起。
5. **給 URL**：確認頁面可達後，把網址給使用者 `http://localhost:8088/.html`（多頁時入口給 top-level）。若使用者從別台機器看，換成那台 server 可達的位址。
6. server 背景跑，看完可關（TaskStop 或 kill）。

## 別做
- **別無腦套樣板**：先跑 Tier C 診斷，主題不同方法就不同。
- **沒 GUI 的環境別用 `open`**（改 serve ＋ 給 URL）。
- 別生依賴外部 CDN／lib 的 HTML。
- 別編造資料；不確定的標出來。
- 別用破折號。

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [j0214ack](https://github.com/j0214ack)
- **Source:** [j0214ack/claude-skills-better-human-decisions](https://github.com/j0214ack/claude-skills-better-human-decisions)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-j0214ack-claude-skills-better-human-decisions-explain
- Seller: https://agentstack.voostack.com/s/j0214ack
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.