AI

设计 Agent Skills

让通用大模型成为文档排版领域的专家

v1.0 开放标准 跨模型兼容

一、背景

在技术文档发布链路中，制作工程师通过 Oxygen，VS Code 等完成 MD 格式文档制作后，在写管用平台 → AHF CSS 排版 → 自动完成 PDF 输出是行业主流方案之一。然而，当 MD 文档中出现超宽表（10+ 列、50+ 行）时， 排版链路极易暴露出表宽溢出、表头压字、数据折行、页眉页脚丢失等一系列缺陷。

传统做法是：由文档工程师反复试错、人工调整 MD 文档，修订 CSS、逐页检查 PDF。 一个大规模文件动辄需要若干轮迭代，问题定位依赖个人经验，修复方案无法沉淀复用。

核心痛点： 文档排版问题看似"边缘"，却占用了大量重复性人力，且每次出现都要从零诊断。 大模型虽然在通用领域表现优异，但缺乏对这一垂直领域的结构化知识， 直接提问往往得到泛泛而谈的建议，无法一揽子解决问题。

Agent Skills 的出现

Agent Skills 是一套开放式、基于文件夹结构的能力封装规范， 通过把"领域知识 + 可执行脚本 + 参考资料 + 模板"打包成一个标准目录， 让通用大模型在需要时按需加载、按流程执行， 从而在特定领域获得专家级表现。

本设计将「大表 PDF 溢出修复」这一高频、可枚举的文档排版问题， 封装为一个可被任意兼容模型调用的 Skill —— 无论是 Claude、DeepSeek、Qwen、GLM、Kimi，还是其他 OpenAI 兼容的 Agent 框架，都能按同一套流程自动完成诊断、修复与验证。

二、核心好处

1从"零散问答"到"一揽子闭环"

用户只需一句话描述问题（"表格溢出了"）， Skill 自动完成诊断 → 定因 → 修复 → 验证四步闭环， 无需多轮交互、无需人工提供中间文件。

2节省 Token 与响应时间

采用三级渐进式披露机制：只有元数据常驻上下文， 正文仅在触发时加载，脚本和参考资料只在真正需要时才读取。 相比把全部知识塞进提示词，Token 消耗降低一个数量级。

3结构化、可复用的知识沉淀

把过去只有资深文档工程师掌握的经验 （如"DITA 管道会剥离 col 的 class 属性"） 固化为可执行的诊断脚本与参考资料，团队新人也能得到一致的输出。

4跨模型、跨平台兼容

不依赖任何特定模型 API；所有脚本操作的是文件 （中间 XHTML、CSS、PDF），而不是模型能力。 Claude、DeepSeek、Qwen、GLM、Kimi 等均可无缝运行。

5可验证、可审计

每一步都有明确的输入、输出与判定标准； 修复完成后自动运行 PDF 验证脚本，产出结构化的修复报告， 全过程可追溯、可审计。

6不影响现有文档体系

所有 CSS 规则均严格作用域限定在专用包装类下， 不污染文档中其他表格；MD 源文件仅需添加一个包装 <div>， 不动数据本身。

三、Skill 概要

3.1 目录结构

一个 Skill 就是一个独立文件夹。下面是「大表 PDF 溢出修复」Skill 的完整结构：

table-pdf-overflow-fixer/ ├── SKILL.md # 核心指令文件（必需） ├── scripts/ # 可执行脚本（可选） │ ├── diagnose.py # 诊断根因 │ ├── calc_col_widths.py # 核算列宽百分比 │ └── verify_pdf.py # 验证输出 PDF ├── references/ # 参考文档（可选） │ ├── root-cause-catalog.md # 六类根因目录 │ ├── css-snippets.md # 可复用 CSS 片段 │ ├── column-width-guide.md # 列宽核算方法 │ └── dita-pipeline-notes.md # 管道行为说明 └── assets/ # 资源模板（可选） └── template-report.html # 修复报告模板

3.2 三级渐进式披露

Skill 的核心设计是按需加载：模型在对话的不同阶段，只读取当前阶段需要的内容， 从而在"知识完整"与"Token 节省"之间取得最优平衡。

Level 1 · YAML Frontmatter

常驻系统提示词。包含 Skill 名称、描述、适用场景、兼容性声明。 模型据此判断"当前任务是否属于本 Skill 的适用范围"。 预计 Token 消耗：200 字以内。

Level 2 · SKILL.md 正文

当模型判定任务匹配后加载。包含完整工作流程、四阶段执行步骤、 禁用事项与自检清单。预计 Token 消耗：1,500 字左右。

Level 3 · 关联文件

脚本、参考资料、模板按需读取。例如诊断脚本只在 Phase 1 运行， 列宽核算脚本只在 Phase 3 调用。 仅在真正需要时加载，不浪费上下文。

3.3 执行流程

1
诊断
diagnose.py
→
2
定因
root-cause-catalog
→
3
修复
calc_col_widths.py
→
4
验证
verify_pdf.py
→
5
报告
template-report

用户一句话触发，Skill 自动跑完五阶段闭环，无需人工迭代。

3.4 六类典型根因

编号 根因 典型表现
A Markdown 管道剥离 inline style 属性 源码里的 <div style="..."> 完全失效
B CSS 显式规则优先于继承 基础样式的 td/th 字号覆盖父级设置
C DITA 转换剥离 <col> 的 class 属性 col.col-xxx 选择器全部匹配失败
D 表头误用 nowrap + overflow:hidden 表头文字被裁，出现 ? 等残缺字符
E 基础样式设置 min-width: 60px 12 列 × 60px 直接撑爆页面宽度
F 命名页不继承默认页的边角框 横向页的品牌标语、logo 全部消失

3.5 兼容性矩阵

模型 / 平台 支持方式 备注
Claude Code / Desktop 原生 Agent Skills 支持 官方推荐路径 ~/.claude/skills/
Qwen Code 原生 skill 目录发现 置于 .qwen/skills/ 下
DeepSeek Harness 原生 skill 系统 通过 ctx.skills 发现
GLM / Kimi / MiniMax 通过 Claude Code 兼容客户端接入 与 Claude Code 同路径
其他 OpenAI 兼容框架 读取 SKILL.md frontmatter 按渐进式披露机制加载
设计原则： Skill 不依赖任何模型特有的 API。所有脚本使用标准 Python 3.9+， 操作对象是文件，而非模型调用。这意味着本 Skill 可以在任何遵循 Agent Skills 规范的平台上运行，无需为不同模型维护多套版本。

四、使用示例

用户在任意兼容模型中提出：

// 用户输入 "数据类型配置表在 PDF 里溢出了，最右边一列被裁掉，表头也显示不全。"

模型自动触发本 Skill，依次执行：

[Phase 1] 运行 diagnose.py → 发现根因 C + D + E [Phase 2] 查阅 root-cause-catalog.md → 确认修复策略 [Phase 3] 运行 calc_col_widths.py → 生成 12 条列宽规则 [Phase 4] 生成 PDF → 运行 verify_pdf.py → 全部 PASS [Phase 5] 输出结构化修复报告

整个过程无需人工迭代，模型按 Skill 定义的标准化流程完成诊断、修复、验证闭环， 平均耗时相比人工方式缩短一个数量级。