diff --git a/bin/superpowers-zh.js b/bin/superpowers-zh.js
index 31480ec..4ef5667 100755
--- a/bin/superpowers-zh.js
+++ b/bin/superpowers-zh.js
@@ -68,7 +68,14 @@ const TARGETS = [
   // 注意 Kiro 的 frontmatter 键是 inclusion / fileMatchPattern，不是 Cursor 系的
   // alwaysApply / globs —— 我们旧文档写错过，见 docs/README.kiro.md。
   { name: 'Kiro',          dir: '.kiro/skills',              detect: '.kiro' },
-  { name: 'DeerFlow',      dir: 'skills/custom',             detect: 'deer_flow' },
+  // DeerFlow 安装路径 skills/custom/ 经官方文档核实（bytedance-deer-flow.mintlify.app
+  // /concepts/skills）：自动扫描 ["skills/public", "skills/custom"] 两个固定目录，
+  // custom 默认被 gitignore，无需任何配置。容器内挂到 /mnt/skills/。
+  // 但检测标记原来写的是 deer_flow —— DeerFlow 2.0 顶层是 backend/frontend/skills/…，
+  // **没有 deer_flow 这个目录**（实测 GitHub API 列目录确认），所以真实的 DeerFlow
+  // 检出从来没被自动检测到过。改认 skills/public：它是 skills 机制本身、随仓库版本
+  // 控制，任何 DeerFlow 检出都有；deer_flow 保留作 1.x 兼容。
+  { name: 'DeerFlow',      dir: 'skills/custom',             detect: ['skills/public', 'deer_flow'] },
   { name: 'Trae',          dir: '.trae/skills',              detect: '.trae' },
   // Antigravity 无 global：其全局 skills 加载路径未在 docs 证实（全局规则走 ~/.gemini/GEMINI.md），
   // 不确认能生效就不写，避免「装了不生效」。用户用项目级安装。
diff --git a/docs/README.deerflow.md b/docs/README.deerflow.md
index fd1adea..2f2297c 100644
--- a/docs/README.deerflow.md
+++ b/docs/README.deerflow.md
@@ -1,65 +1,90 @@
-# Superpowers 中文版 — DeerFlow 2.0 安装指南
+# Superpowers 中文版 — DeerFlow 安装指南
 
-在 [DeerFlow 2.0](https://github.com/bytedance/deer-flow)（字节跳动开源 SuperAgent）中使用 superpowers-zh 的完整指南。
+在 [DeerFlow](https://github.com/bytedance/deer-flow)（字节跳动开源 SuperAgent）中使用 superpowers-zh 的完整指南。
 
 ## 快速安装
 
+在你的 **DeerFlow 仓库根目录**下运行：
+
 ```bash
-cd /your/deerflow-project
-npx superpowers-zh
+cd /your/deer-flow
+npx superpowers-zh --tool deerflow
 ```
 
-安装脚本会自动检测 `deer_flow/` 目录并将 skills 复制到 `skills/custom/`。
+skills 会装到 `skills/custom/`。
+
+> 📌 v1.7.10 及更早版本的自动检测标记写的是 `deer_flow/` —— **DeerFlow 2.0 的顶层目录里根本没有它**（实际是 `backend/` `frontend/` `skills/` `docker/` 等）。也就是说真实的 DeerFlow 检出从来没被自动检测到过，必须手动 `--tool deerflow`。v1.7.11 起改认 `skills/public/`（skills 机制本身、随仓库版本控制），`deer_flow/` 保留作 1.x 兼容。
+
+## 工作原理
+
+[DeerFlow 官方文档](https://bytedance-deer-flow.mintlify.app/concepts/skills)明确了两个**固定**目录：
+
+| 目录 | 用途 | 是否进 git |
+|---|---|---|
+| `skills/public/` | DeerFlow 自带的 skill，社区维护 | 是 |
+| `skills/custom/` | 用户自建或安装的 skill | 否，默认被 gitignore |
+
+加载方式是**自动扫描这两个目录**，找每个子目录里的 `SKILL.md`：
+
+```python
+for base_dir in ["skills/public", "skills/custom"]:
+    for skill_dir in os.listdir(base_dir):
+        ...
+```
+
+**无需任何配置**，也没有可改路径的配置项 —— 这两个目录名是写死的。所以我们装到 `skills/custom/`，装完即被发现。
+
+### 容器挂载
+
+DeerFlow 的 skill 在沙箱容器里执行，两个目录会挂到容器内的 `/mnt/skills/`：
+
+```
+/mnt/skills/
+├── public/
+└── custom/
+```
+
+所以 skill 内部若要引用自己的附属脚本，路径要写容器内的形式，例如 `python /mnt/skills/custom/my-skill/scripts/process.py`。
+
+> superpowers-zh 的 20 个 skill 以 Markdown 指令为主，`brainstorming` 带的 `scripts/` 是给宿主机 harness 用的可视化伴侣服务，在 DeerFlow 的容器沙箱里不适用 —— 这部分能力在 DeerFlow 上不可用，其余 skill 的方法论正常生效。
 
 ## 手动安装
 
 ```bash
-git clone https://github.com/jnMetaCode/superpowers-zh.git
-mkdir -p /your/deerflow-project/skills/custom
-cp -r superpowers-zh/skills/* /your/deerflow-project/skills/custom/
+cd /your/deer-flow
+mkdir -p skills/custom
+cp -r /path/to/superpowers-zh/skills/* skills/custom/
 ```
 
-## 工作原理
-
-DeerFlow 2.0 使用 **Custom Skills** 机制扩展 Agent 能力：
-
-- **目录**：`skills/custom/`
-- **格式**：每个 skill 是一个目录，包含 `SKILL.md` 文件（Markdown + YAML frontmatter）
-- **加载方式**：DeerFlow 自动扫描 `skills/custom/` 下的所有目录，通过 `description` 字段匹配 skill
-
-### Skills 格式兼容
-
-superpowers-zh 的 SKILL.md 文件格式与 DeerFlow 自定义 skills 完全兼容。安装后，DeerFlow 会自动发现并加载所有 skills。
-
-### 环境变量
-
-如果你的 DeerFlow 项目不在当前目录，可以手动指定安装路径：
+装到别处的 DeerFlow 检出时，用绝对路径即可：
 
 ```bash
-export DEERFLOW_SKILLS_DIR=/path/to/deerflow/skills/custom
-cp -r superpowers-zh/skills/* $DEERFLOW_SKILLS_DIR/
+cp -r /path/to/superpowers-zh/skills/* /path/to/deer-flow/skills/custom/
 ```
 
+> 📌 v1.7.10 及更早的本文档给了一段 `export DEERFLOW_SKILLS_DIR=...` 的写法，容易被读成「DeerFlow 认这个环境变量」。**官方文档里没有这个环境变量**，目录是写死的。已删除。
+
 ## 使用
 
-安装后，在 DeerFlow 对话中引用 skill 名称即可：
+装好后在 DeerFlow 对话中直接描述任务，或点名 skill：
 
 - 「使用头脑风暴来分析这个需求」
 - 「用测试驱动开发来实现这个功能」
 - 「按系统化调试流程排查这个 bug」
 
-DeerFlow 会根据 skill 的 `description` 自动匹配并加载。
+DeerFlow 按 skill frontmatter 里的 `description` 匹配并加载，所以 `description` 写得越具体，被正确选中的概率越高 —— 这也是官方文档强调的一点。
 
-## 更新
+## 卸载
 
 ```bash
-cd /your/deerflow-project
-npx superpowers-zh
+cd /your/deer-flow
+npx superpowers-zh --uninstall
 ```
 
-重新运行安装命令即可更新到最新版本。
+只删除我们装进 `skills/custom/` 的那些 skill 目录，`skills/public/` 和你自己的 custom skill 不动。
 
 ## 获取帮助
 
 - 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
-- DeerFlow 文档：https://github.com/bytedance/deer-flow
+- DeerFlow 仓库：https://github.com/bytedance/deer-flow
+- DeerFlow Skills 文档：https://bytedance-deer-flow.mintlify.app/concepts/skills
diff --git a/scripts/verify-release.sh b/scripts/verify-release.sh
index 6687e60..7b0b901 100755
--- a/scripts/verify-release.sh
+++ b/scripts/verify-release.sh
@@ -88,7 +88,10 @@ declare -a DETECT=(
   ".claw:Claw Code"          ".qoder:Qoder"          ".codebuddy:CodeBuddy"
   ".codeartsdoer:CodeArts"   ".clinerules:Cline"     ".kilocode:Kilo Code"
   ".kilo:Kilo Code"          ".crush:Crush"
-  "deer_flow:DeerFlow"       ".github/copilot-instructions.md:VS Code"
+  # DeerFlow 2.0 顶层没有 deer_flow 目录（backend/frontend/skills/…），只测它等于
+  # 拿代码测代码。skills/public 是 skills 机制本身、随仓库版本控制，才是真实标记。
+  "skills/public:DeerFlow"   "deer_flow:DeerFlow"
+  ".github/copilot-instructions.md:VS Code"
   "GEMINI.md:Gemini CLI"
 )
 for entry in "${DETECT[@]}"; do