Docling Agent Skill：让 AI Agent 随包自动学会使用 Docling 的转换、抽取与切分
【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling
Docling 在 Python 包内部自带了一个usage skill（自包含的指令文件集），安装后即可被 AI 编码 Agent 自动发现，Agent 能直接从 Docling 项目官方撰写的文档中学会如何正确调用doclingCLI、Python SDK（DocumentConverter+PipelineOptions）、DocumentExtractor与 RAG 切分。本文覆盖 skill 的安装发现方式（library-skills符号链接）、手动路径注册、包内目录结构与按需加载机制，并结合仓库源码剖析 skill 的 frontmatter 设计与随 wheel 分发的打包依据，读完后你能够在自己的项目中让 Agent 稳定地"带着官方知识"操作 Docling。
什么是 Agent Skill：随包分发的自包含指令包
Agent skill 是一组自包含的指令文件，用于教会 AI 编码 Agent 如何使用某个工具。Docling 的做法是把usage skill直接放在 Python 包源码树内——安装docling后，skill 随包一起进入环境，Agent 运行时可以自动发现它，无需在 Agent 侧额外维护一份使用文档。这带来两个直接收益：
- 知识随版本更新：skill 内容来自 Docling 项目官方，与 CLI/SDK 行为保持一致；
- 按需加载：入口
SKILL.md是短路由，正文引用文件在需要时才读取，Agent 只为当前任务加载所需内容，不占满上下文。
skill 的入口文件是 SKILL.md，其 YAML frontmatter（SKILL.md）声明了 skill 的元数据：
name: docling description: > Use Docling to understand the content of documents in any supported format — PDF (born-digital or scanned), DOCX, PPTX, XLSX, HTML, Markdown, AsciiDoc, CSV, images, audio, and XML — by converting them into a unified DoclingDocument (Markdown or structured JSON). ... license: MIT compatibility: Requires Python 3.10+ metadata: author: docling-project version: "1.0" allowed-tools: Bash(docling:*) Bash(docling-tools:*) Bash(python3:*) Bash(python:*) Bash(uvx:*) Bash(uv:*) Bash(pip:*)从源码结构看，frontmatter 各字段承担明确分工：description是 Agent 判断"何时该用这个 skill"的触发描述（覆盖了 "what's in this PDF"、"convert this to markdown"、"chunk this for RAG" 等典型请求）；compatibility声明 Python 3.10+ 前置条件（与 pyproject.toml 中requires-python = '>=3.10,<4.0'一致）；allowed-tools限定了 Agent 允许执行的命令前缀（docling、docling-tools、python、uvx等），构成一道工具白名单。
SKILL.md正文是一个"路由器"：先给出最快的可用路径（CLI 一行命令），再用一张决策表把任务分发到 6 个引用文件，并给出Rules of thumb（本地一次性任务用 CLI、要调 pipeline/切分/嵌入应用用 SDK、多文档低延迟免 GPU 用 Service Client、最小化安装体积用 docling-slim）。它还约定了输出规范，例如：必须汇报转换状态和 PDF 页数、用户未指定格式时先询问要 Markdown 还是 JSON、表格优先用 table item 的export_to_markdown()/export_to_dataframe()、PDF 输出近乎为空或出现大量U+FFFD替换字符时改用 OCR 或--pipeline vlm重试。
安装与发现 skill：library-skills 的符号链接方式
推荐方式是使用library-skills——一个扫描项目已安装依赖、找出其中捆绑的 skill、并把它们以符号链接形式装进 Agent skill 目录的小 CLI 工具。因为使用符号链接，升级 Docling 后 skill 内容自动更新，无需重新安装。
项目已依赖 Docling（推荐路径）
如果docling已经是项目依赖，直接运行：
多数 Agent（Codex、Cursor、Copilot 等）使用统一的.agents/目录约定：
uvx library-skillsClaude Code 使用.claude/目录而非.agents/，需加--claude参数，使 skill 安装到.claude/skills：
uvx library-skills --claude从流程上看，library-skills会读取项目的pyproject.toml，扫描项目环境中已安装的包，然后为 Docling 捆绑的 skill 创建符号链接，指向.agents/skills/docling（或.claude/skills/docling）。这一步做完即完成接入。
如果 Docling 还不在项目中，library-skills无法自动发现它——先安装（uv add docling或pip install docling），再按上述方式运行uvx library-skills。
手动路径注册：适配尚未支持 .agents/ 约定的运行时
如果你的 Agent 运行时还不支持.agents/目录约定，可以手动定位 skill 目录并注册。以下命令利用 Python 的importlib找到已安装docling包的物理位置，拼出 skill 目录路径并打印：
python -c "import importlib.util, pathlib; \ print(pathlib.Path(importlib.util.find_spec('docling').origin).parent / '.agents/skills/docling')"然后把 Agent 指向打印出的路径（或其中的SKILL.md）即可。这条命令的健壮性来自 skill 的分发位置：skill 位于包的根目录内（docling/.agents/skills/docling/），与包的入口模块同级，因此从任意安装方式（wheel、sdist、本地路径）解析出的包根目录下都能按固定相对路径找到它。
skill 的目录结构与按需加载机制
skill 在安装后的包内位于docling/.agents/skills/docling/，完整结构如下：
docling/.agents/skills/docling/ ├── SKILL.md # 入口：Docling 是什么 + 何时使用哪条路径 └── references/ ├── cli.md # 从命令行转换任意格式 ├── python-sdk.md # DocumentConverter + PipelineOptions、批处理、ASR、图片/表格导出 ├── extraction.md # DocumentExtractor — 从文档抽取指定类型的字段（beta） ├── rag.md # 切分 + LangChain / LlamaIndex / Haystack loader ├── service-client.md # 经 docling-serve 远程转换（自托管或托管） └── slim-packaging.md # docling-slim 安装 extrasSKILL.md负责路由，references/*.md在需要时才被加载，Agent 只读取当前任务所需的内容。skill 的路由表把每类任务映射到对应引用文件：
| 任务 | Skill 引用 |
|---|---|
| 从 shell 读取/转换文件 | cli.md |
在代码中转换并调优 pipeline（PipelineOptions） | python-sdk.md |
| 从文档中抽取特定类型字段 | extraction.md |
| 为 RAG 切分文档 | rag.md |
| 把转换卸载到远程服务 | service-client.md |
| 只安装需要的依赖 | slim-packaging.md |
各引用文件的内容与仓库实际能力一一对应，可作为 skill 可信度的佐证：
- cli.md：任务导向的 CLI 摘要。基本用法
docling <source> [--to md|json|html|text|doctags] [--output DIR]，source 可为本地路径或 URL；两条 pipeline 家族（--pipeline standard面向 born-digital PDF、CPU 可用，--pipeline vlm面向复杂版式/手写/公式、需 GPU 或 Apple MPS）；OCR 引擎选择（--ocr-engine easyocr|rapidocr|tesserocr|ocrmac、--force-ocr、--no-ocr、--ocr-lang）；表格与富化（--no-tables、--table-mode accurate、--enrich-formula等）；常见情境速查表（密码 PDF 用--pdf-password、大文档用--page-range、GPU/CPU 显式指定--device cuda|cpu|mps）；离线场景先docling-tools models download --output-dir /models再配--artifacts-path。 - python-sdk.md：入口为
DocumentConverter，行为由PipelineOptions子类按InputFormat控制；skill 中特别标注了 API 注意事项（Docling 2.81+ 起format_options的键必须是InputFormat枚举成员并匹配对应的FormatOption值，字符串键会在运行时触发AttributeError）。 - extraction.md：
DocumentExtractor与DocumentConverter的区别——前者按模板抽取指定的类型化字段（如发票号、合同字段）而非整个文档，标记为 beta，需要extract-coreextra。 - rag.md：直接用 SDK 的
HybridChunker切分，或使用各框架现成 loader——LangChain 的DoclingLoader（langchain-docling）、LlamaIndex 的DoclingReader+ Docling node parser、Haystack 的docling-haystack。 - service-client.md：
docling.service_client把转换卸载到远程docling-serve端点，本地只需docling-slim[service-client]，无 torch、无 OCR 引擎、无 GPU；调用形态与本地DocumentConverter相同。 - slim-packaging.md：
docling-slim与docling同代码库但默认零可选依赖，按 extras 组合安装；pip install docling等价于docling-slim[standard]。
skill 还提供了免持久化安装的运行方式（来自 SKILL.md）：
uvx --from docling docling report.pdf --to md --output /tmp/打包与同步机制：为什么 skill 一定在包内
skill 随包分发不是约定俗成，而是构建配置直接保证的。pyproject.toml 中：
[tool.hatch.build.targets.wheel] packages = ["docling"] [tool.hatch.build.targets.sdist] only-include = ["docling", "pyproject.toml", "README.md", "LICENSE"]wheel 目标打包整个docling/目录树，因此docling/.agents/skills/docling/下的SKILL.md与 6 个 references 文件都会进入 wheel/sdist——这正是前文手动注册命令能从包根目录稳定拼出 skill 路径的原因，也是library-skills扫描"已安装包"即可发现 skill 的前提。
维护规范方面，AGENTS.md 明确了 skill 的两类划分与同步纪律：
Usage skills（供使用Docling 转换文档的 Agent）打包在包内
docling/.agents/skills/docling/，会被打包进 wheel/sdist，在docling安装后可通过uvx风格的 library skills 发现。当面向用户的行为变化时，必须让它们与 CLI、SDK（PipelineOptions）、Service Client、docling-slimextras 保持同步。
这条规则解释了 skill 内容为何可以"当作权威使用说明"：它被项目自身的 Agent 工作流约束为与真实 API 同步的活文档，而非一次性快照。
usage skill 与 development skill 的区分
本文所述的 skill 是usage skill——帮助 Agent使用Docling。参与 Docling开发的协作者使用另一套独立的development skills，存放在仓库根目录的.agents/skills/中，不随包分发。当前仓库根目录.agents/skills/下实际包含dignified-python（Python 代码风格与模式）和building-pydantic-ai-agents（Pydantic AI Agent 开发）两个开发 skill，各自带SKILL.md与 references 子目录。
这个"仓库根目录放开发 skill、包内放使用 skill"的双目录结构，配合AGENTS.md中对两类 skill 的显式说明，构成了完整的项目级 Agent 知识体系：外部用户装包即得使用知识，内部贡献者克隆仓库即得开发知识，二者互不污染。
小结
Docling 的 Agent skill 方案可以归纳为三步落地：
- 确保
docling是项目依赖（uv add docling或pip install docling）； - 运行
uvx library-skills（Claude Code 用户加--claude），让符号链接建立到.agents/skills/docling或.claude/skills/docling；运行时不支持该约定时，用 SKILL.md 给出的importlib命令手动定位并注册； - 之后 Agent 即可按
SKILL.md的路由表，就 CLI、Python SDK、抽取、RAG 切分、远程转换、slim 安装六大场景按需读取对应 reference，获得与 Docling 版本同步的官方使用说明。
核心文件索引：docs/usage/agent_skills.md（本页原始文档）、docling/.agents/skills/docling/SKILL.md（skill 入口）、pyproject.toml（打包配置）、AGENTS.md（skill 维护规范）。
【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
