---
name: book-to-skill
description: "将典籍与文书（PDF、EPUB、DOCX、HTML、Markdown、纯文、RTF，及藉Calibre之MOBI/AZW）化作结构化代理技能，抽取框架、心智模型、原则、技法与反模式。凡欲藉GitHub Copilot CLI、Amp或Claude Code研读一文，应用作者之框架于实务，或自文件筑可复用知识库者，皆可用之。"
---
book-to-skill 转换器
化书写之知为代理可行之技——抽其结构，非撮要成篇。
理念
书者，岁积月累之智晶也。其框架、原则、技艺，非一朝可得。此术非撮要成篇，乃化其结构为代理可反复调用之利器。
抽结构，非撮要。 技能非书评，乃一 toolkit 也，内含：
- 已名之框架（心智模型，应用情境清晰）
- 可行之原则（导决策之规）
- 技法（步步之法）
- 反模式（当避者与所以）
- 声调校准（作者思与言之道）
存作者之精微。 框架之名，往往有故。“五问法”不可与“多问何故”互换。须录其确切之式。
层深适度。 简书出简技。繁书具十余框架者，则技能附参考档与按需章节。
---
运作模式
有四途可循，视君所求而定。
1. 完全转换（默认）
触发： 君提供一个或多个文档/目录/glob 路径，且无特别指示。
动作： 运行以下全部步骤（Step 0–9）。
输出： 完整技能，含 SKILL.md、chapters/、glossary、patterns、cheatsheet。
2. 仅分析
触发： 君言“analyze”“just extract”或“我欲先审再生成”。
动作： 运行 Step 0–3，产出结构化抽取报告（框架、原则、技法）。止步，不生成技能文件。
输出： 分析报告，供君审阅。
3. 依前分析生成
触发： 君已有分析笔记，或曾运行“仅分析”。
动作： 跳过 Step 0–3，以君提供之分析为输入，运行 Step 4–9。
输出： 依分析生成之技能文件。
4. 更新 / 折入（既有技能）
触发： 君提供新源路径，并指明欲更新既有技能（或指向既有技能文件夹，或给已存在之 slug，或明确要求更新）。
动作： 运行 Step 0（范围检查）、Step 1（验证输入）、Step 1.5（辨内容类型）、Step 2（抽取新文件）。然后跳至 Step 5（识别既有技能路径），执行
更新 / 折入流程，将新内容并入既有技能文件。
输出： 更新后之既有技能，新/修订章摘要与合并索引/术语表。
---
技能存放处
此转换器可运行于多处技能系统。寻其辅助脚本或写生成之书技能时，优先以下位置：
1. GitHub Copilot CLI 个人技能：~/.copilot/skills/
2. 跨代理个人技能（Copilot + Amp）：~/.agents/skills/
3. Claude Code 个人技能：~/.claude/skills/
4. 项目本地 Copilot 技能：.github/skills/
5. 项目本地 Claude 技能：.claude/skills/
6. 项目本地 Amp / Copilot 技能：.agents/skills/
7. Amp 全局技能：~/.config/agents/skills/
8. Amp 旧版全局技能：~/.config/amp/skills/
为生成之书技能，择君之主机代理实能发现之目的地（见 Step 5）。若有多处有效根目录存在，问君一次，记住本次会话之答，不默默认值。
---
Step 0 — 范围检查
若无参数，止步并应：
> "book-to-skill 需一受支持之文档路径、文件夹或 glob 模式。用法：book-to-skill <文档文件夹或glob路径>... [技能slug]"
全程：
- 识输入路径与可选技能 slug。
- 若末参数非文件、文件夹或匹配文件之 glob，且形似技能 slug（小写连字符、字母数字），则视之为
SKILL_NAME。
- 其余参数皆为
INPUT_PATHS 列表。
- 若任一输入路径为既有技能目录（含
SKILL.md 与 chapters/ 子文件夹），或 SKILL_NAME 匹配 SKILLS_HOME 中既有技能 slug，则标此运行为更新/折入操作（模式 4）。
---
Step 1 — 验证输入
验 INPUT_PATHS 中至少有一受支持文件、目录或 glob 模式。
对目录与 glob，展开之，寻匹配之受支持文件（.pdf、.epub、.docx、.txt、.md、.markdown、.rst、.adoc、.html、.htm、.rtf、.mobi、.azw、.azw3）。
若无受支持文件，止步，给清晰错误讯息。
---
Step 1.5 — 辨内容类型
抽取前，问君：
> "这些源含何种内容？此有助于择最佳抽取法。
>
> 1. 技术型 —— 有代码块、表格、公式、图表（例如编程书、学术论文、架构指南）
> 2. 文字为主 —— 多为散文，少或无表格/代码（例如管理、生产力、叙事非虚构）
> 3. 不确定 —— 我将用快速法，若品质似有限，会警示"
存答为 BOOK_TYPE：
- 选项 1 →
BOOK_TYPE=technical
- 选项 2 →
BOOK_TYPE=text
- 选项 3 →
BOOK_TYPE=text
若 BOOK_TYPE=technical，先行告知君：
> "📐 已选技术模式——用 Docling 做结构感知抽取（表格、代码块、公式以 markdown 存）。每页约 1.5 秒，长源需数分钟。开始……"
若 BOOK_TYPE=text，告知：
> "📄 已选文字模式——为各文件类型用最快适用抽取器。纯文/Markdown/HTML 通常数秒即就；PDF 若有 pdftotext 则用之。"
---
Step 2 — 自源文档抽取文字
运行抽取脚本，传输入路径：
SCRIPT_PATH=""
for candidate in \
"$HOME/.copilot/skills/book-to-skill/scripts/extract.py" \
"$HOME/.agents/skills/book-to-skill/scripts/extract.py" \
"$HOME/.claude/skills/book-to-skill/scripts/extract.py" \
".github/skills/book-to-skill/scripts/extract.py" \
".claude/skills/book-to-skill/scripts/extract.py" \
".agents/skills/book-to-skill/scripts/extract.py" \
"$HOME/.config/agents/skills/book-to-skill/scripts/extract.py" \
"$HOME/.config/amp/skills/book-to-skill/scripts/extract.py"
do
if [ -f "$candidate" ]; then
SCRIPT_PATH="$candidate"
break
fi
done
if [ -z "$SCRIPT_PATH" ]; then
echo "Could not find scripts/extract.py for book-to-skill" >&2
exit 1
fi
PYTHON_BIN="${PYTHON_BIN:-python3}"
if ! command -v "$PYTHON_BIN" >/dev/null 2>&1; then
PYTHON_BIN="python"
fi
"$PYTHON_BIN" "$SCRIPT_PATH" $INPUT_PATHS --mode <BOOK_TYPE> --install-missing ask
抽取前，脚本查各格式所需可选 Python 包。若缺更优抽取器，则提示君可用回退。非交互会话默认回退，除非安装模式明确为 yes。
提示——预检环境： 运行 "$PYTHON_BIN" "$SCRIPT_PATH" --check，可印各格式抽取器安装情况与安装缺失包之确切命令，而不处理任何文件。君报安装或品质问题时有用。
此步产出：
/book_skill_work/full_text.txt —— 所有源合并抽取文字，边界清晰 demarcated。/book_skill_work/metadata.json —— 合并大小、字数、页数、token 数，以及各处理源之详表。
读
/book_skill_work/metadata.json 以检结果。
---
Step 2.5 — 预飞成本估算
读 /book_skill_work/metadata.json，生成前先给君估算：
📖 检出源：<total_sources> 个源
<逐列出各源文件名与格式>
📄 合并页/节：约 <N> | 字数：约 <N> | 总 token：约 <N>K
💰 估算 token 成本（完全转换 / 更新）：
输入（读取 + 提示）：约 <N>K tokens
输出（生成/更新技能文件）：约 <N>K tokens
合计：约 <N>K tokens
参考价格（2025 年）：
Claude Sonnet 4.5 → 约 $<X> USD
Claude Haiku 4.5 → 约 $<X> USD
⏱ 估算耗时：约 <N> 分钟
📁 将生成/更新之文件：
SKILL.md + 章节文件 + 术语表 + 模式 + 速查表
➡ 是否继续完全转换 / 更新？（或输入 "analyze only" 先预览）
估算法：
- 输入 token ≈ metadata 之
estimated_tokens × 1.3（每章提示开销）
- 输出 token ≈ 章数 × 每章预算 + 4,000（SKILL.md） + 4,500（术语表 + 模式 + 速查表）
- 每章预算中值依
BOOK_TYPE（DEPTH 后定，可上调）：text ≈ 1,000，technical ≈ 1,800。若君已示参考 vs 深研，用 Step 7 矩阵对应行。
- 价格：Sonnet input=$3/MTok output=$15/MTok — Haiku input=$0.80/MTok output=$4/MTok
待君确认方行。若君言“analyze only”，转模式 2。
---
Step 2.6 — 大书（> 50k tokens）之 REPL 式访问
受 Recursive Language Model (RLM) 启发：视 full_text.txt 为可查询语料，而非一次性读入。全文入上下文，耗费本可留给生成之预算。
对超 ~50k tokens 之书，优先程式化探查，而非无界 Read(full_text.txt)：
# 尺寸检查
wc -w "$FULL_TEXT_PATH"
# 寻章偏移，不载全文
grep -n -E "^\s*(Chapter|CHAPTER)\s+[0-9]+" "$FULL_TEXT_PATH" | head -40
# 仅取所需章（含起止行）
sed -n '<start>,<end>p' "$FULL_TEXT_PATH"
# 认领框架前先验其确有提及
grep -c -i "westrum\|dora" "$FULL_TEXT_PATH"
# 带偏移/限制之 targeted Read，避免倾倒全文
# Read(file_path=full_text.txt, offset=<行>, limit=<行数>)
Step 3（结构分析）、Step 7（每章摘要）、Step 8（术语表/模式抽取）皆用此法。50k tokens 以下之书，单次 Read 即可。
何以重？200 页书约 75k tokens。每章重读一次（28 遍）耗 ~2M 输入 token；用 grep + sed 仅取相关片，生成成本与输出成比例，而非与源成比例。
---
Step 3 — 分析书结构
读抽取 full_text.txt 之前 8,000 字符，识：
- 书标题与作者
- 章结构（寻“Chapter N”、“PART I”、编号标题、目录）
- 核心主题与学科域
- 约章数
再读目录部分（若有），映射全章。
若模式为“仅分析”： 即产抽取报告并止。结构：
## 抽取报告 —— <标题>
### 作者核心框架
- **<框架名>**：<何为及何时用>
### 关键原则
- <原则>：<可行之规>
### 技法与方法
- <技法>：<步步或如何做>
### 反模式
- <当避者>：<所以>
### 建议技能名
`{作者姓氏}-{核心概念}` —— 例如 `cialdini-influence`
### 检出章节
| # | 标题 | 主要框架 |
---
Step 4 — 问目的（仅完全转换）
生成前，问君：
> "此技能欲助君何为？（可选一项或多项）
> 1. 实务中应用作者框架
> 2. 以作者心智模型思考
> 3. 参考特定章与概念
> 4. 以上皆是"
用答加权 SKILL.md 核心部分所强调者。
自答推 DEPTH（不另问）：
- 仅选选项 3（参考）→
DEPTH=reference —— 轻量、快速查阅章。
- 含选项 1、2 或 4 →
DEPTH=study —— 更深章，含更多实作细节、例与推理。
DEPTH 与
BOOK_TYPE 共定 Step 7 每章 token 预算。（模式 2/3 跳 Step 4 时，默认
DEPTH=study。）
---
Step 5 — 定技能名
若已给 SKILL_NAME，用之为 slug。
否则，提两选项，待君择：
- 作者-概念式：
{作者姓氏}-{核心概念}（例如 cialdini-influence、meadows-systems）
- 书名式：书名小写连字符（例如
designing-data-intensive-apps）
书有强方法论身份时，默认作者-概念式。
择技能根目录（SKILLS_HOME）。探君文件系统既有技能根，按君运行之主机择：
| 主机代理 | 个人技能根（探序） | 项目本地根 |
|---|
| GitHub Copilot CLI | ~/.copilot/skills → ~/.agents/skills | .github/skills → .claude/skills → .agents/skills |
| Amp | ~/.agents/skills → ~/.config/agents/skills → ~/.config/amp/skills | .agents/skills |
| Claude Code | ~/.claude/skills | .claude/skills |
择规：
1. 若主机候选根
恰有一存在于磁盘，无问即用。
2. 若
无（新机），问君欲建哪根——呈主机适配选项，记住本次会话选择。不默默认。
3. 若君明确要项目本地输出，优先项目本地行。
4. 若不能识主机，问：“君运行于何代理——GitHub Copilot CLI、Amp 或 Claude Code？”
设 SKILLS_HOME 为所选根，查 $SKILLS_HOME// 是否已存在。
若存在，提示君择：
1. 更新 / 折入（模式 4）—— 将新文件/内容并入既有技能组件。
2. 覆盖—— 删除并自头重生成。
3. 改名—— 追加 -2 或用不同自定义 slug。
若君选更新 / 折入，跳过 Step 3、4、6、7、8、9，直接行更新 / 折入流程（Step 2.5 后）。
---
Step 6 — 建技能目录结构
mkdir -p "$SKILLS_HOME/<skill_name>/chapters"
---
Step 7 — 生成章摘要
TOKEN 预算规则——要紧（自适应）：
每章预算随 BOOK_TYPE 与 DEPTH 伸缩。技术章需容代码与表格；深研需容实作推理。自下表择预算：
| DEPTH=reference | DEPTH=study |
|---|
BOOK_TYPE=text | 800–1,200 tokens | 1,000–1,800 tokens |
BOOK_TYPE=technical | 1,200–1,800 tokens | 2,000–3,000 tokens |
- 此为每文件目标，非硬上限——密章或超，薄章或不及。密度胜长度（质量规则 3）：勿为凑数而垫。
- 文件按需载入，故大章仅在实读时耗 token。
- 疑难时择较低预算，让深度来自精准，而非体积。
DEPTH=study 须以内容挣得，非更大数字。 标准节模板（核心理念 → 关联）自然使散文章落于 700–900 tokens 左右。欲诚实达深研预算——非垫——须加具体料：
- 重现章中一实作例或工件（例如作者所走之示例新闻稿、对话、填好之模板、决策全程），置于
## 实作例 节。此为最大杠杆，亦学习者复返所求。
- 将各框架之“How”展开为明确步骤或判据，非一行了事。
- 为前 1–2 框架加短“何以奏效 / 失效模式”注。
若章真无实作例且抗展开，则让其低于深研底，而非垫——并于核心理念注该章薄。反之，
reference 深度章故意略实作例，仅留决策-ready 精要。
对 Step 3 所识每章/大节：
读抽取 full_text.txt 对应部分（用字符偏移或 grep 章标题）。
用下结构建 $SKILLS_HOME//chapters/ch-.md。
依 BOOK_TYPE 调强调：
technical → 优先“代码例”“参考表”“命令与 API”节；确切存语法text → 优先“引入框架”“心智模型”“关键收获”；空技术节略去
# 第 N 章：<全标题>
## 核心理念
<1–2 句：本章所授最要者>
## 引入框架
- **<框架名>**：<确切表述——存作者命名>
- 何时用：<具体情境>
- 如何：<步骤或判据>
## 关键概念
- **<术语>**：<精确定义，一句>
（本章 5–10 最要术语）
## 心智模型
<2–4 框架或思维工具。写为“X 情境用 Y”或“视 X 为 Y”>
## 反模式
- **<当避者>**：<所以失效>
## 代码例（仅技术书——若 BOOK_TYPE=text 则略）
<!-- 复制章中最具启发之片段。确切存缩进。 -->
<语言>
<本章关键代码例>
- **示何**：<一句>
## 参考表（仅技术书——若 BOOK_TYPE=text 则略）
<!-- 将章中比较矩阵、参数表或决策表以 markdown 重现。 -->
## 实作例（仅 DEPTH=study——reference 深度略）
<!-- 重现或重构作者所走之一具体例：样本文档、对话、填好模板、前后对比、或决策全程。此为深研章值其预算之关键。忠于源；勿抄长原文——紧凑重构。 -->
## 关键收获
1. <可行洞见>
2. <可行洞见>
3. <可行洞见>
（实践者须记 3–7 条）
## 关联
- **第 N 章**：<何以相联>
- **<概念>**：<所联之外部概念或标准>
---
Step 8 — 生成支撑文件
glossary.md
建
$SKILLS_HOME//glossary.md：
- 书中所有要术语，字母序
- 格式：
术语 —— 定义（第 N 章）
- 最多 1,500 tokens
patterns.md
建
$SKILLS_HOME//patterns.md：
- 书中所有具体技法、设计模式、算法
- 格式：
## 模式名\n何时用：...\n如何：...\n权衡：...
- 最多 2,000 tokens
cheatsheet.md
建
$SKILLS_HOME//cheatsheet.md：
此为技能最殊层——视之为推理辅，而非关键词表。 任何人皆可 grep 术语表。速查表捕作者之判断：彼将如何决、何以。正是此文件使“识词”变为“我将如作者所为而行”。
优先序：
1. 决策规——“X 时，做 Y，因 Z。”作者所用 if/then 逻辑，述之使读者无需重读书即可用。
2. 决策树 / 流程图（嵌套 bullet 或小表）——多于两分支之选择。
3. 权衡矩阵——竞争选项依作者所重维度评分，使读者可依己约束择。
4. 阈值 & 默认——作者所定具体数字、比率或经验法则（例如“函数保持 ~20 行内”“错误预算 < 10% 时告警”）。
5. 征象 & 气味——速启发识情境（“见 X，恐陷 Y 困境”）。
避： bare 术语→定义行（那是术语表），与散文段（那是章）。每行皆助读者决某事。
- 格式多为紧凑表与决策规；可印一页置案头者。
- 最多 1,200 tokens。
---
Step 9 — 生成主 SKILL.md
要紧 TOKEN 预算： 保持 SKILL.md 正文 < 4,000 tokens。
压缩自末尾截——最要内容置最前。
建 $SKILLS_HOME//SKILL.md：
---
name: <skill_name>
description: "「<全标题>」作者 <作者> 之知识库。凡应用 <作者> 框架于 <关键主题，3–6 词>、研读本书或参考其概念者用之。"
---
<!-- argument-hint: [主题、框架名或章号] -->
# <全标题>
**作者**：<作者> | **页数**：约 <N> | **章数**：<N> | **生成**：<YYYY-MM-DD>
## 如何用此技能
- **无参数** —— 载核心框架供参考
- **带主题** —— 问 `replication`、`pricing` 或其他索引主题；我寻并读相关章
- **带章** —— 求 `ch05`；我载该章
- **浏览** —— 问“有哪些章？”见全索引
当君问及核心框架下未覆主题时，我将先读相关章文件再答。
---
## 核心框架与心智模型
<!-- ~2,000 tokens：作者最要已名框架与原则。
存确切名。写为“X 情境用 Y”“因 Z 故宁 X 勿 Y”。
乃 toolkit，非撮要。 -->
<此处生成最要框架与洞见，约 2,000 tokens>
---
## 章索引
| # | 标题 | 关键框架 |
|---|------|----------|
| [ch01](chapters/ch01-<slug>.md) | <标题> | <框架1>、<框架2> |
| [ch02](chapters/ch02-<slug>.md) | <标题> | <框架1>、<框架2> |
...
## 主题索引
<!-- 字母序。主要术语/框架 → 覆之章 -->
- **<术语>** → ch<N>[, ch<N>]
- **<术语>** → ch<N>
## 支撑文件
- [glossary.md](glossary.md) —— 所有关键术语与定义
- [patterns.md](patterns.md) —— 所有技法与设计模式
- [cheatsheet.md](cheatsheet.md) —— 速查表与决策导引
---
## 范围与限界
此技能仅覆本书内容。欲于代码库实作，须与项目特定工具合用。书外主题，请查相关技能或直问代理。
---
Step 10 — 清理与报告
PYTHON_BIN="${PYTHON_BIN:-python3}"
if ! command -v "$PYTHON_BIN" >/dev/null 2>&1; then
PYTHON_BIN="python"
fi
"$PYTHON_BIN" - <<'PY'
import os
import shutil
import tempfile
from pathlib import Path
shutil.rmtree(
os.environ.get("BOOK_SKILL_WORKDIR", Path(tempfile.gettempdir()) / "book_skill_work"),
ignore_errors=True,
)
PY
然后报君：
✅ 技能已建：$SKILLS_HOME/<skill_name>/
📚 书：<全标题> —— <作者>
📄 页数：约 <N> | 章数：<N>
生成文件：
SKILL.md —— 核心框架 + 索引 （约 X tokens）
chapters/ —— <N> 章摘要 （约 X tokens/章，合计约 X）
glossary.md —— 关键术语 （约 X tokens）
patterns.md —— 技法与模式 （约 X tokens）
cheatsheet.md —— 速查 （约 X tokens）
─────────────────────────────────────────────────────
技能总大小：约 X tokens（按需载入，非全载）
💡 提示：查君代理会话成本/用量命令，见实 token 耗。
用法：
问 <skill_name> → 载核心框架
问 <skill_name> 关于 <主题> → 寻并解主题
问 <skill_name> 要 ch<N> → 深潜某章
重载（若代理不自检新技能）：
GitHub Copilot CLI: /skills reload
Claude Code: 重启会话
Amp: 重启会话
分享此技能（Copilot 生态，可选）：
gh skill publish $SKILLS_HOME/<skill_name>
---
更新 / 折入流程
对 $SKILLS_HOME// 既有技能行更新/折入时：
1. 读既有技能结构
读并析既有技能文件：
- 读
$SKILLS_HOME//SKILL.md，析章索引、主题索引、元数据（作者、总章数）与核心框架。
- 列
$SKILLS_HOME//chapters/ 下所有文件，寻最高章号（例如 ch12）。
- 读
$SKILLS_HOME//glossary.md、$SKILLS_HOME//patterns.md 与 $SKILLS_HOME//cheatsheet.md，视已有术语与框架索引。
2. 匹配内容，识修订 vs 新增
析新抽取
/book_skill_work/full_text.txt，识新内容是否为：
- 既有章之更新/修订：若新内容直接更新或扩展既有章主题，读既有章文件，合并新细节，重写之。
- 新添：若引入新章、论文或独立节，则于
chapters/ 下建新章摘要文件。编号自既有最高章号后始（例如既有止于 ch12，则建 ch13-*.md、ch14-*.md 等）。
3. 生成或更新章摘要文件
对每新或修订章：
- 读新抽取文字对应部分。
- 循 Step 7 格式指南建摘要。
- 写/更新
$SKILLS_HOME//chapters/ 下文件。
4. 合并支撑文件
- 合并 glossary.md：
- 读既有
$SKILLS_HOME//glossary.md。
- 自新内容抽所有新术语与定义（Step 8 术语表指南）。
- 合既有与新术语，字母序。
- 若术语已存，追加新章/源引用（例如
术语 —— 定义（第 4 章、第 13 章））。
- 重写
$SKILLS_HOME//glossary.md，为完全合并、字母序列表。
- 合并 patterns.md：
- 读既有
$SKILLS_HOME//patterns.md。
- 自新内容抽新技法、算法或模式。
- 追加新模式，格式一致，总长精简（< 2,500 tokens）。
- 合并 cheatsheet.md：
- 读既有
$SKILLS_HOME//cheatsheet.md。
- 抽新比较规、决策表或参数导。
- 洁净并入速查表结构。
5. 重生成主 SKILL.md
更新主技能文件
$SKILLS_HOME//SKILL.md：
- 元数据：递增章数，更新估页数，适加新源名。更新
Generated 日期为今日。
- 核心框架：折入新内容中最具冲击之心智模型或原则（确保全文件仍 < 4,000 tokens）。
- 章索引：追加新章至索引表，链向新建文件。
- 主题索引：字母序合并新主题。若既有主题亦为新章所覆，追加新章链（例如
- 主题 → ch05, ch13）。
6. 清理并行 Step 10
文件成功写并合并后，跳
Step 10 做清理，印定制更新报告，总结新添章、合并术语与更新索引。
---
质量守则
1. 抽结构，非撮要 —— 捕已名框架、确切表述、反模式；非章回
2. 存作者之精微 —— “五问法” ≠ “多问何故”；存确切命名
3. 密度胜完备 —— 1,000 token 摘要胜 10,000 token 摘抄
4. 实践者声调 —— 写“X 情境用 Y”，非“书解释 X”
5. 前置 SKILL.md —— 压缩保前 5,000 tokens；最要内容最前
6. 章文件按需 —— 载入前不计入技能预算
7. 勿抄原书文字 —— 恒合成、撮要、抽信号
8. 主题索引要紧 —— 代理赖之以导航至正确章文件
---