Agent Skill on KnightLi的博客

使用AI维护Hugo多语言博客的Agent Skill

Mon, 06 Apr 2026 10:00:00 +0800

如果你在维护 Hugo 多语言博客，经常会遇到一个高频痛点：

中文写完后，需要同步生成英文和繁体版本
三个语言文件要保持结构一致
front matter 既要翻译又要遵守 Hugo 格式

sync-post-translations 就是为这个场景设计的 Agent Skill。

这个技能解决什么问题

sync-post-translations 的定位很清晰：

以 index.zh-cn.md 为源文件
在同目录生成或更新 index.en.md、index.zh-tw.md
保持 Markdown 结构一致
对 front matter 执行明确规则（尤其是 date、slug）

适用触发词示例：

“同步翻译英文繁体”
“把这篇文章同步成英文和繁体”

技能目录结构

.\sync-post-translations\
├─ SKILL.md
└─ agents\
   └─ openai.yaml

核心代码一：SKILL.md

下面是该技能的核心规则文件：

---
name: sync-post-translations
description: 将 Hugo 文章从简体中文源文件（`index.zh-cn.md`）同步翻译为英文（`index.en.md`）和繁体中文（`index.zh-tw.md`）。当用户提出“en 繁体”“同步翻译英文繁体”或要求同时生成/更新两种语言版本且需保持 front matter 与 Markdown 结构一致时使用。
---

# 同步文章翻译

使用此技能为同一篇文章生成或更新多语言版本。

## 工作流程

1. 在目标文章目录中定位源文件 `index.zh-cn.md`。
2. 读取完整 front matter 与正文内容。
3. 在同目录创建或更新 `index.en.md` 与 `index.zh-tw.md`。
4. 确保三语结构对齐后执行 Hugo 构建检查。

## 翻译规则

1. 严格保留 `slug` 原值。
2. `date` 统一规范为 Hugo 常用带时间格式（RFC3339），示例：`2026-04-05T10:00:00+08:00`。
3. 自然翻译以下 front matter 字段：`title`、`description`、`tags`、`categories`。
4. 保持 Markdown 结构不变：标题层级、列表形态、代码块、链接与命令行示例。
5. 技术标识符保持原样：文件名、CLI 参数、模型名、设备名、URL、包名等。
6. 若 YAML 的 `title` 含有 `:`，必须加引号，避免解析报错。
7. 在不改变语义前提下，使用目标语言自然标点与表达习惯（`en`、`zh-tw`）。

## 输出约定

1. 仅在源文章同目录写入目标文件。
2. 汇报变更的文件路径。
3. 条件允许时执行 `hugo --source . --destination public`，并反馈通过/失败；失败时给出关键报错行。

## 质量标准

1. 全文术语前后一致。
2. 避免机器直译感，优先可发布文风。
3. 章节内容完整，不省略示例、注意点与总结。

核心代码二：agents/openai.yaml

这个文件定义了技能在 Agent 侧的展示和默认提示词：

interface:
  display_name: "同步文章翻译"
  short_description: "生成或更新 EN + ZH-TW 翻译稿"
  default_prompt: "使用该技能在同一 Hugo 文章目录中，从 `index.zh-cn.md` 生成或同步 `index.en.md` 与 `index.zh-tw.md`，保留 `date` 与 `slug`，保持 Markdown 结构一致，并执行 Hugo 构建校验。"

实战调用示例

1) 面向人的自然语言触发

1
2

请把 content/post/2026/04/06/index.zh-cn.md 同步翻译成英文和繁体，
要求 date 用 RFC3339，slug 不变，最后跑 hugo 校验。

2) 你应当期待的输出结果

已更新：
- content/post/2026/04/06/index.en.md
- content/post/2026/04/06/index.zh-tw.md

构建校验：
- hugo --source . --destination public
- 结果：PASS

为什么这些规则很关键

slug 保持不变，能稳定 URL 与历史外链。
date 统一 RFC3339（带时区）可避免 Hugo/主题在时间解析上的歧义。
Markdown 结构不变，能避免翻译后目录、代码块、短代码渲染错位。
技术标识符不翻译，可显著降低“命令不可用/文件名不匹配”问题。

常见坑位与规避

title 里有 : 却没加引号，YAML 会解析失败。
把 --flag、URL、包名翻译了，示例命令会直接失效。
三语标题层级不一致（如中文 ## 变成英文 ###），目录锚点会错位。
只翻译正文不处理 front matter，页面列表与 SEO 信息会异常。

分析 Anthropic 的 Agent Skill docx 功能、代码组成、使用方法与注意事项

Sat, 04 Apr 2026 11:00:00 +0800

Anthropic 的 skills/docx 本质上是一套“让 AI 更稳地处理 Word 文档”的工作规范与脚本工具集。
它不是单纯告诉模型“去写一个 .docx”，而是把 Word 文档处理拆成几条明确路径：新建文档、读取内容、编辑已有文档、处理修订、添加评论、转换格式、校验 OOXML 结构。

如果只看一句话，可以把它理解为：

让 agent 不再把 .docx 当黑盒，而是把它当成 ZIP + XML + Office 兼容性问题来处理。

这个 skill 解决什么问题

普通文本生成模型在处理 Word 文档时，常见问题有几类：

只会输出文本，不会真正生成结构正确的 .docx
修改现有文档时容易破坏 OOXML 结构
遇到批注、修订、评论线程时，不知道该改哪几个 XML
能生成文档，但在 Word、LibreOffice、Google Docs 之间兼容性不稳定
不清楚什么时候该用 pandoc，什么时候该直接解包改 XML

docx skill 的价值就在这里。它把“该怎么做”提前约束好了：

读内容时，优先用 pandoc 或解包
新建 .docx 时，优先用 docx-js
编辑现有 .docx 时，优先走“解包 -> 修改 XML -> 重新打包 -> 校验”
处理接受修订、评论、schema 校验这些细节时，用配套脚本而不是让模型硬编

这套思路非常实用，因为 Word 文档问题往往不是“文字写得对不对”，而是“文件结构是否还能被 Office 正常接受”。

目录和代码组成

这个 skill 大致可以分成四层。

1. 说明层：`SKILL.md`

SKILL.md 是整个 skill 的入口，主要做两件事：

定义触发条件
只要用户需求涉及 Word、.docx、评论、修订、目录、页码、模板、格式化文档等内容，就应该启用这个 skill。
规定工作路径
它明确写出不同任务该走哪条技术路线，而不是每次临场发挥。

从内容看，它既是“使用说明”，也是“操作规范”。
尤其有价值的是里面列出的很多 Word 兼容性规则，比如：

docx-js 默认是 A4，不是 US Letter
横向页面时宽高参数要按它的内部逻辑传
列表不能手工插入 Unicode bullet
表格宽度要同时设置 table 和 cell
图片插入时 type 不能省
生成后要做 validate

这说明作者不是只想“能生成”，而是想要“生成后能稳定打开、稳定渲染、稳定兼容”。

2. Office 包操作层：`scripts/office/*`

这一层负责把 .docx/.pptx/.xlsx 当成 Office Open XML 包来处理。

`unpack.py`

作用是把 Office 文件解包到目录中，并做几件辅助工作：

解压 ZIP 包
对 XML / .rels 做 pretty print
对 .docx 可选执行 merge_runs
对 .docx 可选执行 simplify_redlines
把智能引号转成 XML 实体，降低后续处理风险

它的设计重点不是“简单解压”，而是把文件整理成适合 agent 和人类继续编辑的状态。

`pack.py`

作用是把修改后的目录重新打包成 .docx/.pptx/.xlsx。
打包前还会做两件重要的事：

可选运行校验与自动修复
把 XML 重新压缩整理，去掉无意义空白和注释

如果提供 --original，它会结合 validator 做比对，这一点很关键。
因为很多 Word 修改不是“能压回去就算成功”，而是要确认文档结构和追踪修订语义都还成立。

`validate.py`

这是整个 skill 的质量闸门。
它支持校验：

XML 是否良构
namespace 是否正确
各类 ID 是否唯一
relationship / content type 是否匹配
是否符合 XSD schema
空白保留规则是否正确
插入、删除、评论标记是否合法

对 .docx 来说，这一步几乎是核心能力。
很多看起来“只改了一点 XML”的文档，真正问题都出在这里。

`soffice.py`

这是一个很有工程味道的小工具。
它不是简单调用 LibreOffice，而是为受限环境准备了兼容处理，自动设置 SAL_USE_VCLPLUGIN=svp，在必要时还会构造 shim 解决 AF_UNIX socket 受限的问题。

这说明 skill 的目标环境并不只是“本地桌面手工操作”，而是考虑了 agent、CI、沙箱等自动化环境。

3. Word 专项能力层：评论、修订与 redline

`comment.py`

这个脚本负责给 DOCX 添加评论。
它做的事情比“写一段 comment XML”复杂得多，因为 Word 评论不是单文件机制，而是一组部件协同：

word/comments.xml
commentsExtended.xml
commentsIds.xml
commentsExtensible.xml
document.xml 中的 comment range marker
[Content_Types].xml 与 document.xml.rels 中的关系声明

脚本里已经把这些依赖关系考虑进去了。
如果是第一次添加评论，它会自动补齐模板文件、relationship 和 content types，这能显著降低手工改 OOXML 时的出错率。

`accept_changes.py`

这个脚本的目标非常明确：接受所有修订。
实现方式不是自己硬改 XML，而是通过 LibreOffice headless + Basic macro 调 .uno:AcceptAllTrackedChanges。

这个选择很稳妥，因为“接受修订”在 Word 语义里并不只是删掉 <w:ins> / <w:del> 那么简单，直接改 XML 很容易留下边角问题。
借助 Office 引擎自身完成这一步，兼容性通常更好。

`validators/redlining.py`

这是 skill 里我觉得最值得注意的一部分。
它会把“某个作者的修订”从原始文档和修改后文档中分别剥离，再比较正文文本是否一致，用来判断修订是否被正确地包裹在 tracked changes 结构里。

换句话说，它不只是检查 XML 格式，而是在检查“你是不是按修订语义编辑了文档”。

这对 agent 特别重要，因为 AI 很容易做出这种错误：

直接改正文，但没有包进 <w:ins> / <w:del>
在别人的插入或删除结构里改坏层级
让最终文本变了，但 redline 逻辑不成立

这个 validator 就是在挡这种“表面可用、语义错误”的问题。

4. Schema 与辅助层：`schemas/`、`helpers/`、`templates/`

`schemas/`

这里放的是一整套 OOXML / ECMA / Microsoft 扩展相关的 XSD。
这意味着 skill 的校验不是拍脑袋写规则，而是尽量基于正式 schema 约束。

`helpers/`

这里主要是：

merge_runs.py
simplify_redlines.py

作用是把解包后的 Word XML 做适度清理，让结构更稳定、更容易编辑和比较。

`templates/`

这里存放评论功能依赖的 XML 模板，如：

comments.xml
commentsExtended.xml
commentsIds.xml
commentsExtensible.xml
people.xml

这类模板文件很重要，因为很多 Word 部件不是“缺了就自动补”，而是必须按 Office 能接受的格式预置。

典型使用方法

从 SKILL.md 给出的建议来看，这个 skill 最适合下面几种工作流。

场景一：读取或分析现有 DOCX

如果目标是提取内容、阅读结构、转成 Markdown，优先用：

`1`	`pandoc --track-changes=all document.docx -o output.md`

如果要看底层 XML，则用：

`1`	`python scripts/office/unpack.py document.docx unpacked/`

前者适合读内容，后者适合看结构。

场景二：新建 DOCX

skill 的建议不是手搓 OOXML，而是用 docx-js 生成：

`1`	`npm install -g docx`

然后生成文档后再校验：

`1`	`python scripts/office/validate.py doc.docx`

这条路线适合：

报告
memo
letter
有标题、目录、页脚、分页、表格的正式文档

场景三：编辑已有 DOCX

这是整个 skill 最核心的工作流：

1
2
3

python scripts/office/unpack.py document.docx unpacked/
# 修改 unpacked/ 下的 XML
python scripts/office/pack.py unpacked/ output.docx --original document.docx

这里的关键不是“修改 XML”，而是最后那步 --original。
它让系统能在回包时做 schema 和 redline 层面的验证，而不是盲目打包。

场景四：接受所有修订

`1`	`python scripts/accept_changes.py input.docx output.docx`

这一步依赖 LibreOffice。
适合用于把已审阅文档整理成“干净版本”。

场景五：添加评论

1
2

python comment.py unpacked/ 0 "Comment text"
python comment.py unpacked/ 1 "Reply text" --parent 0

这里要特别注意：脚本只是把评论内容和必要的评论部件加进去，实际还需要按注释说明，在 document.xml 中加上 comment range marker，才能把评论真正挂到对应文本范围上。

这个 skill 最值得注意的几个坑

如果只是快速浏览 SKILL.md，很容易低估其中“兼容性规则”的价值。
下面这些点尤其值得记住。

1. `.docx` 不是文本文件，而是 Office 包

最危险的误区就是把它当成“一个带格式的文本文件”。
实际上你改的可能同时涉及：

正文 XML
relationships
content types
comments / people / ids
schema 约束
修订语义

所以这个 skill 才会强调“解包 - 编辑 - 校验 - 回包”。

2. `docx-js` 能生成文档，但不保证默认参数符合你的目标

SKILL.md 里强调了很多默认值陷阱，例如：

默认纸张是 A4
横向页面宽高处理有内部逻辑
列表不能直接塞字符 bullet
表格宽度要双重声明
Google Docs 对百分比宽度兼容性差

这说明生成工具只是起点，不是最终质量保证。

3. 评论和修订都不是单点修改

无论是 comment 还是 tracked changes，都不是改一处 XML 就完事。
你需要维护多个部件之间的一致性，这也是 skill 把这些动作脚本化的原因。

4. “能打开”不等于“改对了”

一个文档能被 Word 打开，不代表结构就是对的。
很多错误只会在这些场景暴露：

再次编辑时崩
审阅模式异常
批注丢失
Google Docs 打开后布局错乱
重新接受修订时报错

因此 validate.py 和 pack.py --original 非常重要。

5. 依赖外部工具时要提前准备环境

这个 skill 依赖几类外部工具：

pandoc
LibreOffice / soffice
docx-js
Python 依赖，如 defusedxml、lxml

如果环境里缺这些工具，agent 即使知道流程，也无法完整执行。

这个 skill 适合什么，不适合什么

适合

批量生成 Word 报告
结构化生成正式文档
自动化修改 .docx
保留或处理 tracked changes
自动添加批注
把 Word 文档纳入脚本或 agent 工作流

不太适合

单纯导出 PDF 的简单场景
只需要纯文本内容，不关心 Word 格式
完全依赖手工可视化编辑的工作方式
希望零依赖、零环境准备就完成全部 Word 自动化

总结

Anthropic 的 skills/docx 强项不在“会生成 Word”，而在“知道 Word 为什么容易出问题，并提前把问题拆开处理”。
它把文档生成、底层 XML 编辑、修订语义、schema 校验、Office 兼容性这些原本很零散的知识，整理成了一条可执行的工作流。

如果你只是偶尔导出一份简单文档，它可能显得有点重。
但只要场景涉及现有 .docx 修改、评论、修订、自动化批处理或兼容性要求，这套 skill 就很有价值，因为它补上的恰恰是 AI 最容易忽略、而 Office 文档最容易翻车的那部分细节。

简单总结就是：

SKILL.md 负责告诉 agent 该走哪条路
scripts/office/* 负责解包、回包、校验和 Office 兼容
comment.py 与 accept_changes.py 负责 Word 专项能力
schemas/ 与 validators 负责把“看起来能用”提升到“结构上靠谱”

代码地址：https://github.com/anthropics/skills/tree/main/skills/docx