book-to-skill 的 SKILL.md 中文版

这是一份完全本地化、翻译并优化为中文环境可用的 SKILL.md。它保留了所有代码逻辑、系统变量和 Agent 指令，同时将需要输出给用户的交互提示语、生成模板以及 Agent 的思考指南转化为了流畅的中文。

你可以直接将其保存为你的 SKILL.md。

---
name: book-to-skill
description: "将书籍和文档 (PDF, EPUB, DOCX, HTML, Markdown, 纯文本, RTF, 借助 Calibre 的 MOBI/AZW) 转换为结构化的 Agent 技能，提取其中的框架、心智模型、原则、技术和反模式。当用户希望通过 GitHub Copilot CLI、Amp 或 Claude Code 学习文档，在工作时应用作者的框架，或者从文件构建可复用的知识库时，请使用此技能。"
---

<!--
跨 Agent 注意事项 (仅供参考；宿主 agent 会忽略此内容):
  - 兼容的技能根目录: GitHub Copilot CLI (~/.copilot/skills, ~/.agents/skills,
    .github/skills, .claude/skills, .agents/skills), Amp (.agents/skills,
    ~/.config/agents/skills, ~/.config/amp/skills), Claude Code (~/.claude/skills)。
  - 故意省略了 `allowed-tools` 以保持对不同 Agent 的中立性：Copilot CLI 使用 
    `shell`/MCP-server 名称，Claude 使用 `Bash`/`Read`/`Write`/`Glob`/`Grep`，Amp 
    添加了 `shell_command`。该技能需要 shell（运行 extract.py）和文件
    读写权限 — 宿主系统会在首次使用时提示授权。
  - 参数提示: <文档文件夹或glob的路径>... [技能名称-slug]
-->

# 书籍转技能 (Book-to-Skill) 转换器

将书面知识转化为可执行的 Agent 技能——提取其深层结构，而不是仅仅生成摘要。

## 核心理念 (Philosophy)

书籍包含作者结晶化的专业知识：历经数年发展出的框架、原则和技术。此技能将这些知识提取为一种特殊格式，让 GitHub Copilot CLI、Amp、Claude Code 或其他兼容的 Agent 能够反复利用。

**提取结构，而非总结摘要。** 一个技能不是一份读书报告。它是一个工具箱，包含：
- 命名的框架（具有明确应用场景的心智模型）
- 可执行的原则（指导决策的规则）
- 技术与方法（循序渐进的方法论）
- 反模式（应该避免什么以及为什么）
- 语调校准（作者如何思考和沟通）

**保留作者的精确性。** 框架的命名通常有其特定原因。“5问法 (The 5 Whys)”与“多问几次为什么”是不能互换的。请捕捉精确的表述。

**适度分层。** 简单的书 → 简单的技能。包含 10 个以上框架的复杂书籍 → 带有参考文件和按需加载章节的复杂技能。

---

## 运行模式 (Modes of Operation)

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

### 1. 完整转换 (默认)
**触发条件:** 用户提供了一个或多个文档/目录/glob路径，且没有特殊指示
**执行动作:** 运行下方所有步骤 (Step 0–9)
**输出:** 包含 SKILL.md、chapters/ 目录、术语表(glossary)、模式(patterns)和速查表(cheatsheet)的完整技能

### 2. 仅分析 (Analyze Only)
**触发条件:** 用户说“分析 (analyze)”、“仅提取 (just extract)”或“我想在生成前先看看 (review before generating)”
**执行动作:** 运行 Step 0–3，然后生成一份结构化的提取报告（找到的框架、原则、技术）。然后停止 — **不要**生成技能文件。
**输出:** 供用户审查的分析报告

### 3. 基于先前的分析生成
**触发条件:** 用户拥有现有的分析笔记，或之前运行过“仅分析”
**执行动作:** 跳过 Step 0–3，使用提供的分析作为输入，运行 Step 4–9
**输出:** 根据提供的分析生成的技能文件

### 4. 更新 / 融入 (针对现有技能)
**触发条件:** 用户提供了一个或多个新的源路径，并表示希望更新现有技能（通过指向现有技能文件夹、提供 `SKILLS_HOME` 中已存在的技能 slug，或明确要求更新）。
**执行动作:** 运行 Step 0 (范围外检查)、Step 1 (验证输入)、Step 1.5 (识别书籍类型) 和 Step 2 (提取新文件)。然后跳至 Step 5 (识别现有技能路径) 并运行 **更新 / 融入工作流 (Update / Fold-in Workflow)**，将新内容合并到现有技能文件中。
**输出:** 更新后的现有技能，包含新增/修订的章节摘要和合并后的索引/术语表。

---

## 技能存储位置 (Skill Locations)

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

1. GitHub Copilot CLI 个人技能: `~/.copilot/skills/`
2. 跨 Agent 个人技能 (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/`

对于**生成**的书籍技能，请选择用户宿主 Agent 实际能够发现的目标位置（见 Step 5）。如果存在多个有效的根目录，**请询问用户一次并在会话中记住该答案 — 不要静默使用默认值**。

---

## Step 0 — 范围外检查 (Out-of-scope check)

如果没有提供参数，请停止并回复：
> "book-to-skill 需要支持的文档路径、文件夹或 glob 模式。用法：`book-to-skill <文档文件夹或glob路径>... [技能名称-slug]`"

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

---

## Step 1 — 验证输入 (Validate input)

验证 `INPUT_PATHS` 中至少有一个受支持的文件、目录或 glob 模式。
对于目录和 globs，展开它们以寻找匹配的受支持文件 (`.pdf`, `.epub`, `.docx`, `.txt`, `.md`, `.markdown`, `.rst`, `.adoc`, `.html`, `.htm`, `.rtf`, `.mobi`, `.azw`, `.azw3`)。

如果没有找到受支持的文件，请显示清晰的错误信息并停止。

---

## Step 1.5 — 识别内容类型 (Identify content type)

在提取之前，向用户提问：

> "这些来源包含哪种类型的内容？这将帮助我选择最佳的提取方法。
>
> 1. **技术类 (Technical)** — 包含代码块、表格、公式、图表（如编程书籍、学术论文、架构指南）
> 2. **纯文本类 (Text-heavy)** — 主要是文字，几乎没有表格/代码（如管理、生产力、叙事性非虚构类）
> 3. **不确定 (Not sure)** — 我将使用快速方法，如果质量受限会提醒你"

将答案存储为 `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 — 从源文档提取文本 (Extract text)

运行提取脚本，传入输入路径：

```bash
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 包。如果缺少更好的提取器，它会提示用户使用可用的降级方案。非交互式会话默认使用降级方案，除非明确将 install mode 设置为 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 以检查结果。

Step 2.5 — 预检成本估算 (Pre-flight cost estimate)

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

📖 检测到来源：<总来源数> 个
<列出 sources metadata 列表中的每个源文件名和格式>
📄 合计页数/章节：约 <N> | 字数：约 <N> | 总 Token 数：约 <N>K

💰 预估 Token 成本 (完整转换 / 更新)：
   输入 (读取 + 提示词)：约 <N>K tokens
   输出 (生成/更新技能文件)：约 <N>K tokens
   总计：               约 <N>K tokens

   成本预估：请将上述 Token 数乘以您当前所用模型的
   输入/输出每百万 Token 费率（因模型和定价经常变动，
   此处不写死金额；请引用今日的费率并注明为预估）。

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

📁 将生成/更新的文件：
   SKILL.md + 章节文件 + glossary(术语表) + patterns(模式) + cheatsheet(速查表)

➡  是否继续进行完整转换 / 更新？（或回复 "analyze only" 以先进行预览）

如何估算：

  • 输入 tokens ≈ metadata 中的 estimated_tokens × 1.3（每个章节生成的提示词开销）

  • 输出 tokens ≈ 章节数 × 每章预算 + 4,000 (SKILL.md) + 4,500 (术语表 + 模式 + 速查表)

  • 根据 BOOK_TYPE 确定每章预算中位数（DEPTH 在 Step 4 决定，可能会提高它）：text ≈ 1,000, technical ≈ 1,800。如果用户已表明只是参考而非深度学习，使用 Step 7 矩阵的对应行。

  • 成本：报告 Token 数量，并乘以用户当前的每百万 Token 输入/输出费率。不要硬编码具体的美元数字 — 标注这是一个预估值和当前日期。

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

Step 2.6 — 针对大型书籍的 REPL 式访问 (> 50k tokens)

灵感来自递归语言模型 (RLM) 范式：将 full_text.txt 视为可查询的语料库，而不是一次性通读的文件。将整个文件加载到上下文中会耗尽后续生成所需的 Token 预算。

对于超过 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

# 仅提取需要的章节 (提取 start..end 之间的行)
sed -n '<start>,<end>p' "$FULL_TEXT_PATH"

# 在 SKILL.md 宣称某框架前，验证它确实被提及
grep -c -i "westrum\|dora" "$FULL_TEXT_PATH"

# 使用带有 offset/limit 的目标读取，避免转储完整文件
# Read(file_path=full_text.txt, offset=<line>, limit=<lines>)

在 Step 3 (结构分析)、Step 7 (每章摘要) 和 Step 8 (术语/模式提取) 中使用这种方法。对于低于 50k tokens 的书籍，单次 Read 即可。

为什么这很重要：一本 200 页的书约 75k tokens。每章重读一次（假设28个传递）耗费约 2M 输入 tokens；使用 grep + sed 仅提取相关片段，使生成成本与输出成正比，而不是与源文件成正比。

Step 3 — 分析书籍结构 (Analyze book structure)

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

  • 书籍 书名 (Title) 和 作者 (Author)
  • 章节结构（查找“第 N 章”、“PART I”、带编号的标题、目录）
  • 核心主题 和学科领域
  • 约略的章节数量

然后如果存在目录 (Table of Contents) 部分，请阅读它以映射所有章节。

如果模式是“仅分析 (Analyze Only)”： 立即生成提取报告并停止。格式如下：

## 提取报告 — <书名>

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

### 关键原则
- <原则>: <可执行的规则>

### 技术与方法
- <技术>: <分步指南或操作方法>

### 反模式
- <要避免什么>: <原因>

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

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

Step 4 — 询问意图 (仅限完整转换)

在生成之前，向用户提问：

"这个技能主要用来帮你做什么？(可多选)

  1. 在工作时应用作者的框架
  2. 运用作者的心智模型进行思考
  3. 参考特定的章节和概念
  4. 以上全部"

利用该答案来决定 SKILL.md “核心内容 (Core)” 部分的侧重点。

从中推导出 DEPTH 参数（不需要额外提问）：

  • 答案只有选项 3 (参考) → DEPTH=reference — 精简、便于快速查阅的章节。
  • 答案包含 1、2 或 4 → DEPTH=study — 更有深度的章节，包含更多具体案例、示例和推理过程。

DEPTH 和 BOOK_TYPE 共同决定了 Step 7 中的单章 Token 预算。千万不要单独问一个“学习还是参考”的问题——这会在这里自动推断。（在跳过 Step 4 的模式 2/3 中，默认 DEPTH=study。）

Step 5 — 确定技能名称 (Determine skill name)

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

  • 按作者-概念: {作者姓氏}-{核心概念} (例如 cialdini-influence, meadows-systems)
  • 按书名: 提取书名的拼音或英文小写及连字符 (例如 designing-data-intensive-apps)

如果该书具有很强的方法论特征，默认推荐“作者-概念”格式。

选择目标技能根目录 (SKILLS_HOME)。探测用户文件系统中存在的技能位置，并根据用户当前运行的宿主进行选择：

宿主 Agent 个人技能根目录 (按顺序探测) 项目本地根目录
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. 如果用户明确要求输出为项目本地(project-local)，优先选择项目本地的那一行。
  4. 如果无法识别宿主，询问："你是在哪个 Agent 中运行此操作的 — GitHub Copilot CLI、Amp 还是 Claude Code？"

将 SKILLS_HOME 设置为选定的根目录，并检查 $SKILLS_HOME/<skill_name>/ 是否已存在。
如果已存在，提示用户选择：

  1. 更新 / 融入 (Update / Fold-in) (模式 4) — 将新文件/内容整合到现有的技能组件中。
  2. 覆盖 (Overwrite) — 删除并从头重新生成该技能。
  3. 重命名 (Rename) — 附加 -2 或使用其他自定义 slug。

如果用户选择 更新 / 融入，请直接跳至 Step 2.5 之后的 更新 / 融入工作流部分（跳过 Step 3, 4, 6, 7, 8, 9）。

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 左右。要真正达到学习(study)预算的地步 —— 而不是水字数 —— 学习深度的章节必须添加具体的材料：

  • 重现章节中的一个具体推演案例或产出物（例如：新闻稿示例、对话范例、填写好的模板、作者从头到尾演练的决策过程），放在 ## 案例推演 (Worked Example) 小节下。这是最大的抓手，也是学习者回头查阅的主要原因。
  • 扩展每个框架的“如何做 (How)”，写出明确的步骤或标准，而不是一句废话。
  • 为最核心的 1-2 个框架补充“为什么有效 / 失败模式”。

如果某章节确实没有推演示例，且很难扩写，那就让它低于“study”的预算下限，而不是强行注水 — 并在文档中说明该章节的核心观点较为单薄。相反，reference 深度的章节则有意省略推演示例，只保留准备用于决策的精要。

对于 Step 3 中识别出的每个章节/主要部分：

读取提取出的 full_text.txt 相应部分（使用字符偏移量或 grep 查找章节标题）。

使用以下结构创建 $SKILLS_HOME/<skill_name>/chapters/ch<NN>-<slug>.md。

根据 BOOK_TYPE 调整侧重点：

  • technical → 优先考虑“代码示例 (Code Examples)”、“参考表格 (Reference Tables)”和“命令与API (Commands & APIs)”；精准保留语法。
  • text → 优先考虑“引入的框架 (Frameworks Introduced)”、“心智模型 (Mental Models)”和“核心要点 (Key Takeaways)”；忽略空的技术部分。
# 第 N 章: <完整标题>

## 核心观点 (Core Idea)
<1–2 句话：本章教授的最重要的一件事>

## 引入的框架 (Frameworks Introduced)
- **<框架名称>**: <精确的表述 — 保留作者的命名>
  - 何时使用: <特定情境>
  - 如何操作: <步骤或标准>

## 关键概念 (Key Concepts)
- **<术语>**: <用1句话精确定义>
(本章最重要的 5–10 个术语)

## 心智模型 (Mental Models)
<2–4 个框架或思考工具。写成 "当 Y 发生时，使用 X" 或 "将 X 视为 Y">

## 反模式 (Anti-patterns)
- **<应避免什么>**: <为什么它会失败>

## 代码示例 (Code Examples) *(仅技术类书籍 — 如果是纯文本则省略)*
<!-- 复制本章最具指导意义的代码片段。严格保留缩进。 -->
```<language>
<本章的关键代码示例>
  • 它展示了什么: <一句话总结>

参考表格 (Reference Tables) (仅技术类书籍 — 如果是纯文本则省略)

案例推演 (Worked Example) (仅限 DEPTH=study — 如果是 reference 则省略)

核心要点 (Key Takeaways)

  1. <可执行的洞察>
  2. <可执行的洞察>
  3. <可执行的洞察>
    (从业者必须记住的 3–7 个要点)

关联概念 (Connects To)

  • 第 N 章: <为什么本章与其相关>
  • <概念>: <与之相连的外部概念或标准>

---

## Step 8 — 生成支持文件

### glossary.md (术语表)
创建 `$SKILLS_HOME/<skill_name>/glossary.md`:
- 书中每个重要的术语，按字母 (或拼音) 排序
- 格式: `**术语** — 定义 (第 N 章)`
- 最多 1,500 tokens

### patterns.md (模式与技术)
创建 `$SKILLS_HOME/<skill_name>/patterns.md`:
- 书中所有具体的技术、设计模式、算法
- 格式: `## 模式名称\n**何时使用**: ...\n**如何操作**: ...\n**权衡与妥协**: ...`
- 最多 2,000 tokens

### cheatsheet.md (速查表)
创建 `$SKILLS_HOME/<skill_name>/cheatsheet.md`:

**这是该技能最具差异化的层面——请将其视为“推理辅助工具”，而不是关键词列表。** 任何人都可以去术语表 grep 搜索一个词。速查表捕捉的是作者的**判断力**：他们会做什么决定，以及为什么。这个文件能把“我知道这些词”变成“我会像作者那样行动”。

按优先顺序包括：
1. **决策规则 (Decision rules)** — “遇到 X，就做 Y，因为 Z。” 阐述作者采用的“如果/那么”逻辑，让读者不需重读书籍就能直接应用。
2. **决策树 / 流程图 (Decision trees)** (以嵌套列表或小型表格的形式) — 用于具有两个以上分支的选择。
3. **权衡矩阵 (Trade-off matrices)** — 针对作者关注的维度对竞争选项进行评分，使读者能在自己的约束条件下做出选择。
4. **阈值与默认值 (Thresholds & defaults)** — 作者承诺的特定数字、比率或经验法则（例如“保持函数在 20 行以内”、“当错误预算 < 10% 时触发警报”）。
5. **迹象与嗅觉 (Tells & smells)** — 快速识别情况的启发式方法（“如果你看到 X，你可能遇到了麻烦 Y”）。

避免：单纯的“术语→定义”行（那属于术语表），以及长篇大论的段落（那属于章节）。每一行都应该帮助读者*做出决定*。

- 尽量将其格式化为紧凑的表格和决策规则；也就是那种你希望在一张 A4 纸上打印出来放在手边工作的内容。
- 最多 1,200 tokens。

---

## Step 9 — 生成主 SKILL.md

**极其关键的 Token 预算：保持 SKILL.md 主体在 4,000 tokens 以内。**
Agent 会从末尾截断内容 — 将最重要的内容放在最前面。

创建 `$SKILLS_HOME/<skill_name>/SKILL.md`（注意保持 frontmatter 键名为英文）：

```markdown
---
name: <skill_name>
description: "提取自 <Author(s)> 著作《<完整书名>》的知识库。当你在 <核心主题，3-6 个术语> 的工作上应用作者的框架，或希望学习该书、参考其概念时使用此技能。"
---

<!-- argument-hint: [主题, 框架名称, 或章节编号] -->

# <完整书名>
**作者**: <Author(s)> | **页数**: 约 <N> | **章节数**: <N> | **生成时间**: <YYYY-MM-DD>

## 如何使用本技能 (How to Use This Skill)

- **无参数** — 加载核心框架作为参考
- **提供主题** — 询问关于 `replication`、`定价` 或索引中的其他主题；我会找到并阅读相关章节
- **提供章节** — 请求 `ch05`；我会加载该特定章节
- **浏览** — 问“你有什么章节？”以查看完整索引

当您询问核心框架(Core Frameworks)中未涵盖的主题时，我会在回答前去阅读相关的章节文件。

---

## 核心框架与心智模型 (Core Frameworks & Mental Models)
<!-- 约 2,000 tokens：作者最重要且命名的框架和原则。
     保留精确的名称。写成 "当 Y 时使用 X"、"优先选 X 而非 Y，因为 Z"。
     这是一个工具箱，不是摘要。 -->

<在此处生成 2,000 tokens 的最关键框架和深刻见解>

---

## 章节索引 (Chapter Index)

| # | 标题 | 关键框架 |
|---|-------|----------------|
| [ch01](chapters/ch01-<slug>.md) | <章节标题> | <框架1>, <框架2> |
| [ch02](chapters/ch02-<slug>.md) | <章节标题> | <框架1>, <框架2> |
...

## 主题索引 (Topic Index)

<!-- 字母或拼音排序。主要术语/框架 → 涵盖它们的章节。 -->
- **<术语>** → ch<N>[, ch<N>]
- **<术语>** → ch<N>

## 支持文件 (Supporting Files)

- [glossary.md](glossary.md) — 所有关键术语及其定义
- [patterns.md](patterns.md) — 所有技术和设计模式
- [cheatsheet.md](cheatsheet.md) — 快速参考表和决策指南

---

## 范围与限制 (Scope & Limits)

本技能仅涵盖书籍内容。若要在代码库中实际实施，请结合针对特定项目的工具。对于超出本书范围的主题，请查看相关技能或直接询问 Agent。

Step 9.5 — 扫描生成的技能 (Scan the generated skill)

在向用户报告成功、在另一个会话中加载技能或发布它之前，运行建议性安全扫描：

SKILL_CONVERTER_ROOT="$(cd "$(dirname "$SCRIPT_PATH")/.." && pwd)"
"$PYTHON_BIN" "$SKILL_CONVERTER_ROOT/tools/scan_generated_skill.py" "$SKILLS_HOME/<skill_name>"

如果扫描仪以非零状态退出，请停止并要求人类检查其找出的文件/行信息。不要静默重写生成的文件，在发现被解决或人类明确接受之前，不要加载或发布该技能。

Step 10 — 清理并报告 (Cleanup and report)

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 (按需加载，绝非一次性读取)

💡 提示: 检查你的 Agent 会话成本/用量命令，以查看实际的 Token 使用情况。

使用方法:
  请求 <skill_name>                 → 加载核心框架
  向 <skill_name> 询问 <某主题>       → 查找并解释该主题
  向 <skill_name> 请求 ch<N>        → 深入特定章节

重新加载 (如果您的 Agent 无法自动检测新技能):
  GitHub Copilot CLI:  /skills reload
  Claude Code:         重启会话
  Amp:                 重启会话

分享此技能 (Copilot 生态系统，可选):
  gh skill publish $SKILLS_HOME/<skill_name>

更新 / 融入工作流 (Update / Fold-in Workflow)

在对 $SKILLS_HOME/<skill_name>/ 的现有技能执行“更新/融入”操作时：

1. 读取现有技能结构

读取并解析现有技能的文件：

  • 读取 $SKILLS_HOME/<skill_name>/SKILL.md 解析现有的章节索引 (Chapter Index)、主题索引 (Topic Index)、元数据（作者、总章节数）和核心框架 (Core Frameworks)。
  • 列出 $SKILLS_HOME/<skill_name>/chapters/ 中的所有文件，以找到最高章节号（例如 ch12）。
  • 读取 glossary.md、patterns.md 和 cheatsheet.md 以了解已经索引了哪些术语和框架。

2. 匹配内容 & 识别“修订”与“新增”

分析 <tempdir>/book_skill_work/full_text.txt 中的新提取文本，以确定新内容是否代表：

  • 现有章节的更新/修订：如果新内容的某部分直接更新或扩展了现有章节的主题，请读取现有章节文件，将新细节合并进去，并重写该文件。
  • 全新增加的内容：如果内容引入了新章节、论文或独立部分，请在 chapters/ 下创建新章节摘要文件。从现有最高章节号之后开始编号（例如，如果现有章节到 ch12 结束，则创建 ch13-*.md、ch14-*.md 等）。

3. 生成或更新章节摘要文件

对于每个新增或修订的章节：

  • 读取提取出的新文本的相应部分。
  • 遵循 Step 7 中的格式指南构建摘要。
  • 在 $SKILLS_HOME/<skill_name>/chapters/ 中写入/更新文件。

4. 合并支持文件

  • 合并 glossary.md:

  • 读取现有的 $SKILLS_HOME/<skill_name>/glossary.md。

  • 根据 Step 8 的指南从新内容中提取所有新术语及其定义。

  • 组合并按字母(拼音)顺序排列现有和新术语。

  • 如果术语已存在，将新章节/来源参考附加到其后（例如 **术语** — 定义 (第 4 章, 第 13 章)）。

  • 用完全合并且排序的列表重写 glossary.md。

  • 合并 patterns.md:

  • 读取现有的 $SKILLS_HOME/<skill_name>/patterns.md。

  • 从新内容中提取任何新颖的技术、算法或模式。

  • 附加新模式，确保格式一致，并保持总长度简洁（2,500 tokens 以内）。

  • 合并 cheatsheet.md:

  • 读取现有的 $SKILLS_HOME/<skill_name>/cheatsheet.md。

  • 提取新的对比规则、决策表或参数指南。

  • 将它们干净利落地整合到现有的速查表结构中。

5. 重新生成主 SKILL.md

更新主技能文件 $SKILLS_HOME/<skill_name>/SKILL.md：

  • 元数据 (Metadata)：增加章节数，更新估计的页数，并在合适的情况下添加新的源名称。将 Generated (生成时间) 更新为当前日期。
  • 核心框架 (Core Frameworks)：将新内容中影响最大的心智模型或原则折叠进去（确保整体文件保持在 4,000 tokens 以内）。
  • 章节索引 (Chapter Index)：将新章节附加到索引表中，并链接到新创建的文件。
  • 主题索引 (Topic Index)：按字母顺序合并新主题。如果现有主题也在新章节中涉及，将新章节链接附加到其所在行（例如 - **主题** → ch05, ch13）。

6. 扫描、清理并报告

文件成功写入并合并后，运行 Step 9.5，然后进入 Step 10 执行清理，并打印一份自定义的更新报告，总结新添加的章节、合并的术语表词条以及更新的索引。

质量规则 (Quality Rules)

  1. 提取结构，不是写读后感 — 捕捉命名的框架、精确的表述、反模式；而不是写“本章讲了什么”的流水账。
  2. 保留作者的精确性 — “5问法” ≠ “多问几次为什么”；保留精准命名。
  3. 密度胜过完整性 — 1,000 tokens 的高密度精华胜过 10,000 tokens 的摘录。
  4. 从业者语调 — 写“当 Y 发生时，执行 X”，而不是写“书里解释了 X”。
  5. 前置 SKILL.md — Agent 会从尾部截断长达 5,000 tokens 以上的上下文；最关键的内容必须放在最前面。
  6. 章节文件是按需加载的 — 在被明确加载(Load/Read)之前，它们不会计入技能的 Token 预算。
  7. 永远不要原文复制整段书籍文本 — 始终要提炼、总结、提取有价值的信号。
  8. 主题索引至关重要 — 它是 Agent 准确导航并找到合适章节文件的唯一地图。
posted @ 2026-08-02 08:37  立体风  阅读(42)  评论(0)    收藏  举报