Claude官方Skill-Excel源码拆解，学习如何写一个好的Skill

前段时间大家都在传“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 定义的抽象逻辑
def inspect_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 格式，且只给表头和前几行
    return df.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)
    return result
except KeyError as e:
    # 不只是返回 Error，而是返回“引导性”错误信息
    return f"Error: Column {e} not found. Please check column names using `inspect_sheet` and retry."
except Exception as e:
    return f"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 formulas in all sheets
- Scans ALL cells for Excel 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 present if errors found
    "#REF!": {
      "count": 2,
      "locations": [
        "Sheet1!B5",
        "Sheet1!C10"
      ]
    }
  }
}

解读：
这段设计直接把 Skill 从“写完就完事”提升到“可验证的工程流程”：

• • openpyxl 写入的公式只是字符串，不会自动计算，必须借助 Excel/LibreOffice 引擎重算，这里用一个 recalc.py 做一键自动化。
• • 脚本不仅重算，还遍历所有单元格，把 #REF!、#DIV/0! 等错误收集成 JSON，等于给模型一个“测试报告”。
• • 在上层流程中，Claude 可以：

1. 1. 先按规范写 Excel；
2. 2. 跑 recalc.py；
3. 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. 1. 逻辑主要依赖说明文档 + 一些示例，没有复杂的代码抽象，真正的“智能”还是在 Claude 本身，skill 更像“超长 system prompt + 工具协议”。
2. 2. 所有最佳实践都偏向“专业财务/建模”风格，比如指定颜色编码、格式规则，可能不适合所有 Excel 轻量应用场景，需要你在自定义 Skill 时做适当裁剪。

但作为写 Skill 的模板，它传递了一个非常重要的理念：

一个好的 Claude Skill，本质上是“把领域专家的职业习惯写死成规约 + 用外部工具把结果验到没毛病”。

如果只用一句话收尾——

不要指望 Claude 自然长成专家，而是用一份好的 SKILL.md，把它调教成你想要的那种专家。