前段时间大家都在传“Vibe Coding”（氛围感编程），仿佛写代码就是喝着咖啡动动嘴皮子。但作为技术人，我们不仅要懂“氛围”，更要懂“原理”。
Anthropic 官方给 Claude 定义的excel skill。 这不仅仅是一段代码，我认为它是大模型与实体文件交互的优秀范例。很多人觉得给 AI 加个功能就是写个 Function Call，但看了这份源码，你会发现——原来官方是这样教 AI 玩转 Excel 的。
这个 skill 把“如何写一个好的 Claude Skill”的套路暴露得一清二楚：整个仓库没有任何花里胡哨的框架，核心就靠一份结构良好的说明文档 + 少量配套脚本，就把复杂的 Excel 场景跑通了。
核心架构图
下面是核心要点目录：
01、在 SKILL.md 中描述“行为规约层”：零公式错误的铁律
02、用反例教学：用错误代码“调教”模型
03、为了省 Token 的“探针”设计
04、错误处理的“反弹机制
05、用 LibreOffice + recalc.py 做“结果兜底校验闭环”
源码核心要点
01、在 SKILL.md 中描述“行为规约层”：零公式错误的铁律
源码（节选）：
### Zero Formula Errors
- Every Excel model MUST be delivered with ZERO formula errors (#REF!,#DIV/0!,#VALUE!,#N/A,#NAME?)
### Formula Construction Rules
#### Assumptions Placement
- Place ALL assumptions in separate assumption cells
- Use cell references instead of hardcoded values in formulas
- Example: Use =B5*(1+$B$6) instead of =B5*1.05
#### Formula Error Prevention
- Verify all cell references are correct
- Check for off-by-one errors in ranges
- Ensure consistent formulas across all projection periods
- Test with edge cases (zero values, negative numbers)
- Verify no unintended circular references
### Formula Verification Checklist
- **Test 2-3 sample references**: Verify they pull correct values before building full model
- **Row offset**: Excel rows are 1-indexed (DataFrame row 5 = Excel row 6)
- **Division by zero**: Check denominators before using `/` in formulas (#DIV/0!)
- **Cross-sheet references**: Use correct format (Sheet1!A1) for linking sheets
解读：
这段看似只是“写文档”，本质上是在给 Claude 加一层领域 DSL（领域规则语言）：
- • 把“零公式错误”设成强约束，模型在生成方案和代码时会自动偏向更保守、更审慎的写法。
- • 把“假设分离”、“禁止硬编码”这类 Excel best practice，用 checklist 的形式具体化，等于告诉模型：你不仅要算对，还要“会建模”。
- • 把常见坑（off-by-one、行列偏移、交叉表引用）显式写出来，就是在给模型“注入经验”，减少那种 LLM 最容易犯的小失误。
启示：
- • 下次自己写 Claude Skill 时，可以照抄这个套路：
- • 不要只写“这是个什么能力”，要写清楚“什么是错误的行为”（比如：禁止硬编码、禁止修改既有模板格式）。
- • 用 checklist 的形式，把“容易出错的细节”列清楚——模型会真的按这个 checklist 来思考和自检。
- • 把“业务经验”变成显式的规则文本写进 SKILL.md，而不是心里默念“希望模型懂”。
换句话说：好的 Skill，不是多长代码，而是把“人类专家的职业习惯”写成一份可执行的行为约束。
02、用反例教学：用错误代码“调教”模型
源码（节选）：
# ❌ WRONG - Hardcoding Calculated Values
# Bad: Calculating in Python and hardcoding result
total = df['Sales'].sum()
sheet['B10'] = total # Hardcodes 5000
# Bad: Computing growth rate in Python
growth = (df.iloc[-1]['Revenue'] - df.iloc[0]['Revenue']) / df.iloc[0]['Revenue']
sheet['C5'] = growth # Hardcodes 0.15
# ✅ CORRECT - Using Excel Formulas
# Good: Let Excel calculate the sum
sheet['B10'] ='=SUM(B2:B9)'
# Good: Growth rate as Excel formula
sheet['C5'] ='=(C4-C2)/C2'
解读：
这里有两个非常妙的点：
- • 用“错误代码示例”来塑造行为边界：它不是抽象地说“不要硬编码”，而是给出一整段“错误写法”+ 注释 # Bad，这对 LLM 来说是非常强的负样本信号。
- • 把“好代码”写成模板，让模型直接复用模式：“坏写法”用 Python 先算再写值；“好写法”则把 Excel 视为计算引擎，Python 只写公式字符串。模型以后在类似场景自然就会 copy 这种 pattern。
启示：
写 Skill 时，不要吝啬“反例”：
- • 针对你特别怕模型犯错的地方，比如：面对金额字段乱用 float 精度、ID 字段自动转 int、HTML 乱拼字符串，最好写出 “错误示范 + 正确示范” 两段代码。
- • 给出典型模式，而不是只讲原则。LLM 对“模式”比对“抽象说教”敏感得多。
可以给 Claude 的 API / Agent 写 Skill 时，预留一个章节专门叫：“❌ 常见错误写法 / ✅ 推荐写法”，用这个方式强行把模型“调到你想要的风格”。
03、为了省 Token 的“探针”设计
我们通常写 Excel 读取工具，上来就是read_excel。但官方 Skill 的定义极其克制。
源码（节选）：
# 这是一个 Tool 定义的抽象逻辑
definspect_sheet_head(filepath, sheet_name, n_rows=5):
"""
Reads the first n_rows of the sheet to understand structure.
Crucial: Converts output to Markdown Table for LLM readability.
"""
df = pd.read_excel(filepath, sheet_name=sheet_name, nrows=n_rows)
# 重点：转化为 LLM 最容易理解的 Markdown 格式，且只给表头和前几行
returndf.to_markdown(index=False)
解读：
这就好比你去相亲，不会上来就查户口本（全量读取），而是先看个照片（Head）。 这段逻辑的精妙之处在于 nrows=5 和 to_markdown()。
- • Token 经济学：一个 10万行的 Excel 可能有 500M Token，直接读必死。只读前 5 行，消耗极低，但足以让 LLM 理解列名和数据格式（是日期还是数字）。
- • 格式对齐：LLM 训练数据里有大量 Markdown 表格，用 to_markdown 输出，模型理解的准确率远高于 CSV 或 JSON 格式。
启示：
做 RAG 或文档分析时，永远提供一个 peek (预览) 接口。让 AI 自己决定需不需要读更多，而不是一次性把饭喂到嘴里噎死它。
04、错误处理的“反弹机制
虽然代码里通常包含 Python 的try-except，但 Skill 里的设计亮点在于如何把错误反馈给 LLM。
源码（节选）：
try:
result =exec(generated_pandas_code)
returnresult
exceptKeyErrorase:
# 不只是返回 Error，而是返回“引导性”错误信息
returnf"Error: Column{e}not found. Please check column names using `inspect_sheet` and retry."
exceptExceptionase:
returnf"Execution failed:{str(e)}. Review your code logic."
解读：
普通程序报错是给程序员看的（Stack Trace），但 Agent 的报错是给 AI 看的。 这里的 Highlights 在于：报错信息本身就是一条 Prompt。 当发生 KeyError 时，工具不仅仅说“错了”，而是建议“你去用 inspect_sheet 查一下再试”。这让 LLM 具备了自我修复（Self-Healing）的能力。
启示：
当你的 Tool 报错时，不要直接抛出异常栈。**把异常翻译成“下一步的行动建议”**返回给模型。让模型觉得：“噢，我懂了，我换个姿势再来一次。”
05、用 LibreOffice + recalc.py 做“结果兜底校验闭环”
调用示例：
python recalc.py output.xlsx 30
The script:
- Automatically sets up LibreOffice macro on first run
- Recalculates all formulasinall sheets
- Scans ALL cellsforExcel errors (#REF!,#DIV/0!, etc.)
- Returns JSON with detailed error locations and counts
Example output:
{
"status":"success", // or"errors_found"
"total_errors": 0, // Total error count
"total_formulas": 42,
"error_summary": { // Only presentiferrors found
"#REF!": {
"count": 2,
"locations": [
"Sheet1!B5",
"Sheet1!C10"
]
}
}
}
解读：
这段设计直接把 Skill 从“写完就完事”提升到“可验证的工程流程”：
- • openpyxl 写入的公式只是字符串，不会自动计算，必须借助 Excel/LibreOffice 引擎重算，这里用一个 recalc.py 做一键自动化。
- • 脚本不仅重算，还遍历所有单元格，把#REF!、#DIV/0! 等错误收集成 JSON，等于给模型一个“测试报告”。
- 3. 读 JSON，如果 status = errors_found，就自动定位到对应 cell 再修一次公式。
从 Skill 设计思路看，这是一个很典型的模式：
“LLM 生成 → 外部程序验证 → LLM 读取验证结果自修正”。
而且返回的是结构化 JSON，而不是一堆日志字符串，这一点非常关键——模型可以像处理普通数据那样去解析、统计、再生成修复代码。
启示：
写 Claude Skill 时，如果你的领域有现成的“权威校验器”，比如：JSON schema 校验器、TypeScript 编译器、SQL linter、Markdown 链接检查器，强烈建议加上。
让 Skill 明确规定：
写完必须跑校验工具；
- • 校验工具输出结构化结果（JSON / YAML）；
- • 出现错误时要按某个策略重试（比如只改有问题的语句）。
Skill 不是只教“怎么写”，还要教“写完怎么验，验完怎么改”。
一句话概括：优秀的 Skill，不只输出结果，还要自带 CI。
总结与思考
这个 xlsx Skill 的局限也很明显：
- 1. 逻辑主要依赖说明文档 + 一些示例，没有复杂的代码抽象，真正的“智能”还是在 Claude 本身，skill 更像“超长 system prompt + 工具协议”。
- 2. 所有最佳实践都偏向“专业财务/建模”风格，比如指定颜色编码、格式规则，可能不适合所有 Excel 轻量应用场景，需要你在自定义 Skill 时做适当裁剪。
但作为写 Skill 的模板，它传递了一个非常重要的理念：
一个好的 Claude Skill，本质上是“把领域专家的职业习惯写死成规约 + 用外部工具把结果验到没毛病”。
如果只用一句话收尾——
不要指望 Claude 自然长成专家，而是用一份好的 SKILL.md，把它调教成你想要的那种专家。
