从今年开始我的一个明显感受是AI 编程助手的能力上限已经从“模型够不够聪明”转移到了“上下文够不够装”。模型再强如果你想把一本 400 页的团队规范、一个 50 万 token 的技术手册、或者一大堆框架文档交给它照样会当场撞墙。要么上下文爆掉要么模型开始“忘了”更早的指令要么回答越来越漂。于是很多人开始折腾 RAG搭向量库、配 embedding、写检索逻辑、调 chunk 大小。这套东西能做但太重了而且对于“一本书”这种结构化文档来说往往是大炮打蚊子。最近我在关注一个叫book-to-skill的思路它解决的问题非常直接把一本资料书转换成一组“按需技能”平时不占上下文用到哪个部分就只加载哪个部分。项目介绍里有一个很吸引眼球的数字一本书省 51 倍上下文。今天这篇文章我想认真拆一下这个数字是怎么来的它到底解决了什么问题以及你自己怎么照着把一份长文档变成一组可用的 Skill。这篇文章不是简单的项目搬运我会把背后的上下文工程原理、Skill 格式、拆书流程、验证方法以及最容易踩的坑都讲清楚。1. 上下文焦虑模型能力再强喂不进去也是白搭先从一个很常见的场景说起。假设你所在团队有一套完整的《前端开发规范手册》包含代码风格、组件设计、接口约定、发布流程大概 300 页。你想让 AI 编程助手在写代码时严格遵循这套规范怎么做最朴素的办法是把手册全文直接粘贴到系统提示词里。结果很快就出现了手册转成纯文本后可能有 20 万到 50 万 token直接超过了很多模型的上下文窗口上限。就算你的模型支持 100 万 token把那么多内容一次性塞进去推理速度和成本都会显著上升。更关键的是大量不相关的规则会干扰模型对当前任务的理解。你在写一个按钮组件时模型却同时“记着”发布流程和接口约定反而更容易出现注意力分散。这就是我在文章开头说的上下文不是越大越好而是“够用、精准、按需”才是最好。很多人把长文档交给 AI 的办法是叠上下文窗口。2024 年到 2025 年各家模型厂商疯狂卷上下文长度从 128K 到 200K 再到 1M。但窗口大了不等于效果就好。业界公认的观察是当上下文接近上限时模型对中间部分的关注度会明显下降尤其是对早期指令的遵循能力会退化。你塞进去 50 万 token模型真正“高效利用”的可能只有一小部分。AI 编程助手还有一个更现实的问题新开会话就丢失上下文记忆。你上一个会话里交代的“请遵循某某规范”下一个会话它完全不记得。这种情况下如果规范文档不能“按需加载”你就得每次手动重新粘贴非常痛苦。所以问题不是“模型上下文不够大”而是“我们管理上下文的方式太原始”。2. book-to-skill 到底是什么从“全文携带”到“按需调用”book-to-skill 的核心思路一句话就能说清楚不要试图把整本书塞进上下文而是把书拆成一个个“技能包”让 AI 在需要的时候自己去取。这里需要先理解一个概念Skill技能。在 Claude Code、Claude Desktop 等支持 Skills 功能的 AI 助手中一个 Skill 通常是一个独立目录里面有一个SKILL.md文件以及可选的脚本、模板、参考文档。它定义了一个“AI 可以按需调用的能力”。比如你可以做一个json-to-pydantic技能让 AI 在遇到 JSON 转 Pydantic 模型的任务时自动加载对应的转换规则和示例代码。Skill 的调用机制通常是这样AI 助手启动时只会扫描所有 Skill 的元信息名称和描述不会把 Skill 的完整内容加载进上下文。当用户提出的任务与某个 Skill 的描述匹配时AI 才去读取这个 Skill 目录下的SKILL.md和相关文件。这就是“按需加载”的关键。book-to-skill 做的就是把这个机制套用在“一本书”上。假设你有一本关于 Kubernetes 排障的手册全书 30 万字。传统方式是全文塞进上下文。book-to-skill 的思路是把书按章节或主题拆成多个小单元比如“Pod 启动失败排查”“Service 无法访问排查”“存储卷挂载问题”等。为每个单元生成一个独立的 Skill包含该单元的核心规则、命令、示例和注意事项。把这些 Skill 统一安装到 AI 助手的 skills 目录下。之后你问助手“我的 Pod 一直 CrashLoopBackOff 怎么办”它就会自动匹配到“Pod 启动失败排查”这个 Skill只加载那一个章节的内容而不是把整本书都读一遍。所谓“省 51 倍上下文”本质就是对比两条路径的 token 消耗路径 A把整本书全文放进上下文。路径 B只加载与当前问题相关的 Skill 内容。如果一本书全文是 50 万 token而一次按需加载只需要 1 万 token那确实就是 50 倍左右的差距。51 倍这个数字应该是基于某个具体书籍和拆分策略算出来的不同场景下结果会不同。但方向是确定的把“常驻上下文”变成“临时调用”省下来的空间是数量级的。这里我想强调一个容易误会的点book-to-skill 不是万能的它不是要替代 RAG。如果一本书的章节之间关联极强、任何问题都可能涉及全书任意位置的信息那按需加载的命中率就会下降。但对于大多数技术手册、操作指南、团队规范这类结构清晰的文档按需加载的效果非常明显。3. Skill 格式与按需加载机制详解要真正上手 book-to-skill得先搞清楚 Skill 是怎么组织的。3.1 SKILL.md 的基本结构一个最小可用的 Skill 目录结构如下k8s-pod-startup-issue/ ├── SKILL.md └── references/ └── pod-startup-checklist.mdSKILL.md是技能的核心文件前面的 YAML frontmatter 描述技能的名词和触发条件正文部分写具体的操作步骤和规则。一个示例--- name: k8s-pod-startup-issue description: 当用户遇到 Kubernetes Pod 启动失败、CrashLoopBackOff、ImagePullBackOff、Pending 等问题时使用本技能进行排查。 --- # Kubernetes Pod 启动失败排查 ## 排查步骤 1. 先查看 Pod 状态和事件 bash kubectl describe pod pod-name -n namespace如果发现 CrashLoopBackOff查看容器日志kubectl logs pod-name -n namespace --tail200 --previous如果发现 ImagePullBackOff检查镜像名和 tag 是否正确。检查私有仓库拉取凭证是否配置。用kubectl get events --sort-by.lastTimestamp查看具体错误码。常见错误码错误码含义处理建议ErrImagePull镜像拉取失败检查凭证和网络CrashLoopBackOff容器启动后立即退出查看应用日志检查启动命令注意事项不要直接重启 Pod先定位根因。修改 Deployment 后通过滚动更新生效。这里的关键点是 description 字段。AI 助手启动时会扫描 skills 目录下所有 SKILL.md 的 name 和 description建立一个索引。当用户提问时AI 通过语义匹配决定是否加载某个技能。**所以 description 写得好不好直接决定了技能能不能被正确触发。** ### 3.2 为什么这种方式能省上下文 我把三种方案的上下文消耗方式做一个对比 | 方案 | 上下文消耗 | 维护成本 | 适用场景 | | --- | --- | --- | --- | | 全文塞入提示词 | 全书 token 常驻 | 低但效果差 | 短文档几万字以内 | | RAG 向量检索 | 分块检索按相关度取回 | 高需要向量库和 embedding | 数据量大、内容分散、强关联检索 | | Skill 按需加载 | 仅加载匹配技能的内容 | 中需要把书拆成独立主题 | 结构化手册、规范、操作指南 | 从表里可以看出来Skill 按需加载其实处在“全文塞入”和“RAG”之间。它比全文塞入更聪明比 RAG 更轻量。**它的核心优势在于不需要搭建任何额外的检索设施只需要利用 AI 助手本身的“先扫描描述、再按需加载”机制。** ### 3.3 “上下文工程”视角下的 book-to-skill “上下文工程”最近是个热词很多人把它理解成“怎么把提示词写得更长更详细”。实际上上下文工程真正研究的是**如何在有限的上下文窗口里让模型用最少的 token 拿到最关键的信息。** 从上下文工程的角度看book-to-skill 做了三件正确的事 1. **减少常驻 token**技能描述只有几百 token远小于完整文档。 2. **提高信息密度**加载进来的章节内容是和当前任务强相关的。 3. **实现跨对话复用**技能安装一次所有新会话都能用不需要重新粘贴。 这也是它和“AI 编程助手新开会话丢失上下文记忆”这个痛点的关系。技能不是聊天记录不会因为新开会话而消失。它等同于把“知识”从临时会话记忆变成了长期可复用的资产。 ## 4. 环境准备与前置条件 下面进入实操部分。我们需要准备以下环境和材料 ### 4.1 基础环境 - Python 3.9 及以上版本用于运行文档拆分和 Skill 生成脚本。 - 一个支持 Skills 机制的 AI 助手比如 Claude Code、Claude Desktop或者其他兼容 Anthropic Agent Skills 规范的工具。 - 一本或多本需要转换的电子书/技术文档。**建议使用 Markdown 格式作为中间格式**因为后续拆分和处理最方便。 ### 4.2 目录规划 我们约定一个项目目录结构避免后续操作混乱book-to-skill-demo/ ├── input/ │ └── k8s-troubleshooting.md # 原始书籍 Markdown ├── scripts/ │ ├── split_book.py # 按标题拆分章节 │ └── generate_skill.py # 为章节生成 SKILL.md ├── output/ │ └── skills/ # 生成的技能目录 │ ├── k8s-pod-startup/ │ │ └── SKILL.md │ ├── k8s-network/ │ │ └── SKILL.md │ └── ... └── config.yaml # 拆分参数配置### 4.3 关于原始文档格式的说明 如果你的书是 PDF、ePub 或 Word 格式建议先转成 Markdown。这一步可以用现成的工具完成比如 Pandoc bash # 将 PDF 转为 Markdown需要先安装 pandoc pandoc input/k8s-troubleshooting.pdf -t gfm -o input/k8s-troubleshooting.md # 将 ePub 转为 Markdown pandoc input/k8s-troubleshooting.epub -t gfm -o input/k8s-troubleshooting.md这里要提醒一下PDF 转换后的 Markdown 质量往往不太理想尤其是代码块、表格、多级标题这些元素容易错乱。建议转换后先人工检查一遍把标题层级理顺。因为后续的“拆书”逻辑严重依赖 Markdown 的标题结构。如果项目输入材料没有明确指定某个工具版本就不需要纠结具体版本号以你本机实际安装为准。本文重点演示的是通用思路不是某个工具的固定版本操作手册。5. 核心流程拆解从一本书到一组 Skill把一本书变成一组 Skill核心流程可以拆成五步。5.1 第一步预处理原始文档这一步的目标很明确得到一份结构清晰、标题层级完整、代码块正确的 Markdown 文件。具体操作检查一级标题、二级标题是否准确表达章节关系。去掉无关的目录页、前言、致谢等部分这些内容不太可能成为故障排查时的按需技能。确保代码块被正确标注语言类型。为什么这一步重要因为后续的自动拆分脚本默认就是按 Markdown 标题层级来切分内容的。如果标题乱切分出来的块就会乱生成的 Skill 边界也会很模糊。5.2 第二步按主题拆分成块拆分的核心原则是每个块只讲一个主题块内信息自包含。一本书的章节划分通常并不完全等于“主题划分”。比如《Kubernetes 故障排查手册》的第三章可能叫“Pod 生命周期问题”但这一章里既有调度问题又有镜像问题还有健康检查问题。如果直接把整章做成一个 Skill那么这个 Skill 的内容还是太大而且触发条件不聚焦。更合理的做法是在章内部继续按“主题”切块。切块时需要注意每个块的大小建议控制在 2000 到 8000 个 token 之间。太小则信息不完整太大则失去了按需加载的意义。每个块必须有清晰的“能力边界”。比如“排查 CrashLoopBackOff”和“排查 ImagePullBackOff”就是两个不同的主题不要混在一起。每个块要能被一个自然语言问题触发。5.3 第三步为每个块生成 SKILL.md生成了内容块之后需要为每个块写一个SKILL.md。这一步最关键的部分是description 的撰写。描述写得好不好直接决定 AI 助手能不能在正确时机加载这个技能。好的 description 应该包含技能适用的具体任务场景。触发该技能的关键词。明确排除的场景避免误触发。举例description: 当用户遇到 Kubernetes Pod 启动失败、崩溃重启、镜像拉取失败、调度不成功等问题时使用本技能。不适用于 Service 网络访问问题。有一个细节值得注意Skill 的触发条件很大程度上依赖底层模型对 description 的语义理解所以描述要“像用户会问的问题”而不是“像目录名”。比如目录名是“pod-lifecycle”但用户会问“我的 Pod 一直重启怎么办”description 里最好能包含“重启”“崩溃”“CrashLoopBackOff”这类用户真实会用的词。5.4 第四步安装到 AI 助手的 skills 目录不同 AI 助手的 Skill 安装方式不完全相同但大体上都是把 Skill 目录放到指定的 skills 文件夹下。以 Claude Code 为例通常在项目根目录或用户配置目录下存在一个.claude/skills/目录.claude/skills/ ├── k8s-pod-startup/ │ └── SKILL.md ├── k8s-network-debug/ │ └── SKILL.md把生成的 Skill 目录复制进去重启 AI 助手或者重新加载会话就算安装完成。5.5 第五步验证调用安装完成后用真实问题去触发。比如问我的 Pod 一直 CrashLoopBackOff怎么排查然后观察 AI 助手是否加载了k8s-pod-startup这个技能。很多助手会在回复中提示“正在使用技能”或“已加载技能 xxx”。如果 AI 没有触发技能说明 description 写得不到位需要调整。6. 完整示例拆书、生成 Skill、估算上下文用量下面我用一个具体的示例来演示。示例使用 Python 编写分为三个脚本拆书脚本、生成 Skill 脚本、上下文用量估算脚本。6.1 示例一按 Markdown 标题拆书先看拆分脚本。这个脚本的作用是把一本 Markdown 格式的书按二级标题##切分成多个独立文件。# 文件路径scripts/split_book.py import re import os from pathlib import Path INPUT_FILE Path(input/k8s-troubleshooting.md) OUTPUT_DIR Path(output/chunks) OUTPUT_DIR.mkdir(parentsTrue, exist_okTrue) def split_book_by_h2(md_text: str): 按 ## 二级标题将 Markdown 拆分为多个块。 lines md_text.splitlines() chunks [] current_chunk [] current_title None current_heading_level 0 # 记录当前标题级别 for line in lines: # 匹配 Markdown 标题最多支持到 ## 级别 m re.match(r^(#{1,2})\s(.*), line) if m: level len(m.group(1)) title m.group(2).strip() # 遇到二级标题开启一个新 chunk if level 2: if current_chunk: chunks.append((current_title, \n.join(current_chunk))) current_title title current_chunk [line] current_heading_level level else: # 一级标题属于文档总标题不单独成 chunk current_chunk.append(line) else: current_chunk.append(line) if current_chunk: chunks.append((current_title, \n.join(current_chunk))) return chunks def main(): md_text INPUT_FILE.read_text(encodingutf-8) chunks split_book_by_h2(md_text) print(f共拆分出 {len(chunks)} 个章节块) for index, (title, content) in enumerate(chunks, start1): # 用章节序号 标题生成文件名保证排序稳定 safe_title re.sub(r[^\w\u4e00-\u9fa5], _, title)[:30] filename f{index:03d}_{safe_title}.md filepath OUTPUT_DIR / filename filepath.write_text(content, encodingutf-8) print(f[{index}] {title} - {filepath}) if __name__ __main__: main()运行方式python scripts/split_book.py这个脚本的核心逻辑是逐行扫描 Markdown遇到##级别的标题就开启一个新的 chunk。拆完后每个 chunk 独立存储为一个文件。特别说明这个脚本是演示用只处理了##级别。如果书有多级嵌套你需要根据自己的文档结构调整脚本比如按###拆或者先按##拆再按###细分。6.2 示例二为每个章节生成 SKILL.md接下来是生成 Skill 的脚本。它读取拆分后的章节文件自动生成一个包含SKILL.md的 Skill 目录。# 文件路径scripts/generate_skill.py import os import re from pathlib import Path CHUNKS_DIR Path(output/chunks) SKILLS_DIR Path(output/skills) SKILLS_DIR.mkdir(parentsTrue, exist_okTrue) def extract_topic_from_filename(filename: str) - str: 从文件名中提取主题关键字用于生成 description。 # 去掉序号和后缀例如 001_Pod启动失败排查.md - Pod启动失败排查 name re.sub(r^\d_, , filename.replace(.md, )) return name def generate_skill_for_chunk(filepath: Path) - str: 为单个章节文件生成 Skill 目录。 content filepath.read_text(encodingutf-8) topic extract_topic_from_filename(filepath.name) # 取章节内容的前 300 字作为 SKILL.md 的正文摘要 # 这里在生产环境中应该进一步提炼而不是简单截取 body_preview content[:300] skill_name re.sub(r[^\w\u4e00-\u9fa5], -, topic).strip(-) skill_dir SKILLS_DIR / skill_name skill_dir.mkdir(parentsTrue, exist_okTrue) sk_md f--- name: {skill_name} description: 当用户遇到与“{topic}”相关的问题时使用本技能。包括但不限于以下场景{topic}相关的排查步骤、常见错误、解决方案。不适用于其他无关主题。 --- # {topic} ## 使用说明 当用户的问题命中本技能描述时按以下方式回答 1. 阅读本文件中的排查步骤。 2. 结合具体场景按步骤引导用户排查。 3. 如果步骤中涉及命令在回答中给出可复制命令。 ## 内容 {body_preview} skill_md_path skill_dir / SKILL.md skill_md_path.write_text(sk_md, encodingutf-8) return str(skill_md_path) def main(): chunk_files sorted(CHUNKS_DIR.glob(*.md)) if not chunk_files: print(未找到章节文件请先运行 split_book.py) return for chunk_file in chunk_files: path generate_skill_for_chunk(chunk_file) print(f生成技能: {path}) print(f\n共生成 {len(chunk_files)} 个技能到 {SKILLS_DIR}) if __name__ __main__: main()运行方式python scripts/generate_skill.py这个脚本生成的SKILL.md只是一个演示。它把章节内容的前 300 字直接作为正文这在真实场景是不够的。更好的做法是人工为每个章节提炼核心排查步骤、命令、注意事项写入 SKILL.md 的正文同时把原始章节完整内容放到 references 目录作为参考附件。这里体现了 Skill 设计的一个重要思想SKILL.md里放的是“如何执行这个技能”而原始资料可以放到references/供需要时读取。这样平时上下文中只有精简版步骤只有 AI 判断需要更多细节时才去读参考文件。6.3 示例三估算上下文用量最后是估算脚本。通过对比“整本书 token 数”和“所有 Skill 描述 token 数”直观看出省了多少上下文。# 文件路径scripts/estimate_tokens.py import re from pathlib import Path INPUT_FILE Path(input/k8s-troubleshooting.md) SKILLS_DIR Path(output/skills) def count_tokens_rough(text: str) - int: 粗略估算 token 数。中文场景下一个字约等于 1 个 token。 # 这里用字符数作为简化估算更准确的估算需要接入分词器 return len(text) def main(): book_text INPUT_FILE.read_text(encodingutf-8) book_tokens count_tokens_rough(book_text) skill_desc_tokens 0 skill_full_tokens 0 for skill_md in SKILLS_DIR.rglob(SKILL.md): content skill_md.read_text(encodingutf-8) skill_full_tokens count_tokens_rough(content) # 只统计 description 行作为常驻上下文的近似 m re.search(r^description:\s*(.*)$, content, re.MULTILINE) if m: skill_desc_tokens count_tokens_rough(m.group(1)) print(f整本书估算 token 数: {book_tokens}) print(f所有技能完整内容 token 数: {skill_full_tokens}) print(f所有技能 description 常驻 token 数: {skill_desc_tokens}) if skill_desc_tokens: print(f按需加载 vs 全文塞入 的节省倍数(粗略): {book_tokens / skill_desc_tokens:.1f} 倍) if __name__ __main__: main()运行方式python scripts/estimate_tokens.py这个脚本最重要的输出是最后一行“节省倍数”。如果所有 Skill 的 description 加起来只有几百 token而整本书有几十万 token那两者的差距就是几十倍。这也就是项目宣称“省 51 倍上下文”的逻辑基础。需要说明的是这里的 token 估算用了简单的字符数近似真实的 token 数计算需要接入具体模型的分词器。但对于对比“全文 vs 按需”的数量级差异这个简单估算已经足够说明问题。6.4 示例四在 Claude Code 中的实际使用生成 Skill 之后如何在 AI 助手中生效下面以 Claude Code 为例演示。把生成的 Skill 目录放到项目的.claude/skills/下mkdir -p .claude/skills cp -r output/skills/* .claude/skills/然后启动 Claude Codeclaude在会话中输入我的 Deployment 滚动更新一直卡住Pod 起不来请帮我排查。如果 Skill 的 description 里有“滚动更新”“Pod 起不来”“排查”等关键词Claude Code 会自动匹配到对应的技能并加载。当然不同 AI 助手的 Skill 目录路径和加载机制可能不同具体以你使用的工具官方文档为准。核心原理是一致的技能描述常驻索引技能正文按需加载。7. 运行结果与效果验证完成上述示例之后你可以通过以下方式验证结果。7.1 查看生成的目录结构tree output/skills预期输出类似output/skills/ ├── Pod启动失败排查/ │ └── SKILL.md ├── Service网络问题排查/ │ └── SKILL.md └── 滚动更新卡住处理/ └── SKILL.md7.2 查看估算结果运行estimate_tokens.py后你会看到类似这样的输出整本书估算 token 数: 320000 所有技能完整内容 token 数: 45000 所有技能 description 常驻 token 数: 2000 按需加载 vs 全文塞入 的节省倍数(粗略): 160.0 倍这里的 160 倍只是一个举例。实际倍数取决于你的书有多大、拆分粒度有多细、description 写得多精简。核心关注点不是数字本身而是数量级上的差异。7.3 在 AI 助手中验证技能触发验证技能是否真正生效有几种方法在对话中明确提问观察助手的回复是否出现“正在使用技能”或类似提示。用调试模式很多 AI 助手支持显示加载的上下文和技能名称。故意问一个明显不相关的问题确认它不会误加载技能。如果技能没有触发优先检查 description。很多时候不是 Skill 目录放错了而是 description 没有覆盖用户真实的问法。比如你写的是“Kubernetes Pod 启动失败”但用户会问“容器一直重启怎么办”这两句话语义相近但字面不同AI 能否关联上取决于底层模型的能力。稳妥的做法是在 description 里把用户可能用的各种问法都写进去。8. 常见问题与排查思路在实际把玩这个流程的过程中最容易遇到下面这些问题问题现象可能原因排查方式解决方案生成技能数量过少原始 Markdown 标题层级不规整##太少查看原始文档标题结构预处理文档统一标题层级技能互相重叠触发混乱拆分粒度太大一个 chunk 包含多个主题查看 chunk 文件内容是否聚焦细化拆分逻辑按###拆或人工调整边界AI 助手不加载技能description 写得不够贴近用户问法在助手调试模式中查看技能索引重写 description覆盖更多用户问法技能加载了但回答质量差SKILL.md 正文信息不足查看 SKILL.md 内容增加步骤、命令、示例、常见错误上下文仍然超限一个 Skill 内 references 太大检查 references 文件大小进一步拆分或只保留关键内容新会话技能丢失技能目录放错位置检查 skills 目录路径放在项目根目录或用户级全局目录PDF 转 Markdown 后格式混乱PDF 本身无结构化信息检查转换后的代码块和表格手动修复或用高质量转换工具我特别想展开说一下“技能互相重叠”这个问题。举例如果有个 chunk 叫“Kubernetes 基础概念”另一个 chunk 叫“Pod 生命周期”用户问“Pod 一直重启怎么办”两个技能都可能被触发。这种情况下AI 可能加载了“基础概念”这个包含大量百科式内容的技能占用上下文却没有提供有用的排查步骤。解决方案有两个方向拆分时尽量让主题互斥。比如“Kubernetes 基础概念”这种通识性内容就不太适合做成按需技能因为它没有明确的“触发任务边界”。在 description 中明确排除边界。比如“Pod 生命周期”技能的描述里写“不适用于集群安装、网络配置等场景”。很多人第一次做 Skill 拆分时意识不到 description 的边界声明有多重要。它不仅能提高技能触发的准确率还能避免多个技能同时加载导致上下文浪费。9. 最佳实践与工程建议经过流程拆解和问题排查下面是我认为做这件事最值得遵循的几条工程建议。9.1 先整理文档再拆技能拆书之前花半小时整理 Markdown 结构比拆完再返工要高效得多。整理的核心是标题层级。一本书如果原来的目录结构足够清晰二级标题基本就等于章节主题拆出来的 Skill 边界也会比较干净。9.2 控制技能的粒度一个技能的正文建议控制在 2000 到 8000 token。太小的技能没有独立的必要会提高索引噪音太大的技能失去了按需加载的优势。判断粒度是否合适有一个简单标准拿这个技能的名字问自己一个用户问题能否在 10 秒内判断“该不该用这个技能”。如果能粒度基本合适如果需要看完整描述才能判断说明粒度太粗或边界不清。9.3 description 是重中之重我在这篇文章里已经很多次提到 description因为它真的是整个机制的命门。写 description 时建议覆盖三个维度技能负责的任务类型比如“排查”“转换”“生成”。技能适用的领域关键词比如“Kubernetes”“Pod”“CrashLoopBackOff”。明确的排除条件比如“不适用于网络问题”。9.4 用 references 承载细节SKILL.md 保持精简SKILL.md 是技能的执行框架references 目录放原始参考资料的细节。这样两者各司其职框架常驻AI 知道这个技能怎么用。细节按需只有需要时才去 references 里找详细资料。9.5 持续迭代技能库书不是静态的技术会更新规范会调整。技能库也需要维护。建议在每次使用的过程中把“AI 回答明显不准确”的场景记录下来反哺到对应的 SKILL.md 中。经过几轮迭代技能库的质量会有明显提升。9.6 明确不适合的场景不是所有资料都适合转成 Skill。如果你的一本书是小说、散文或者主题高度连贯、无法拆分不适合。如果你的问题场景可能涉及全书任意位置按需加载的效果不好RAG 可能更合适。如果你的文档只有几千字直接全文塞入反而更简单没必要做技能化改造。这个方案最适合的是“结构清晰、按主题调用、场景明确”的技术手册和团队规范。10. 总结与后续实践方向book-to-skill 的核心价值不是那个“51 倍”的营销数字而是它背后的上下文工程思路在 AI 助手时代知识不应该以“整本书”的形态常驻上下文而应该以“按需技能”的形态被随时调用。它把长期困扰程序员的长文档使用问题从“模型上下文不够大”转化为“如何设计一套高效的知识调用系统”。这对任何需要把大量规范、手册、内部文档沉淀给 AI 使用的团队都是一个值得认真尝试的方向。如果你准备动手实践我的建议是选一本你工作里最常需要查阅的技术手册。先转成 Markdown人工检查标题结构。用脚本拆块再人工调整每个块的主题边界。为每个块撰写 SKILL.md重点打磨 description。安装到你的 AI 编程助手中用真实问题验证触发效果。根据使用反馈持续迭代技能内容。如果整套流程跑通了你大概率会发现同样的助手在接入技能库之后回答质量和上下文消耗都有了质的改变。这种改变比单纯换一个更大上下文的模型来得更实际也更可持续。
用book-to-skill把技术手册变成按需技能，节省51倍上下文
从今年开始我的一个明显感受是AI 编程助手的能力上限已经从“模型够不够聪明”转移到了“上下文够不够装”。模型再强如果你想把一本 400 页的团队规范、一个 50 万 token 的技术手册、或者一大堆框架文档交给它照样会当场撞墙。要么上下文爆掉要么模型开始“忘了”更早的指令要么回答越来越漂。于是很多人开始折腾 RAG搭向量库、配 embedding、写检索逻辑、调 chunk 大小。这套东西能做但太重了而且对于“一本书”这种结构化文档来说往往是大炮打蚊子。最近我在关注一个叫book-to-skill的思路它解决的问题非常直接把一本资料书转换成一组“按需技能”平时不占上下文用到哪个部分就只加载哪个部分。项目介绍里有一个很吸引眼球的数字一本书省 51 倍上下文。今天这篇文章我想认真拆一下这个数字是怎么来的它到底解决了什么问题以及你自己怎么照着把一份长文档变成一组可用的 Skill。这篇文章不是简单的项目搬运我会把背后的上下文工程原理、Skill 格式、拆书流程、验证方法以及最容易踩的坑都讲清楚。1. 上下文焦虑模型能力再强喂不进去也是白搭先从一个很常见的场景说起。假设你所在团队有一套完整的《前端开发规范手册》包含代码风格、组件设计、接口约定、发布流程大概 300 页。你想让 AI 编程助手在写代码时严格遵循这套规范怎么做最朴素的办法是把手册全文直接粘贴到系统提示词里。结果很快就出现了手册转成纯文本后可能有 20 万到 50 万 token直接超过了很多模型的上下文窗口上限。就算你的模型支持 100 万 token把那么多内容一次性塞进去推理速度和成本都会显著上升。更关键的是大量不相关的规则会干扰模型对当前任务的理解。你在写一个按钮组件时模型却同时“记着”发布流程和接口约定反而更容易出现注意力分散。这就是我在文章开头说的上下文不是越大越好而是“够用、精准、按需”才是最好。很多人把长文档交给 AI 的办法是叠上下文窗口。2024 年到 2025 年各家模型厂商疯狂卷上下文长度从 128K 到 200K 再到 1M。但窗口大了不等于效果就好。业界公认的观察是当上下文接近上限时模型对中间部分的关注度会明显下降尤其是对早期指令的遵循能力会退化。你塞进去 50 万 token模型真正“高效利用”的可能只有一小部分。AI 编程助手还有一个更现实的问题新开会话就丢失上下文记忆。你上一个会话里交代的“请遵循某某规范”下一个会话它完全不记得。这种情况下如果规范文档不能“按需加载”你就得每次手动重新粘贴非常痛苦。所以问题不是“模型上下文不够大”而是“我们管理上下文的方式太原始”。2. book-to-skill 到底是什么从“全文携带”到“按需调用”book-to-skill 的核心思路一句话就能说清楚不要试图把整本书塞进上下文而是把书拆成一个个“技能包”让 AI 在需要的时候自己去取。这里需要先理解一个概念Skill技能。在 Claude Code、Claude Desktop 等支持 Skills 功能的 AI 助手中一个 Skill 通常是一个独立目录里面有一个SKILL.md文件以及可选的脚本、模板、参考文档。它定义了一个“AI 可以按需调用的能力”。比如你可以做一个json-to-pydantic技能让 AI 在遇到 JSON 转 Pydantic 模型的任务时自动加载对应的转换规则和示例代码。Skill 的调用机制通常是这样AI 助手启动时只会扫描所有 Skill 的元信息名称和描述不会把 Skill 的完整内容加载进上下文。当用户提出的任务与某个 Skill 的描述匹配时AI 才去读取这个 Skill 目录下的SKILL.md和相关文件。这就是“按需加载”的关键。book-to-skill 做的就是把这个机制套用在“一本书”上。假设你有一本关于 Kubernetes 排障的手册全书 30 万字。传统方式是全文塞进上下文。book-to-skill 的思路是把书按章节或主题拆成多个小单元比如“Pod 启动失败排查”“Service 无法访问排查”“存储卷挂载问题”等。为每个单元生成一个独立的 Skill包含该单元的核心规则、命令、示例和注意事项。把这些 Skill 统一安装到 AI 助手的 skills 目录下。之后你问助手“我的 Pod 一直 CrashLoopBackOff 怎么办”它就会自动匹配到“Pod 启动失败排查”这个 Skill只加载那一个章节的内容而不是把整本书都读一遍。所谓“省 51 倍上下文”本质就是对比两条路径的 token 消耗路径 A把整本书全文放进上下文。路径 B只加载与当前问题相关的 Skill 内容。如果一本书全文是 50 万 token而一次按需加载只需要 1 万 token那确实就是 50 倍左右的差距。51 倍这个数字应该是基于某个具体书籍和拆分策略算出来的不同场景下结果会不同。但方向是确定的把“常驻上下文”变成“临时调用”省下来的空间是数量级的。这里我想强调一个容易误会的点book-to-skill 不是万能的它不是要替代 RAG。如果一本书的章节之间关联极强、任何问题都可能涉及全书任意位置的信息那按需加载的命中率就会下降。但对于大多数技术手册、操作指南、团队规范这类结构清晰的文档按需加载的效果非常明显。3. Skill 格式与按需加载机制详解要真正上手 book-to-skill得先搞清楚 Skill 是怎么组织的。3.1 SKILL.md 的基本结构一个最小可用的 Skill 目录结构如下k8s-pod-startup-issue/ ├── SKILL.md └── references/ └── pod-startup-checklist.mdSKILL.md是技能的核心文件前面的 YAML frontmatter 描述技能的名词和触发条件正文部分写具体的操作步骤和规则。一个示例--- name: k8s-pod-startup-issue description: 当用户遇到 Kubernetes Pod 启动失败、CrashLoopBackOff、ImagePullBackOff、Pending 等问题时使用本技能进行排查。 --- # Kubernetes Pod 启动失败排查 ## 排查步骤 1. 先查看 Pod 状态和事件 bash kubectl describe pod pod-name -n namespace如果发现 CrashLoopBackOff查看容器日志kubectl logs pod-name -n namespace --tail200 --previous如果发现 ImagePullBackOff检查镜像名和 tag 是否正确。检查私有仓库拉取凭证是否配置。用kubectl get events --sort-by.lastTimestamp查看具体错误码。常见错误码错误码含义处理建议ErrImagePull镜像拉取失败检查凭证和网络CrashLoopBackOff容器启动后立即退出查看应用日志检查启动命令注意事项不要直接重启 Pod先定位根因。修改 Deployment 后通过滚动更新生效。这里的关键点是 description 字段。AI 助手启动时会扫描 skills 目录下所有 SKILL.md 的 name 和 description建立一个索引。当用户提问时AI 通过语义匹配决定是否加载某个技能。**所以 description 写得好不好直接决定了技能能不能被正确触发。** ### 3.2 为什么这种方式能省上下文 我把三种方案的上下文消耗方式做一个对比 | 方案 | 上下文消耗 | 维护成本 | 适用场景 | | --- | --- | --- | --- | | 全文塞入提示词 | 全书 token 常驻 | 低但效果差 | 短文档几万字以内 | | RAG 向量检索 | 分块检索按相关度取回 | 高需要向量库和 embedding | 数据量大、内容分散、强关联检索 | | Skill 按需加载 | 仅加载匹配技能的内容 | 中需要把书拆成独立主题 | 结构化手册、规范、操作指南 | 从表里可以看出来Skill 按需加载其实处在“全文塞入”和“RAG”之间。它比全文塞入更聪明比 RAG 更轻量。**它的核心优势在于不需要搭建任何额外的检索设施只需要利用 AI 助手本身的“先扫描描述、再按需加载”机制。** ### 3.3 “上下文工程”视角下的 book-to-skill “上下文工程”最近是个热词很多人把它理解成“怎么把提示词写得更长更详细”。实际上上下文工程真正研究的是**如何在有限的上下文窗口里让模型用最少的 token 拿到最关键的信息。** 从上下文工程的角度看book-to-skill 做了三件正确的事 1. **减少常驻 token**技能描述只有几百 token远小于完整文档。 2. **提高信息密度**加载进来的章节内容是和当前任务强相关的。 3. **实现跨对话复用**技能安装一次所有新会话都能用不需要重新粘贴。 这也是它和“AI 编程助手新开会话丢失上下文记忆”这个痛点的关系。技能不是聊天记录不会因为新开会话而消失。它等同于把“知识”从临时会话记忆变成了长期可复用的资产。 ## 4. 环境准备与前置条件 下面进入实操部分。我们需要准备以下环境和材料 ### 4.1 基础环境 - Python 3.9 及以上版本用于运行文档拆分和 Skill 生成脚本。 - 一个支持 Skills 机制的 AI 助手比如 Claude Code、Claude Desktop或者其他兼容 Anthropic Agent Skills 规范的工具。 - 一本或多本需要转换的电子书/技术文档。**建议使用 Markdown 格式作为中间格式**因为后续拆分和处理最方便。 ### 4.2 目录规划 我们约定一个项目目录结构避免后续操作混乱book-to-skill-demo/ ├── input/ │ └── k8s-troubleshooting.md # 原始书籍 Markdown ├── scripts/ │ ├── split_book.py # 按标题拆分章节 │ └── generate_skill.py # 为章节生成 SKILL.md ├── output/ │ └── skills/ # 生成的技能目录 │ ├── k8s-pod-startup/ │ │ └── SKILL.md │ ├── k8s-network/ │ │ └── SKILL.md │ └── ... └── config.yaml # 拆分参数配置### 4.3 关于原始文档格式的说明 如果你的书是 PDF、ePub 或 Word 格式建议先转成 Markdown。这一步可以用现成的工具完成比如 Pandoc bash # 将 PDF 转为 Markdown需要先安装 pandoc pandoc input/k8s-troubleshooting.pdf -t gfm -o input/k8s-troubleshooting.md # 将 ePub 转为 Markdown pandoc input/k8s-troubleshooting.epub -t gfm -o input/k8s-troubleshooting.md这里要提醒一下PDF 转换后的 Markdown 质量往往不太理想尤其是代码块、表格、多级标题这些元素容易错乱。建议转换后先人工检查一遍把标题层级理顺。因为后续的“拆书”逻辑严重依赖 Markdown 的标题结构。如果项目输入材料没有明确指定某个工具版本就不需要纠结具体版本号以你本机实际安装为准。本文重点演示的是通用思路不是某个工具的固定版本操作手册。5. 核心流程拆解从一本书到一组 Skill把一本书变成一组 Skill核心流程可以拆成五步。5.1 第一步预处理原始文档这一步的目标很明确得到一份结构清晰、标题层级完整、代码块正确的 Markdown 文件。具体操作检查一级标题、二级标题是否准确表达章节关系。去掉无关的目录页、前言、致谢等部分这些内容不太可能成为故障排查时的按需技能。确保代码块被正确标注语言类型。为什么这一步重要因为后续的自动拆分脚本默认就是按 Markdown 标题层级来切分内容的。如果标题乱切分出来的块就会乱生成的 Skill 边界也会很模糊。5.2 第二步按主题拆分成块拆分的核心原则是每个块只讲一个主题块内信息自包含。一本书的章节划分通常并不完全等于“主题划分”。比如《Kubernetes 故障排查手册》的第三章可能叫“Pod 生命周期问题”但这一章里既有调度问题又有镜像问题还有健康检查问题。如果直接把整章做成一个 Skill那么这个 Skill 的内容还是太大而且触发条件不聚焦。更合理的做法是在章内部继续按“主题”切块。切块时需要注意每个块的大小建议控制在 2000 到 8000 个 token 之间。太小则信息不完整太大则失去了按需加载的意义。每个块必须有清晰的“能力边界”。比如“排查 CrashLoopBackOff”和“排查 ImagePullBackOff”就是两个不同的主题不要混在一起。每个块要能被一个自然语言问题触发。5.3 第三步为每个块生成 SKILL.md生成了内容块之后需要为每个块写一个SKILL.md。这一步最关键的部分是description 的撰写。描述写得好不好直接决定 AI 助手能不能在正确时机加载这个技能。好的 description 应该包含技能适用的具体任务场景。触发该技能的关键词。明确排除的场景避免误触发。举例description: 当用户遇到 Kubernetes Pod 启动失败、崩溃重启、镜像拉取失败、调度不成功等问题时使用本技能。不适用于 Service 网络访问问题。有一个细节值得注意Skill 的触发条件很大程度上依赖底层模型对 description 的语义理解所以描述要“像用户会问的问题”而不是“像目录名”。比如目录名是“pod-lifecycle”但用户会问“我的 Pod 一直重启怎么办”description 里最好能包含“重启”“崩溃”“CrashLoopBackOff”这类用户真实会用的词。5.4 第四步安装到 AI 助手的 skills 目录不同 AI 助手的 Skill 安装方式不完全相同但大体上都是把 Skill 目录放到指定的 skills 文件夹下。以 Claude Code 为例通常在项目根目录或用户配置目录下存在一个.claude/skills/目录.claude/skills/ ├── k8s-pod-startup/ │ └── SKILL.md ├── k8s-network-debug/ │ └── SKILL.md把生成的 Skill 目录复制进去重启 AI 助手或者重新加载会话就算安装完成。5.5 第五步验证调用安装完成后用真实问题去触发。比如问我的 Pod 一直 CrashLoopBackOff怎么排查然后观察 AI 助手是否加载了k8s-pod-startup这个技能。很多助手会在回复中提示“正在使用技能”或“已加载技能 xxx”。如果 AI 没有触发技能说明 description 写得不到位需要调整。6. 完整示例拆书、生成 Skill、估算上下文用量下面我用一个具体的示例来演示。示例使用 Python 编写分为三个脚本拆书脚本、生成 Skill 脚本、上下文用量估算脚本。6.1 示例一按 Markdown 标题拆书先看拆分脚本。这个脚本的作用是把一本 Markdown 格式的书按二级标题##切分成多个独立文件。# 文件路径scripts/split_book.py import re import os from pathlib import Path INPUT_FILE Path(input/k8s-troubleshooting.md) OUTPUT_DIR Path(output/chunks) OUTPUT_DIR.mkdir(parentsTrue, exist_okTrue) def split_book_by_h2(md_text: str): 按 ## 二级标题将 Markdown 拆分为多个块。 lines md_text.splitlines() chunks [] current_chunk [] current_title None current_heading_level 0 # 记录当前标题级别 for line in lines: # 匹配 Markdown 标题最多支持到 ## 级别 m re.match(r^(#{1,2})\s(.*), line) if m: level len(m.group(1)) title m.group(2).strip() # 遇到二级标题开启一个新 chunk if level 2: if current_chunk: chunks.append((current_title, \n.join(current_chunk))) current_title title current_chunk [line] current_heading_level level else: # 一级标题属于文档总标题不单独成 chunk current_chunk.append(line) else: current_chunk.append(line) if current_chunk: chunks.append((current_title, \n.join(current_chunk))) return chunks def main(): md_text INPUT_FILE.read_text(encodingutf-8) chunks split_book_by_h2(md_text) print(f共拆分出 {len(chunks)} 个章节块) for index, (title, content) in enumerate(chunks, start1): # 用章节序号 标题生成文件名保证排序稳定 safe_title re.sub(r[^\w\u4e00-\u9fa5], _, title)[:30] filename f{index:03d}_{safe_title}.md filepath OUTPUT_DIR / filename filepath.write_text(content, encodingutf-8) print(f[{index}] {title} - {filepath}) if __name__ __main__: main()运行方式python scripts/split_book.py这个脚本的核心逻辑是逐行扫描 Markdown遇到##级别的标题就开启一个新的 chunk。拆完后每个 chunk 独立存储为一个文件。特别说明这个脚本是演示用只处理了##级别。如果书有多级嵌套你需要根据自己的文档结构调整脚本比如按###拆或者先按##拆再按###细分。6.2 示例二为每个章节生成 SKILL.md接下来是生成 Skill 的脚本。它读取拆分后的章节文件自动生成一个包含SKILL.md的 Skill 目录。# 文件路径scripts/generate_skill.py import os import re from pathlib import Path CHUNKS_DIR Path(output/chunks) SKILLS_DIR Path(output/skills) SKILLS_DIR.mkdir(parentsTrue, exist_okTrue) def extract_topic_from_filename(filename: str) - str: 从文件名中提取主题关键字用于生成 description。 # 去掉序号和后缀例如 001_Pod启动失败排查.md - Pod启动失败排查 name re.sub(r^\d_, , filename.replace(.md, )) return name def generate_skill_for_chunk(filepath: Path) - str: 为单个章节文件生成 Skill 目录。 content filepath.read_text(encodingutf-8) topic extract_topic_from_filename(filepath.name) # 取章节内容的前 300 字作为 SKILL.md 的正文摘要 # 这里在生产环境中应该进一步提炼而不是简单截取 body_preview content[:300] skill_name re.sub(r[^\w\u4e00-\u9fa5], -, topic).strip(-) skill_dir SKILLS_DIR / skill_name skill_dir.mkdir(parentsTrue, exist_okTrue) sk_md f--- name: {skill_name} description: 当用户遇到与“{topic}”相关的问题时使用本技能。包括但不限于以下场景{topic}相关的排查步骤、常见错误、解决方案。不适用于其他无关主题。 --- # {topic} ## 使用说明 当用户的问题命中本技能描述时按以下方式回答 1. 阅读本文件中的排查步骤。 2. 结合具体场景按步骤引导用户排查。 3. 如果步骤中涉及命令在回答中给出可复制命令。 ## 内容 {body_preview} skill_md_path skill_dir / SKILL.md skill_md_path.write_text(sk_md, encodingutf-8) return str(skill_md_path) def main(): chunk_files sorted(CHUNKS_DIR.glob(*.md)) if not chunk_files: print(未找到章节文件请先运行 split_book.py) return for chunk_file in chunk_files: path generate_skill_for_chunk(chunk_file) print(f生成技能: {path}) print(f\n共生成 {len(chunk_files)} 个技能到 {SKILLS_DIR}) if __name__ __main__: main()运行方式python scripts/generate_skill.py这个脚本生成的SKILL.md只是一个演示。它把章节内容的前 300 字直接作为正文这在真实场景是不够的。更好的做法是人工为每个章节提炼核心排查步骤、命令、注意事项写入 SKILL.md 的正文同时把原始章节完整内容放到 references 目录作为参考附件。这里体现了 Skill 设计的一个重要思想SKILL.md里放的是“如何执行这个技能”而原始资料可以放到references/供需要时读取。这样平时上下文中只有精简版步骤只有 AI 判断需要更多细节时才去读参考文件。6.3 示例三估算上下文用量最后是估算脚本。通过对比“整本书 token 数”和“所有 Skill 描述 token 数”直观看出省了多少上下文。# 文件路径scripts/estimate_tokens.py import re from pathlib import Path INPUT_FILE Path(input/k8s-troubleshooting.md) SKILLS_DIR Path(output/skills) def count_tokens_rough(text: str) - int: 粗略估算 token 数。中文场景下一个字约等于 1 个 token。 # 这里用字符数作为简化估算更准确的估算需要接入分词器 return len(text) def main(): book_text INPUT_FILE.read_text(encodingutf-8) book_tokens count_tokens_rough(book_text) skill_desc_tokens 0 skill_full_tokens 0 for skill_md in SKILLS_DIR.rglob(SKILL.md): content skill_md.read_text(encodingutf-8) skill_full_tokens count_tokens_rough(content) # 只统计 description 行作为常驻上下文的近似 m re.search(r^description:\s*(.*)$, content, re.MULTILINE) if m: skill_desc_tokens count_tokens_rough(m.group(1)) print(f整本书估算 token 数: {book_tokens}) print(f所有技能完整内容 token 数: {skill_full_tokens}) print(f所有技能 description 常驻 token 数: {skill_desc_tokens}) if skill_desc_tokens: print(f按需加载 vs 全文塞入 的节省倍数(粗略): {book_tokens / skill_desc_tokens:.1f} 倍) if __name__ __main__: main()运行方式python scripts/estimate_tokens.py这个脚本最重要的输出是最后一行“节省倍数”。如果所有 Skill 的 description 加起来只有几百 token而整本书有几十万 token那两者的差距就是几十倍。这也就是项目宣称“省 51 倍上下文”的逻辑基础。需要说明的是这里的 token 估算用了简单的字符数近似真实的 token 数计算需要接入具体模型的分词器。但对于对比“全文 vs 按需”的数量级差异这个简单估算已经足够说明问题。6.4 示例四在 Claude Code 中的实际使用生成 Skill 之后如何在 AI 助手中生效下面以 Claude Code 为例演示。把生成的 Skill 目录放到项目的.claude/skills/下mkdir -p .claude/skills cp -r output/skills/* .claude/skills/然后启动 Claude Codeclaude在会话中输入我的 Deployment 滚动更新一直卡住Pod 起不来请帮我排查。如果 Skill 的 description 里有“滚动更新”“Pod 起不来”“排查”等关键词Claude Code 会自动匹配到对应的技能并加载。当然不同 AI 助手的 Skill 目录路径和加载机制可能不同具体以你使用的工具官方文档为准。核心原理是一致的技能描述常驻索引技能正文按需加载。7. 运行结果与效果验证完成上述示例之后你可以通过以下方式验证结果。7.1 查看生成的目录结构tree output/skills预期输出类似output/skills/ ├── Pod启动失败排查/ │ └── SKILL.md ├── Service网络问题排查/ │ └── SKILL.md └── 滚动更新卡住处理/ └── SKILL.md7.2 查看估算结果运行estimate_tokens.py后你会看到类似这样的输出整本书估算 token 数: 320000 所有技能完整内容 token 数: 45000 所有技能 description 常驻 token 数: 2000 按需加载 vs 全文塞入 的节省倍数(粗略): 160.0 倍这里的 160 倍只是一个举例。实际倍数取决于你的书有多大、拆分粒度有多细、description 写得多精简。核心关注点不是数字本身而是数量级上的差异。7.3 在 AI 助手中验证技能触发验证技能是否真正生效有几种方法在对话中明确提问观察助手的回复是否出现“正在使用技能”或类似提示。用调试模式很多 AI 助手支持显示加载的上下文和技能名称。故意问一个明显不相关的问题确认它不会误加载技能。如果技能没有触发优先检查 description。很多时候不是 Skill 目录放错了而是 description 没有覆盖用户真实的问法。比如你写的是“Kubernetes Pod 启动失败”但用户会问“容器一直重启怎么办”这两句话语义相近但字面不同AI 能否关联上取决于底层模型的能力。稳妥的做法是在 description 里把用户可能用的各种问法都写进去。8. 常见问题与排查思路在实际把玩这个流程的过程中最容易遇到下面这些问题问题现象可能原因排查方式解决方案生成技能数量过少原始 Markdown 标题层级不规整##太少查看原始文档标题结构预处理文档统一标题层级技能互相重叠触发混乱拆分粒度太大一个 chunk 包含多个主题查看 chunk 文件内容是否聚焦细化拆分逻辑按###拆或人工调整边界AI 助手不加载技能description 写得不够贴近用户问法在助手调试模式中查看技能索引重写 description覆盖更多用户问法技能加载了但回答质量差SKILL.md 正文信息不足查看 SKILL.md 内容增加步骤、命令、示例、常见错误上下文仍然超限一个 Skill 内 references 太大检查 references 文件大小进一步拆分或只保留关键内容新会话技能丢失技能目录放错位置检查 skills 目录路径放在项目根目录或用户级全局目录PDF 转 Markdown 后格式混乱PDF 本身无结构化信息检查转换后的代码块和表格手动修复或用高质量转换工具我特别想展开说一下“技能互相重叠”这个问题。举例如果有个 chunk 叫“Kubernetes 基础概念”另一个 chunk 叫“Pod 生命周期”用户问“Pod 一直重启怎么办”两个技能都可能被触发。这种情况下AI 可能加载了“基础概念”这个包含大量百科式内容的技能占用上下文却没有提供有用的排查步骤。解决方案有两个方向拆分时尽量让主题互斥。比如“Kubernetes 基础概念”这种通识性内容就不太适合做成按需技能因为它没有明确的“触发任务边界”。在 description 中明确排除边界。比如“Pod 生命周期”技能的描述里写“不适用于集群安装、网络配置等场景”。很多人第一次做 Skill 拆分时意识不到 description 的边界声明有多重要。它不仅能提高技能触发的准确率还能避免多个技能同时加载导致上下文浪费。9. 最佳实践与工程建议经过流程拆解和问题排查下面是我认为做这件事最值得遵循的几条工程建议。9.1 先整理文档再拆技能拆书之前花半小时整理 Markdown 结构比拆完再返工要高效得多。整理的核心是标题层级。一本书如果原来的目录结构足够清晰二级标题基本就等于章节主题拆出来的 Skill 边界也会比较干净。9.2 控制技能的粒度一个技能的正文建议控制在 2000 到 8000 token。太小的技能没有独立的必要会提高索引噪音太大的技能失去了按需加载的优势。判断粒度是否合适有一个简单标准拿这个技能的名字问自己一个用户问题能否在 10 秒内判断“该不该用这个技能”。如果能粒度基本合适如果需要看完整描述才能判断说明粒度太粗或边界不清。9.3 description 是重中之重我在这篇文章里已经很多次提到 description因为它真的是整个机制的命门。写 description 时建议覆盖三个维度技能负责的任务类型比如“排查”“转换”“生成”。技能适用的领域关键词比如“Kubernetes”“Pod”“CrashLoopBackOff”。明确的排除条件比如“不适用于网络问题”。9.4 用 references 承载细节SKILL.md 保持精简SKILL.md 是技能的执行框架references 目录放原始参考资料的细节。这样两者各司其职框架常驻AI 知道这个技能怎么用。细节按需只有需要时才去 references 里找详细资料。9.5 持续迭代技能库书不是静态的技术会更新规范会调整。技能库也需要维护。建议在每次使用的过程中把“AI 回答明显不准确”的场景记录下来反哺到对应的 SKILL.md 中。经过几轮迭代技能库的质量会有明显提升。9.6 明确不适合的场景不是所有资料都适合转成 Skill。如果你的一本书是小说、散文或者主题高度连贯、无法拆分不适合。如果你的问题场景可能涉及全书任意位置按需加载的效果不好RAG 可能更合适。如果你的文档只有几千字直接全文塞入反而更简单没必要做技能化改造。这个方案最适合的是“结构清晰、按主题调用、场景明确”的技术手册和团队规范。10. 总结与后续实践方向book-to-skill 的核心价值不是那个“51 倍”的营销数字而是它背后的上下文工程思路在 AI 助手时代知识不应该以“整本书”的形态常驻上下文而应该以“按需技能”的形态被随时调用。它把长期困扰程序员的长文档使用问题从“模型上下文不够大”转化为“如何设计一套高效的知识调用系统”。这对任何需要把大量规范、手册、内部文档沉淀给 AI 使用的团队都是一个值得认真尝试的方向。如果你准备动手实践我的建议是选一本你工作里最常需要查阅的技术手册。先转成 Markdown人工检查标题结构。用脚本拆块再人工调整每个块的主题边界。为每个块撰写 SKILL.md重点打磨 description。安装到你的 AI 编程助手中用真实问题验证触发效果。根据使用反馈持续迭代技能内容。如果整套流程跑通了你大概率会发现同样的助手在接入技能库之后回答质量和上下文消耗都有了质的改变。这种改变比单纯换一个更大上下文的模型来得更实际也更可持续。