用 pdf2skill 把 PDF 专业资料编译成 Claude Code 和 OpenCode 技能包

很多专业知识都躺在 PDF（Portable Document Format，便携式文档格式）里：技术规范、操作手册、行业报告、方法论书籍、业务培训材料。直接把这些资料丢给 AI（人工智能）做摘要，通常只能得到一段概括性的文字；真正工作时，AI 仍然不知道什么时候该用哪套方法，也不知道某个流程的前置条件、分支判断和输出格式。

pdf2skill 要解决的正是这个问题：把 PDF 编译成 Skill（技能包），让 Claude Code 或 OpenCode 在合适的任务场景里自动调用对应的专业方法。

它不是简单提取目录，也不是把每章压缩成摘要，而是把文档里的概念、步骤、条件、异常分支和依赖关系整理成一组可复用的 Markdown 技能文件。最终产物通常是一个 skills.zip，解压到指定目录后，AI 助手就能把这些知识当成工具使用。

pdf2skill 解决的核心问题

AI 处理专业资料时，常见麻烦有三类。

第一类是上下文成本。一本几百页的书不可能每次对话都重新上传，即使能上传，也会占用大量上下文窗口。任务一多，资料内容很容易被压缩、遗忘或误用。

第二类是结构丢失。摘要能告诉你“这本书讲了什么”，但它通常不会完整保留“什么时候用 A 方法、A 方法之前要检查什么、遇到异常指标要切换到哪个流程”。

第三类是复用困难。一次对话里整理出来的 Prompt，很难稳定迁移到后续任务。每次都要重新解释背景、规则、格式和边界条件。

pdf2skill 的思路是把文档处理成可加载的技能资产：

flowchart LR
    A[PDF 书籍 / 手册 / 报告 / 规范] --> B[文档解析]
    B --> C[语义拆解]
    C --> D[知识结构化]
    D --> E[依赖关系建模]
    E --> F[Skill 文件生成]
    F --> G[skills.zip]
    G --> H[Claude Code / OpenCode 加载调用]

PDF 进入编译流程后，不再只是被压缩成一段文字，而是变成一组带触发条件、输入要求、执行步骤和输出格式的技能文件。AI 助手接到任务时，可以根据用户问题匹配对应 Skill，而不是把整本书重新塞进对话。

和“让 AI 总结 PDF”有什么不同

直接总结 PDF 的产物是文本，pdf2skill 的产物是可调用的工作流。两者适合的任务完全不同。

可以把摘要理解成“给人看的浓缩版”，把 Skill 理解成“给 AI 调用的操作手册”。前者回答“资料大概讲什么”，后者回答“遇到这个任务应该怎么做”。

生成的技能包长什么样

一个典型的 skills.zip 解压后，大致会包含主技能文件、多个子技能文件、索引和说明文档：

skills/
├── SKILL.md              # 主技能文档，描述技能集合的用途、触发方式和整体规则
├── skills/
│   ├── skill-001.md      # 单个技能定义
│   ├── skill-002.md
│   ├── skill-003.md
│   └── index.md          # 技能索引和路由规则
└── README.md             # 给人阅读的说明文档

每个 Skill 文件一般会包含这些内容：

一个简化后的 Skill 可能长这样：

---
name: cash-flow-statement-classification
description: 用于按经营活动、投资活动、筹资活动分析现金流量表
triggers:
  - 分析现金流
  - 判断企业现金流质量
  - 拆解现金流量表
inputs:
  - cash_flow_statement
  - company_context
outputs:
  - cash_flow_quality_report
---

# 现金流量表分类分析

## 使用场景

当用户需要判断一家企业现金流质量，或者需要解释现金流量表中各类现金流变化时，调用该技能。

## 执行步骤

1. 将现金流拆分为经营活动、投资活动、筹资活动。
2. 判断经营活动现金流是否能覆盖净利润。
3. 检查投资活动现金流是否主要来自扩张、资产处置或金融投资。
4. 分析筹资活动现金流是否依赖持续举债或股权融资。
5. 输出现金流质量判断和风险点。

真实技能文件会比这个更细，尤其是方法论书籍、规范文档和操作手册，通常会包含更多分支条件和异常处理规则。

编译流程：从 PDF 到 Skill 的 5 个阶段

pdf2skill 可以理解成一个“文档转技能编译器”。它的内部处理过程大致分为五层：文档解析、语义密度分析、知识结构化、融合索引、Skill 转换。

flowchart TB
    A[PDF 输入] --> B[1. 文档解析]
    B --> C[2. 语义密度分析]
    C --> D[3. 知识结构化]
    D --> E[4. 融合引擎]
    E --> F[5. Skill 转换]
    F --> G[SKILL.md]
    F --> H[子技能文件]
    F --> I[索引与路由规则]
    F --> J[README.md]

这个流程的关键不在“切分”，而在“建模”。如果只是按页数或章节硬切，AI 仍然需要自己判断哪些内容能用于当前任务。pdf2skill 更关注语义边界：一个完整方法、一个判断流程、一个异常处理分支，应该尽量被组织成独立且可调用的技能单元。

AI 助手如何调用这些 Skill

Skill 被放入 Claude Code 或 OpenCode 的技能目录后，AI 助手会在任务中根据描述和触发规则选择合适的文件。调用过程可以抽象成这样：

sequenceDiagram
    participant U as 用户
    participant A as AI 助手
    participant R as 技能索引
    participant S as 具体 Skill
    participant O as 输出结果

    U->>A: 提出任务：帮我分析这份财报
    A->>R: 检索可用技能和触发条件
    R-->>A: 匹配 financial-analysis-four-step-method
    A->>S: 读取技能步骤、输入要求和输出格式
    S-->>A: 返回分析流程
    A->>O: 按 Skill 生成结构化分析结果
    O-->>U: 返回财报分析报告

这种方式的好处是，AI 不需要每次重新理解整本书。只要技能文件设计得足够清楚，它就可以像调用工具一样调用专业方法。

快速上手：上传、下载、导入

pdf2skill 提供在线上传入口：

https://pdf2skills.memect.cn/quick-start

基本流程很短：

flowchart LR
    A[上传 PDF] --> B[等待编译]
    B --> C[下载 skills.zip]
    C --> D[解压到技能目录]
    D --> E[重启或重新加载 AI 助手]

拿到 skills.zip 后，按使用工具选择目录。

Claude Code 用户：

unzip skills.zip -d ~/.claude/skills/your-skill-name/

OpenCode 用户：

unzip skills.zip -d ~/.config/opencode/skills/your-skill-name/

如果希望技能只在某个项目内生效，可以放到项目本地目录：

unzip skills.zip -d your-project/.claude/skills/your-skill-name/

导入后不需要再写 JSON Schema（一种描述 JSON 数据结构的规范），也不需要手工把书改写成 Prompt。生成结果是 Markdown 文件，如果某些触发条件、术语或输出格式不符合实际需求，可以直接编辑。

适合转换成 Skill 的 PDF 类型

不是所有 PDF 都适合技能化。pdf2skill 更适合那些“有方法、有流程、有判断规则”的资料。

判断一份资料是否适合 Skill 化，可以看三个问题：

1. 资料里有没有明确的操作步骤？
2. 有没有“如果……那么……”这类条件判断？
3. 有没有可以重复应用到不同任务中的方法框架？

如果三个问题大多是肯定答案，转换价值通常比较高。

案例一：游戏设计书籍转换成设计技能包

以 Wendy Despain 的《游戏设计的 100 个原理》为例，pdf2skill 可以把一本游戏设计方法论书籍拆成多个独立技能，覆盖核心循环、难度平衡、关卡体验、交互设计、玩家心理和测试管理等主题。

如果把这些分散的技能再整合成一个主技能和多个参考文档，目录可以组织成这样：

~/.claude/skills/game-design/
├── skill.md
└── references/
    ├── character-optimization-design.md
    ├── dynamic-difficulty-adjustment.md
    ├── game-design-methodology.md
    ├── game-development-planning.md
    └── ...（其余参考文档）

主技能可以把游戏设计流程整理成 8 个阶段：

flowchart LR
    A[概念定义] --> B[核心循环]
    B --> C[机制与平衡]
    C --> D[关卡与体验]
    D --> E[视觉与交互]
    E --> F[玩家心理]
    F --> G[原型与测试]
    G --> H[团队管理]

同一套技能还可以按任务类型切换工作模式：

这种技能组织方式的重点是把“知识点”变成“任务流程”。AI 不只是知道 Fitts 定律和 Hick 定律是什么，还能在设计 UI、瞄准、菜单选择、视觉引导时调用对应规则。

一个完整使用链路可以是：

flowchart TB
    A[游戏设计书籍 PDF] --> B[pdf2skill 编译]
    B --> C[游戏设计 Skill 集合]
    C --> D[Claude Code 加载]
    D --> E[调用设计流程]
    E --> F[生成游戏策划结构]
    F --> G[编写单文件 HTML 游戏]

示例产物是一款单文件 HTML 策略游戏，代码规模为 828 行，浏览器打开即可运行。它包含七大空间面板、SVG 动态地图、历史事件决策、水墨风界面和多结局系统。这个例子说明，Skill 的价值不止是“让 AI 懂一本书”，而是把书里的方法转成可以驱动实际产出的工作流。

案例二：财报教材转换成分析技能包

财报分析教材通常非常适合 Skill 化，因为它天然包含表格、指标、判断规则和分析顺序。

一份 300 页左右的财报分析资料，可以被转换成多个细分技能，例如：

这类技能适合做成“分析管线”：

flowchart LR
    A[输入财报数据] --> B[基础报表拆解]
    B --> C[指标计算]
    C --> D[现金流质量判断]
    D --> E[收入预测]
    E --> F[风险与结论输出]

相比一次性总结教材，这种方式能让 AI 在不同企业、不同年份、不同报表数据上重复执行同一套分析框架。

案例三：行业操作规范转换成判断流程

行业手册和操作规范通常包含大量条件分支。把它们转换成 Skill 后，AI 可以根据输入指标自动选择流程，而不是只复述规则。

例如某个规范里有这样的判断逻辑：

IF 指标A > 阈值:
    执行流程1
ELIF 指标B 异常:
    触发异常处理分支
ELSE:
    走标准流程

Skill 化后的价值在于，每个分支都可以单独定义触发条件、输入要求和输出格式：

flowchart TB
    A[输入业务指标] --> B{指标A > 阈值?}
    B -- 是 --> C[执行流程1 Skill]
    B -- 否 --> D{指标B 异常?}
    D -- 是 --> E[异常处理 Skill]
    D -- 否 --> F[标准流程 Skill]
    C --> G[输出操作建议]
    E --> G
    F --> G

这类资料如果只做摘要，很多边界条件会变成模糊描述；转换成 Skill 后，规则可以更接近可执行流程。

使用时需要注意的点

1. PDF 质量会影响结果

扫描版 PDF、目录混乱、表格识别错误、图片文字过多，都会影响编译质量。尽量使用文本可复制、结构清晰、目录完整的文件。

如果资料是扫描件，可以先做 OCR（光学字符识别）处理，再上传编译。

2. 技能生成后最好人工校验

pdf2skill 负责把资料转换成结构化技能，但专业判断仍然需要校验。尤其是法律、医疗、金融、工程安全等场景，不能把生成结果直接当成最终结论。

推荐检查这些位置：

3. 不要把所有资料都塞进一个大 Skill

如果一个技能包包含太多无关知识，AI 匹配时会变得困难。更好的做法是按领域、任务或工作流拆分：

skills/
├── finance-analysis/
├── game-design/
├── legal-contract-review/
└── operation-manual/

每个技能包内部再用索引文件组织子技能。这样既便于维护，也便于 AI 路由。

4. 纯概念资料的转化效果有限

如果一本书主要是观点、哲学讨论或文学表达，没有明确步骤和判断规则，生成的 Skill 往往只能提供解释型帮助。它仍然可能有用，但很难变成稳定的执行流程。

5. 生成时间取决于页数和知识密度

当前支持 500 页以内的 PDF。常见处理时间可以按页数粗略估计：

内容密度高、结构复杂、表格多的资料通常会更慢，因为需要提取和建模的知识更多。

常见问题

需要本地安装吗？

不需要。通过在线入口上传 PDF，编译完成后下载 skills.zip，再解压到 Claude Code 或 OpenCode 的技能目录即可。

需要提供 API Key 吗？

不需要。编译过程在服务端完成，使用者只需要上传 PDF 并下载生成结果。

支持中文和英文 PDF 吗？

支持中文和英文资料。混合语言资料也可以处理，但专业术语最好在生成后检查一遍，避免同一概念出现多个译名。

生成的 Skill 能自己修改吗？

可以。输出文件是 Markdown 格式，可以直接编辑技能名称、触发条件、执行步骤、输出格式和参考内容。

Claude Code 和 OpenCode 的目录有什么区别？

Claude Code 常见目录：

~/.claude/skills/

OpenCode 常见目录：

~/.config/opencode/skills/

项目级技能可以放在项目目录下，例如：

your-project/.claude/skills/

具体加载行为仍以对应工具版本的 Skill 规则为准。

适合采用 pdf2skill 的场景

pdf2skill 适合把“需要反复使用的专业知识”变成 AI 能调用的技能，尤其是这些场景：

不太适合的场景也很明确：只想快速了解一本书大意时，普通摘要更省事；资料本身没有可执行方法时，Skill 化的收益也会降低。

小结

pdf2skill 的核心价值是把 PDF 从“静态资料”变成“可调用能力”。它通过文档解析、语义拆解、知识结构化、依赖建模和 Skill 生成，把书籍、手册、报告和规范转换成 Claude Code 或 OpenCode 可以加载的 Markdown 技能包。

如果手里有大量专业 PDF，尤其是方法论、操作规范、技术标准和行业分析资料，可以用它把知识整理成长期可复用的 AI 工作流。使用入口是：

https://pdf2skills.memect.cn/quick-start