用Claude Code技能自动生成规范Word报告实战

1. 先把需求看清楚：这个案例到底解决什么问题

1.1 从“手动写报告”到“自动出报告”的转变

这个案例我前前后后折腾了大概三天，核心就一件事：让 Claude Code 在收到一堆原始素材之后，自动产出排版规范、结构完整、可以直接交付的 Word 报告。

可能有人会问，直接用 ChatGPT 网页版生成一段 Markdown 再手动复制到 Word 不行吗？行，但如果报告每周都要出、格式要求还特别死板，比如固定的一级标题黑体三号、二级标题黑体四号、正文宋体小四、表格三线表样式、页码位置固定，那你就会发现，靠人工搬运的每一分钟都是浪费。这个案例里，Claude Code 做的事情不是“生成一段文字”，而是“调用我预先定义好的技能”，把原始数据、会议纪要、测试日志甚至图片，整理成一份带目录、带样式、带自动编号的 Word 文件。

先说结论：这套方案的实测效果，是把原本手工需要 1 到 2 小时的报告整理工作，压缩到了 3 到 5 分钟。中间踩过的坑不少，尤其是 Word 表格列宽、公式图片、空白页这类经典问题，后面我会逐条展开。

1.2 为什么选 Claude Code 而不是别的自动化方案

市面上做自动化的工具很多，脚本、Excel 宏、Python 模板、低代码平台，都能做报告生成。但这个案例选 Claude Code，是因为它的“智能体”模式天然适合处理非结构化输入。

手动写脚本方案的问题是：报告的内容结构稍微一变，脚本就要跟着改。比如这个月多了一个“风险项”章节，下个月的报告需要把“结论”提到前面，模板脚本维护成本立刻就上来了。Claude Code 的优势在于，它本身是一个运行在终端里的 AI 智能体，你可以用自然语言给它分配任务，它自己会决定先读哪个目录、调用哪个函数、检查哪份材料，再按照你定义的技能规范输出结果。

这里需要特别提一下“技能”这个概念。在 Claude Code 的机制里，技能不是一段简单的 Prompt，而是一个带目录结构、带说明文件、附带可执行脚本的完整工具包。你可以在项目里通过SKILL.md文件来描述这个技能做什么、有哪些约束、需要调用哪些脚本。Claude Code 读到这个技能之后，会把技能里的规则当作“工作手册”来执行。这跟 CTFHub 技能树那种“知识地图”完全是两种东西——CTFHub 技能树是给人学习用的体系化知识索引，而这里的技能是给 AI 智能体用的工作流程定义。两者名字里都带“技能”，但面向对象和用途完全不同。

2. 环境准备与技能设计：Claude Code 侧的核心配置

2.1 安装 Claude Code 与模型接入

安装 Claude Code 本身不难，如果你用过 npm，那基本就是一条命令的事：

npm install -g @anthropic-ai/claude-code

装完先跑一下claude --version确认版本号正常，然后直接输入claude进入交互终端。首次启动会让你登录授权，这里要注意，服务的可用性跟区域有关。如果你在启动时看到类似“might not be available in your country”的提示，说明当前网络环境不在官方支持范围内。这种情况下最稳妥的做法，是确认官方支持地区列表，或者等待服务覆盖范围扩展后再试。

安全提示先放最前面：不要为了绕过地区限制去折腾代理连接服务器、虚拟机镜像绕行、DNS 解析调整之类的手段。这类操作既不稳定，也容易踩法律和合规的线，解决问题的正路是选一个官方支持的区域或等待服务扩展。

配置完成后，还可以在~/.claude/settings.json里做个性化调整，比如默认模型、输出风格、是否需要自动接受工具调用等。我的建议是，新手期不要开启全自动工具调用，先让它每一步都问你一遍，确认它的行为习惯之后再放权。

2.2 技能的设计思路：把“算报告”变成“工厂流水线”

技能设计是这个案例里最核心的环节。我的思路是：把报告生成拆成四个阶段——素材解析、框架搭建、内容填充、格式渲染。

• 素材解析：读取用户指定的文件夹或文件，识别出里面的数据表、文本记录、图片素材。
• 框架搭建：根据报告类型，生成固定的章节结构，比如背景、数据概览、问题分析、结论建议。
• 内容填充：把解析出来的数据放进去，调用图表生成脚本，把图表路径写进报告框架。
• 格式渲染：最后统一调用定制好的 Word 生成脚本，保证每个标题、每个表格都符合规范。

这四步如果不拆分，全部塞进一个 Prompt 里让 Claude Code 自由发挥，效果会非常不稳定。它可能这次生成的 Markdown 结构很好，下次就输出一堆不规范的内容。拆分成技能之后，每个环节都有明确输入输出，任何一步出错都能单独排查。

2.3 技能目录结构与 SKILL.md 的写法

技能的本质其实是一个约定目录。我在项目里建了这样的结构：

skills/ report-generator/ SKILL.md scripts/ generate_docx.py chart_render.py data_parser.py templates/ report_template.docx cover_page.docx assets/ example_output.docx

SKILL.md是给 Claude Code 看的说明书，一定要写得像“给新员工看的操作手册”，不能太抽象。以下是我实际在用的缩减版：

# 技能名称：报告生成器 ## 技能目标 根据用户提供的素材目录，自动生成一份符合 XX 企业标准的 Word 周报。 ## 触发条件 当用户提到“生成周报”“出报告”“自动报告”时使用本技能。 ## 工作流程 1. 首先调用 scripts/data_parser.py 解析输入目录下的所有 .xlsx / .csv / .txt 文件。 2. 如果解析失败，立即返回错误信息，不要继续后续步骤。 3. 根据解析结果调用 scripts/chart_render.py 生成图表，保存到临时目录。 4. 最后调用 scripts/generate_docx.py 生成 Word 报告。 ## 格式规范 - 一级标题：黑体三号，居中 - 二级标题：黑体四号，左对齐 - 正文：宋体小四，1.5 倍行距 - 表格：标准三线表 - 页脚：页码居中 ## 关键约束 - 不允许修改模板文件 templates/report_template.docx - 生成的报告必须包含封面、目录页、正文、附录四个部分 - 遇到任何数据缺失，请在报告“风险项”章节中明确标注

写完这个文件之后，每次在 Claude Code 对话里提到“生成周报”，它就会自动读取该技能并按照里面的约束执行。这里有一个非常值得记录的细节：如果技能文件写得像“作文提纲”，Claude Code 就会自由发挥；但如果写得像“SOP 操作流程”，它的输出质量会稳定得多。跟人共事的道理是一样的，规则越清晰，产出越可控。

3. 实操：让 Claude Code 真正生成带格式 Word 报告

3.1 用 python-docx 控制样式、表格与分页

技能里的核心脚本是generate_docx.py，基于 python-docx 实现。用这个库而不是直接让 Claude Code 自己拼 XML，是因为它抽象层次合适，既能控制样式，又不像底层操作那样容易出错。

先看如何控制标题样式。python-docx 默认模板的样式名跟 Word 中文版不完全一致，所以最直接的方式是先加载已有的模板，再修改样式：

from docx import Document from docx.shared import Pt from docx.enum.text import WD_ALIGN_PARAGRAPH doc = Document("templates/report_template.docx") styles = doc.styles # 修改一级标题样式 h1 = styles['Heading 1'] h1.font.name = '黑体' h1.font.size = Pt(16) # 三号约等于16pt h1.font.color.rgb = RGBColor(0, 0, 0) h1.paragraph_format.alignment = WD_ALIGN_PARAGRAPH.CENTER # 修改正文样式 normal = styles['Normal'] normal.font.name = '宋体' normal.font.size = Pt(12) # 小四约等于12pt normal.paragraph_format.line_spacing = 1.5

这里有一个容易踩坑的点：font.name = '黑体'只设置了西文字体，中文字体需要在rPr元素里额外指定w:eastAsia，否则生成的 Word 文档里中文仍然显示默认字体。

from docx.oxml.ns import qn def set_font(run, name_cn, name_en, size, bold=False): run.font.name = name_en run._element.rPr.rFonts.set(qn('w:eastAsia'), name_cn) run.font.size = size run.font.bold = bold

这个函数是我写完整套脚本之后总结出来的通用工具，后面的标题、正文、表格单元格文字都靠它来统一设置字体。

3.2 表格列宽设置：poi 是 Java 的标准答案

有朋友在评论区问过“Java POI 能生成图表吗”，答案是能，POI 完全可以操作 Word 文档里的图表对象，但开发周期比 Python 长很多。如果你已经在用 Claude Code 做自动化，脚本语言选 Python 会顺手得多。不过涉及 Word 表格列宽问题的时候，Python 和 Java 的思路是通用的。

python-docx 里设置表格列宽，不能只设置column.width，因为 Word 表格的宽度同时受单元格、表格布局、网格列三个因素影响。正确写法是这样：

table = doc.add_table(rows=len(data), cols=3) table.style = 'Table Grid' # 关闭自动调整 table.autofit = False # 设置每个单元格的宽度 widths = [C