大家好，我是玄姐。

Claude 的 Skills（技能）机制让 AI 能够像“安装插件”一样动态获得新能力。但一个生产环境可用的 Skill，绝不仅仅是几句 Prompt 那么简单。

最近，我们深入扒了 Claude 官方开源的 Excel Skill (xlsx)源码。这个 Skill 极其强悍，它能让 Claude 稳定、精准地生成复杂的 Excel 表格，而不会出现幻觉或格式错误。

今天，我们就像做手术一样，从代码实现到架构设计全方位拆解它。看完这篇，你也能写出架构优雅、稳定性爆棚的 Agent 技能。

一、顶层设计『Skill 的“三驾马车”』

一个标准的 Claude Skill 并不是一个孤立的文件，而是一个工程化的文件夹。官方 Excel Skill 的目录结构非常清晰：

skills/└── xlsx/    ├── SKILL.md          # 核心大脑：定义元数据和自然语言指令    ├── _xlsx_writer.py   # 强力肌肉：执行具体逻辑的 Python 脚本    └── requirements.txt  # 环境依赖：确保代码能跑通

💡 设计哲学：

• SKILL.md (文科生思维)：负责“意图识别”与“调度”。告诉 AI 什么时候用这个技能，以及怎么传参。

• Python 脚本 (理科生思维)：负责“执行”与“落地”。处理枯燥、容错率低的逻辑（如二进制文件生成）。

二、架构核心『“三层汉堡”设计模式』

如果说目录结构是骨架，那么架构模式就是灵魂。

许多开发者习惯让 AI 直接生成 Python 代码并执行（比如让 AI 写 pandas 代码）。但 Claude 官方采用了更高级的“声明式架构” (Declarative Architecture)，引入了“中间层表示 (Intermediate Representation, IR)”的概念。

我们可以将其拆解为三个关键层级：

1. 意图层 (The Intent Layer) - User -> LLM

这是最上层。用户的需求通常是模糊的：“帮我把这些销售数据做个报表，标红亏损的项。”

• Claude 的任务：不写 Python 逻辑，而是将“模糊需求”翻译成“结构化数据”。

• 架构亮点：LLM 专注理解，不关注实现。

2. 协议层 (The Protocol Layer) - JSON Schema

这是架构的秘密武器。官方定义了一套严格的 JSON 结构。Claude 生成的不是 .xlsx 文件，也不是生成文件的 Python 代码，而是一个 JSON 配置单：

// Claude 实际生成的“中间件”代码片段{  "sheets": [    {      "name": "Q3 Sales",      "data": [ ["Item", "Cost"], ["Apple", 500] ],      "styles": { "header": { "bold": true, "bg_color": "#CCCCCC" } }    }  ]}

💡 为什么要这么设计？（关键考点）

• 稳定性：让 LLM 写复杂的 Python 逻辑（引入库、循环写入）极易出错；但让 LLM 写 JSON，准确率接近 100%。

• 安全性：JSON 是静态数据，避免了 AI 生成恶意代码运行的风险。

• 解耦：如果未来想换成 Google Sheets，只需修改后端脚本，Prompt 和 JSON 结构完全不用变。

3. 执行层 (The Execution Layer) - Python Script

即 _xlsx_writer.py。

• 任务：它是一个无状态 (Stateless)的转换器。它盲目信任协议层传来的 JSON，利用 xlsxwriter 库将其“渲染”成二进制文件。

4. 架构执行流程

三、源码实战『如何落地？』

理解了架构，我们再看代码实现，就会豁然开朗。

1. SKILL.md 的“防呆设计”

SKILL.md 是入口。官方在 Prompt 中做了一个极其聪明的引导：

"当需要创建 Excel 时，不要尝试直接输出文件内容。请构造一个描述 Sheet、列头、数据的 JSON 对象，传给 _xlsx_writer.py。"

这直接禁用了 AI “胡乱发挥”的可能性，强制它进入我们设计好的协议层。

2. Python 脚本的“错误反馈环”

_xlsx_writer.py 不仅负责写入，还负责报错。 如果 JSON 格式不对，脚本会打印具体的 Traceback。Claude 能够读取这些报错，并进行“自我反思”和重试。

数据流转全景图 (Data Flow)：

• Input: 用户输入需求。

• Parsing: Claude 分析需求，构建 JSON 中间态数据。

• Bridge: 调用 create_excel_file(json_data)。

• Rendering: Python 脚本接收 JSON -> 渲染成 .xlsx。

• Output: 返回文件路径。

四、总结：如何写好一个 Skill？

通过拆解官方 Excel Skill，我们总结出“高质量 Skill 开发 4 条军规”：

🔸 军规一：动静分离 (Logic vs. Content)

不要让 Prompt 承担计算。

❌ 错误：让 AI 算斐波那契数列。

✅ 正确：Python 算好，AI 调用。

🔸 军规二：定义清晰的接口 (Schema First)

采用“中间层表示”模式。不要让 Agent 直接操作底层 API，而是让 Agent 编写“配置文件”（JSON），再由代码去解释执行。

🔸 军规三：元数据决定生死 (Metadata is Key)

SKILL.md 里的 description 是 Skill 被 AI 检索到的唯一线索，要像写 SEO 一样写它。

🔸 军规四：善用错误反馈 (Error Loop)

脚本报错必须打印到 stdout。让 AI 看到错误，是 Agent 自我修正的关键。

五、结语

官方 Excel Skill 之所以强大，不是因为它用了多复杂的 Prompt，而是因为它展现了Agentic Workflow（代理工作流）的精髓：让 LLM 做调度器，让代码做执行器。

下次写 Skill 时，不妨问自己一句：“这一步逻辑，是不是让 AI 写个 JSON 配置更稳？”

好了，这就是我今天想分享的内容。如果你对构建企业级 AI 原生应用新架构设计和落地实践感兴趣，别忘了点赞、关注噢~

—1—

加我微信

扫码加我👇有很多不方便公开发公众号的我会直接分享在朋友圈，欢迎你扫码加我个人微信来看👇

加星标★，不错过每一次更新！

⬇戳”阅读原文“，立即预约！