Book-to-Skill 转换器

通过提取结构——而非生成摘要——将书面知识转化为可操作的智能体技能。

理念

书籍蕴含精炼的专业知识：框架、原则和技术，它们历经数年发展而成。本技能提取这些知识，形成 GitHub Copilot CLI、Amp、Claude Code 或其他兼容智能体能够反复利用的格式。

提取结构，而非摘要。 技能不是读书笔记。它是一套工具包，包含：

命名框架（具有明确适用场景的思维模型）
可操作原则（指导决策的规则）
技术（逐步方法）
反模式（应避免什么及其原因）
语调校准（作者的思考与表达方式）

保留作者的精准性。 框架的名称往往有其原因。“5个为什么”不能替换为“多次问为什么”。捕捉确切的表述。

按适当层次进行深度处理。 简单的书籍 → 简单的技能。包含10个以上框架的复杂书籍 → 附带参考文件和按需章节的技能。

工作模式

提供四种路径。根据用户的请求进行路由：

1. 完整转换（默认）

触发条件： 用户提供一个或多个文档/目录/通配符路径，无特殊说明 操作： 运行以下所有步骤（步骤 0–9） 输出： 完整的技能，包含 SKILL.md、chapters/、glossary、patterns、cheatsheet

2. 仅分析

触发条件： 用户说“分析”、“仅提取”或“我想在生成前审阅” 操作： 运行步骤 0–3，然后生成结构化的提取报告（找到的框架、原则、技术）。停止——不生成技能文件。 输出： 供用户审阅的分析报告

3. 基于已有分析生成

触发条件： 用户已有分析笔记或之前运行过仅分析模式 操作： 跳过步骤 0–3，使用提供的分析作为输入，运行步骤 4–9 输出： 根据提供的分析生成技能文件

4. 更新/并入（现有技能）

触发条件： 用户提供一个或多个新源路径，并说明要更新现有技能（通过指向现有技能文件夹、提供 SKILLS_HOME 中已存在的技能 slug，或明确请求更新） 操作： 运行步骤 0（范围外检查）、步骤 1（验证输入）、步骤 1.5（识别书籍类型）、步骤 2（提取新文件）。然后跳至步骤 5（识别/检测现有技能路径）并运行更新/并入工作流，将新内容合并到现有技能文件中。 输出： 更新后的现有技能，包含新的/修订的章节摘要以及合并的索引/词汇表。

技能位置

此转换器可从多种技能系统运行。在查找此转换器的辅助脚本或写入生成的书籍技能时，按以下顺序优先选择位置：

GitHub Copilot CLI 个人技能：~/.copilot/skills/
跨智能体个人技能（Copilot + Amp）：~/.agents/skills/
Claude Code 个人技能：~/.claude/skills/
项目本地 Copilot 技能：.github/skills/
项目本地 Claude 技能：.claude/skills/
项目本地 Amp / Copilot 技能：.agents/skills/
Amp 全局技能：~/.config/agents/skills/
Amp 旧版全局技能：~/.config/amp/skills/

对于生成的书籍技能，选择一个用户的主机智能体实际能够发现的目标目录（参见步骤 5）。当存在多个有效根目录时，询问用户一次并在会话期间记住答案——不要静默使用默认值。

步骤 0 — 范围外检查

如果未提供任何参数，则停止并回复：

“book-to-skill 需要一个受支持的文档路径、目录或通配符模式。用法：book-to-skill <文档目录路径或通配符>... [技能名称-slug]”

在整个工作流中：

识别输入路径和可选的技能 slug。
如果最后一个参数不是文件、目录或存在或匹配任何文件的通配符，并且看起来像技能 slug（例如小写连字符、字母数字），则将其视为 SKILL_NAME。
将所有其他参数视为 INPUT_PATHS 列表。
如果任何输入路径是现有技能目录（包含 SKILL.md 和 chapters/ 子文件夹），或者 SKILL_NAME 匹配 SKILLS_HOME 中的现有技能 slug，则将此运行标记为更新/并入操作（模式 4）。

步骤 1 — 验证输入

确认 INPUT_PATHS 中至少有一个受支持的文件、目录或通配符模式。对于目录和通配符，展开以找到匹配的受支持文件（.pdf、.epub、.docx、.txt、.md、.markdown、.rst、.adoc、.html、.htm、.rtf、.mobi、.azw、.azw3）。

如果未找到受支持的文件，则停止并显示清晰的错误消息。

步骤 1.5 — 识别内容类型

在提取之前，询问用户：

“这些来源的内容类型是什么？这有助于我选择最佳的提取方法。

技术类 — 包含代码块、表格、公式、图表（例如编程书籍、学术论文、架构指南）

文本为主 — 主要是散文，很少或没有表格/代码（例如管理、生产力、叙事类非虚构作品）

不确定 — 我将使用快速方法，如果质量看起来有限会警告你”

将答案存储为 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。”

步骤 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 "找不到 book-to-skill 的 scripts/extract.py" >&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 可以打印按格式分列的提取器安装状态报告，以及安装缺失项的确切命令，而不处理任何文件。当用户报告设置或质量问题时很有用。

这将创建：

<tempdir>/book_skill_work/full_text.txt — 所有来源的组合提取文本，带有清晰可见的分隔边界。
<tempdir>/book_skill_work/metadata.json — 总体组合大小、字数、页数、token 数量以及已处理的各个 sources 的详细列表。

读取 <tempdir>/book_skill_work/metadata.json 以检查结果。

步骤 2.5 — 预检成本估算

读取 <tempdir>/book_skill_work/metadata.json 并在进行任何生成之前向用户提供估算：

📖 检测到的来源：<total_sources> 个来源
<列出来源元数据列表中的每个来源文件名和格式>
📄 合并页数/章节：~<N> | 字数：~<N> | 总 token 数：~<N>K

💰 预估 token 成本（完整转换/更新）：
   输入（读取 + 提示）：~<N>K token
   输出（生成的技能文件/更新）：~<N>K token
   总计：~<N>K token

   费用：将上述 token 数量乘以您模型当前的输入/输出每百万 token 费率（价格和模型名称经常变化——不要硬编码；引用今天的费率并标记为估算值）。

   ⏱  预估时间：~<N> 分钟

📁 将要生成/更新的文件：
   SKILL.md + 章节文件 + 词汇表 + 模式 + 速查表

➡  是否继续完整转换/更新？（或输入“仅分析”以先预览）

如何估算：

输入 token ≈ 元数据中的 estimated_tokens × 1.3（每章传递的提示开销）
输出 token ≈ 章节数 × 每章预算 + 4,000（SKILL.md）+ 4,500（词汇表 + 模式 + 速查表）
- 根据 BOOK_TYPE 确定的每章预算中点（DEPTH 在步骤 4 中决定，可以提高预算）：text ≈ 1,000，technical ≈ 1,800。如果用户已经指示了仅参考或深度研究，则使用步骤 7 矩阵的相应行。
费用：报告 token 数量并乘以用户当前每百万 token 输入/输出费率。不要硬编码美元金额——模型名称和价格会变化；如果显示，请将其标记为估算值并注明日期。

等待用户确认后再继续。如果用户说“仅分析”，则切换到模式 2。

步骤 2.6 — 针对大书的 REPL 式访问（超过 50k token）

受递归语言模型（RLM）范例启发：将 full_text.txt 视为可查询的语料库，而不是一次性读取。将整个文件加载到上下文中会消耗您稍后生成所需的预算。

对于超过约 50k token 的书籍，优先使用程序化探测而不是无限制的 Read(full_text.txt)：

# 在读取之前进行大小检查
wc -w "$FULL_TEXT_PATH"

# 在不加载整个文件的情况下查找章节偏移量
grep -n -E "^\s*(Chapter|CHAPTER)\s+[0-9]+" "$FULL_TEXT_PATH" | head -40

# 只提取您需要的章节（行号 start..end 包含）
sed -n '<start>,<end>p' "$FULL_TEXT_PATH"

# 在 SKILL.md 中声称某个框架之前验证它是否实际被提及
grep -c -i "westrum\|dora" "$FULL_TEXT_PATH"

# 使用偏移量/限制的目标读取避免转储整个文件
# Read(file_path=full_text.txt, offset=<line>, limit=<lines>)

在步骤 3（结构分析）、步骤 7（每章摘要）和步骤 8（词汇表/模式提取）中使用此方法。对于低于 50k token 的书籍，单次 Read 就足够了。

为什么这很重要：一本 200 页的书大约有 75k token。每章重新阅读一次（28 次传递）会消耗约 2M 输入 token；使用 grep + sed 仅提取相关切片可以使生成成本与输出成正比，而不是与源文档大小成正比。

步骤 3 — 分析书籍结构

读取提取的 full_text.txt 的前 8,000 个字符以识别：

书籍标题和作者
章节结构（查找“Chapter N”、“PART I”、编号标题、目录）
核心主题和学科领域
近似章节数

然后读取目录部分（如果存在）以映射所有章节。

如果是“仅分析”模式： 现在生成提取报告并停止。结构如下：

## 提取报告 — <标题>

### 作者的核心框架
- **<框架名称>**：<是什么以及何时应用>

### 关键原则
- <原则>：<可操作规则>

### 技术与方法
- <技术>：<逐步操作或操作方法>

### 反模式
- <应避免什么>：<原因>

### 建议的技能名称
`{作者姓氏}-{核心概念}` — 例如 `cialdini-influence`

### 检测到的章节
| # | 标题 | 主要框架 |

步骤 4 — 询问目的（仅完整转换）

在生成之前，询问用户：

“这个技能应该帮你做什么？（选择一个或多个）

在工作中应用作者的框架

用作者的思维模型进行思考

参考特定章节和概念

以上全部”

使用答案来决定在 SKILL.md 核心部分中突出显示什么。

从答案中推导 DEPTH（无需额外提示）：

答案仅为选项 3（参考）→ DEPTH=reference — 简洁、快速查找的章节。
答案包含选项 1、2 或 4 → DEPTH=study — 更深入的章节，包含更多详细工作、示例和推理。

DEPTH 和 BOOK_TYPE 共同决定步骤 7 中每章的 token 预算。不要单独询问“研究 vs 参考”的问题——这里已经推断得出。（在模式 2/3 中，步骤 4 被跳过，默认 DEPTH=study。）

步骤 5 — 确定技能名称

如果提供了 SKILL_NAME，则将其用作技能 slug。否则，提出两个选项并让用户选择：

按作者-概念： {作者姓氏}-{核心概念}（例如 cialdini-influence、meadows-systems）
按标题： 从书籍标题转换的小写连字符形式（例如 designing-data-intensive-apps）

如果书籍具有强烈的方法论身份，则默认使用作者-概念格式。

选择目标技能根目录（SKILLS_HOME）。探测用户的文件系统以查找现有技能根目录，并根据用户正在运行的主机智能体进行选择：

| 主机智能体 | 个人

Leutenegger/book-to-skill

book-to-skill 是什么？

在你喜欢的 AI 中提问

文档

Book-to-Skill 转换器

理念

工作模式

1. 完整转换（默认）

2. 仅分析

3. 基于已有分析生成

4. 更新/并入（现有技能）

技能位置

步骤 0 — 范围外检查

步骤 1 — 验证输入

步骤 1.5 — 识别内容类型

步骤 2 — 从源文档中提取文本

步骤 2.5 — 预检成本估算

步骤 2.6 — 针对大书的 REPL 式访问（超过 50k token）

步骤 3 — 分析书籍结构

步骤 4 — 询问目的（仅完整转换）

步骤 5 — 确定技能名称

相关技能

steipete/notion

langchain-ai/langchain

bytedance/podcast-generation

composiohq/twitter-algorithm-optimizer

composiohq/competitive-ads-extractor

upstash/context7