小黑看代码 — 一个面无表情的小黑，帮你把任意代码库看明白。
Turn any codebase into a hand-drawn, bilingual illustrated walkthrough.
这是一个 Agent Skill：装进你的 AI agent（Cursor / Codex / Antigravity / Claude Code / Gemini CLI），
指向一个仓库说一句「用小黑 decode 这个仓库」，它就会读代码、写双语讲解、画一套「小黑」插画，
拼成一个可滚动的 index.html——每屏一张图 + 一段讲机制的话，带中/英切换、进度条、圆点导航。
它不是一个独立程序，也不需要后端。干活的「大脑」是你已经在用的 agent，所以多数情况下不用额外的 API key。
产出是一个自包含的 HTML 文件——本质是一份可滚动的网页幻灯片：一屏一页，每屏左边一张小黑手绘插画、右边一段讲机制的话，配文件名标签。顶部有进度条、圆点导航和中 / EN 一键切换，无依赖、可离线、双击就能看。
往下滚就是下一屏。完整双语成品见 assets/examples/（直接用浏览器打开里面的 index.html）。
干活的「大脑」是你已经在用的 agent。「读代码 + 写文案」在哪儿都现成，唯一可能要额外准备的是生图能力：
| 你的环境 | 要准备什么 |
|---|---|
| Cursor / Codex（ChatGPT 订阅）/ Antigravity | 不用配置，装上 skill 直接用 ✅ |
| Gemini CLI | 额外配一个 Gemini API key（仅出图用；免费的「Login with Google」调不了图像模型） |
| Claude Code | 额外挂一个带 key 的图像 MCP（仅出图用，如 Gemini / OpenAI 图像服务） |
| 网页 / APP 版 Gemini、ChatGPT、Claude | 用不了——读不了你的本地仓库，也不跑 skill |
clone 本仓库，把整个目录拷进你 agent 的 skills 目录（或建软链接）：
git clone https://github.com/anniekoala/xiaohei-code-decoder.git| Agent | 安装位置 |
|---|---|
| Cursor | ~/.cursor/skills/xiaohei-code-decoder/ |
| Codex | ~/.codex/skills/xiaohei-code-decoder/ |
| Antigravity / 通用约定 | ~/.agents/skills/xiaohei-code-decoder/ |
| Claude Code | ~/.claude/skills/xiaohei-code-decoder/ |
| Gemini CLI | 放入其 skills 目录 |
例如 Cursor：
mkdir -p ~/.cursor/skills
cp -R xiaohei-code-decoder ~/.cursor/skills/Claude Code / Gemini CLI 想出图，还需先配好一个带 key 的图像能力（见上表）。
在 agent 里说（中英都行）：
用小黑 decode 一下 https://github.com/owner/repo
Decode this repo with Xiaohei Code Decoder
给当前这个 codebase 出一套小黑图解
agent 会产出：
<repo>-xiaohei/
├── index.html # 双击打开
└── images/ # 生成的小黑插画
xiaohei-code-decoder/
├── SKILL.md # 触发描述 + 工作流
├── README.md
├── references/
│ ├── xiaohei-style.md # 小黑图像风格 DNA
│ ├── writing-rules.md # 双语文案规则
│ └── assembly.md # 套模板 / 命名 / 输出
└── assets/
├── template.html # 幻灯片模板
├── xiaohei.svg
├── logo.png
└── examples/ # 两套现成成品
- 小黑视觉风格参考自 ian-xiaohei-illustrations 的「小黑」IP 与手绘配图方法论。
- 「把代码库变成单页可视化讲解」的产品思路也参考了 zarazhangrui/codebase-to-course（原创隐喻、不复述、面向非工程师等理念）。
This is an Agent Skill. Drop it into your AI agent (Cursor / Codex / Antigravity / Claude Code / Gemini CLI),
point it at a repo and say "decode this repo with 小黑", and it reads the code, writes a bilingual explanation,
draws a set of "Xiaohei" illustrations, and assembles a scrollable index.html — one image + one mechanism-focused
blurb per screen, with a 中/EN toggle, progress bar, and dot navigation.
It is not a standalone program and needs no backend. The "brain" doing the work is the agent you already pay for, so in most cases no extra API key is required.
The output is one self-contained HTML file — essentially a scrollable web slideshow: one screen per page, each with a hand-drawn Xiaohei illustration on the left and a short, mechanism-focused blurb on the right, tagged with the real file names. A progress bar, dot navigation, and a one-tap 中 / EN toggle sit on top. No dependencies, works offline, just double-click to view.
Scroll down for the next screen. Full bilingual decks live in assets/examples/ — just open their index.html in a browser.
The "brain" doing the work is the agent you already use. "Reading code + writing text" is available everywhere; the only thing some setups need extra is image generation:
| Your environment | What to prepare |
|---|---|
| Cursor / Codex (ChatGPT sub) / Antigravity | Nothing — install the skill and go ✅ |
| Gemini CLI | A Gemini API key (for images only; the free "Login with Google" can't call image models) |
| Claude Code | A keyed image MCP (for images only, e.g. a Gemini / OpenAI image service) |
| Gemini / ChatGPT / Claude web or app | Can't use it — they can't read your local repo or run a skill |
Clone this repo and copy the whole directory into your agent's skills folder (or symlink it):
git clone https://github.com/anniekoala/xiaohei-code-decoder.git| Agent | Install location |
|---|---|
| Cursor | ~/.cursor/skills/xiaohei-code-decoder/ |
| Codex | ~/.codex/skills/xiaohei-code-decoder/ |
| Antigravity / common convention | ~/.agents/skills/xiaohei-code-decoder/ |
| Claude Code | ~/.claude/skills/xiaohei-code-decoder/ |
| Gemini CLI | its skills folder |
For example, Cursor:
mkdir -p ~/.cursor/skills
cp -R xiaohei-code-decoder ~/.cursor/skills/For image generation on Claude Code / Gemini CLI, set up a keyed image capability first (see the table above).
Say to your agent (in English or Chinese):
Decode this repo with Xiaohei Code Decoder: https://github.com/owner/repo
用小黑 decode 一下 <repo>
Make an illustrated walkthrough of this codebase
The agent produces:
<repo>-xiaohei/
├── index.html # open it
└── images/ # the generated Xiaohei illustrations
xiaohei-code-decoder/
├── SKILL.md # trigger description + workflow
├── README.md
├── references/
│ ├── xiaohei-style.md # Xiaohei image style DNA
│ ├── writing-rules.md # bilingual copy rules
│ └── assembly.md # template / naming / output
└── assets/
├── template.html # the deck template
├── xiaohei.svg
├── logo.png
└── examples/ # two finished decks
- The Xiaohei visual style draws on the "Xiaohei" IP and hand-drawn illustration methodology from ian-xiaohei-illustrations.
- The "turn a codebase into a single-page visual explainer" idea also draws on zarazhangrui/codebase-to-course (fresh metaphors, no recycling, built for non-engineers).