参考资料

• Agent Skills 规范
• MCP 规范

Skill（08） - 给 Skill 挂载可执行脚本

读完后，你应能完成以下任务：

• 绘制“Skill（08） - 给 Skill 挂载可执行脚本 / 为什么需要脚本”的关键对象与数据流，解释“精确计算：算一长串数字的总和、复利、统计指标。”，并用源码位置、日志或 Trace 标注证据。
• 为“Skill（08） - 给 Skill 挂载可执行脚本 / 一个直观对比”设计正常与异常输入，验证“Claude 只负责理解需求和解读结果。”，输出首个偏差位置与回归测试结果。
• 实现“Skill（08） - 给 Skill 挂载可执行脚本 / 怎么在技能里挂脚本”的最小代码或配置，检验“Claude 才知道该在这一步调用它，而不是自己算。”，输出命令、结果与 Diff，并说明不适用边界。

本章目标：理解「该让 AI 推理 vs 该让脚本执行」的边界，学会在技能里调用脚本。学完你会得到一个「Skill + Python 脚本」协作的可运行示例。

一、为什么需要脚本

AI 很擅长理解、归纳、生成，但有些活它做起来又慢又容易出错：

• 精确计算：算一长串数字的总和、复利、统计指标。
• 格式转换：Markdown 转 PDF、CSV 转 JSON、图片压缩。
• 确定性处理：批量重命名文件、正则提取、数据校验。
• 调用外部工具：跑测试、查数据库、调 API。

这些活的共同点：有唯一正确答案，且靠确定的步骤就能得到。 让 AI「心算」反而不稳。

正确的分工是：

判断、理解、表达 → 交给 Claude；精确、重复、确定性的执行 → 交给脚本。

技能允许你把脚本放进 scripts/，让 Claude 在合适的时机运行它，而不是自己硬算。

二、一个直观对比

假设技能要「统计一个 CSV 里的销售总额并算平均值」。

没有脚本：Claude 把几百行数字读进上下文，一个个加——慢、烧 token、还可能算错。

有脚本：Claude 运行 python scripts/stats.py sales.csv，脚本秒算出精确结果返回。Claude 只负责理解需求和解读结果。

后者又快又准，这就是脚本的价值。

三、怎么在技能里挂脚本

3.1 第 1 步：把脚本放进 scripts/

sales-analyzer/
├── SKILL.md
└── scripts/
    └── stats.py

3.2 第 2 步：脚本本身写清「用法」

脚本开头用注释或 --help 写明怎么调用，这样 Claude 知道怎么用：

3.3 第 3 步：在 SKILL.md 正文里告诉 Claude 何时、如何运行

## 流程
1. 拿到用户的 CSV 文件路径。
2. 运行脚本进行统计：`python scripts/stats.py <文件路径>`
3. 解读脚本输出，用自然语言向用户汇报，并指出异常（如某天销售额骤降）。

关键点：正文要把「运行脚本」明确写成流程的一步，并说清用什么命令、传什么参数。Claude 才知道该在这一步调用它，而不是自己算。

四、该让 AI 做还是脚本做？决策表

任务	交给谁	为什么
精确的数值计算/统计	🤖 脚本	AI 心算不稳，脚本必准
格式转换（PDF/CSV/图片）	🤖 脚本	有现成库，确定性强
批量/重复的文件操作	🤖 脚本	快且不漏
调用 API、查数据库、跑测试	🤖 脚本	需要真实执行环境
理解用户意图、决定做什么	🧠 Claude	需要判断和灵活性
解读结果、组织语言汇报	🧠 Claude	需要表达能力
处理模糊、开放性问题	🧠 Claude	没有唯一正确答案

一句口诀：

「有唯一正确答案、能用确定步骤算出来」→ 脚本；「需要判断、表达、灵活应变」→ Claude。

五、安全注意（重要）

脚本是真实执行的代码，有副作用，要谨慎：

• 最小权限：脚本只做该做的事，别写「顺手删个文件」这种危险操作。
• 不碰敏感数据：别在脚本里硬编码密钥、密码；需要时从环境变量读。
• 可预期、可回滚：会修改/删除文件的脚本，先想清楚后果，最好先备份或 dry-run。
• 校验输入：脚本要处理「文件不存在、参数缺失」等情况，别一崩了之（看本章 Demo 的写法）。
• 如果平台支持 allowed-tools 等权限字段，可用它收紧技能能调用的工具范围。

六、常见错误

• ❌ 让 AI 硬算本该脚本干的活：几百行数字让 Claude 心算，又慢又错。
• ❌ 脚本没写用法说明：Claude 不知道怎么调、传什么参数。
• ❌ 正文没把「运行脚本」写进流程：脚本成了摆设，Claude 不知道要用它。
• ❌ 脚本不校验输入：文件不存在直接报错崩溃，体验差。
• ❌ 脚本带危险副作用：未经确认就删文件、改全局配置——高风险，务必谨慎。

七、最佳实践

• 先问自己「这步有唯一正确答案吗」：有 → 脚本；没有 → Claude。
• 脚本开头写清用法（docstring 或 --help），并保持单一职责。
• 正文把「运行哪个脚本、传什么参数、怎么用输出」写成明确步骤。
• 脚本做好输入校验和友好报错，别让一个缺参数就把流程搞崩。
• 涉及修改/删除的脚本，遵循最小权限、先备份/确认的安全原则。

八、动手实践：08 章 Demo · Skill + Python 脚本协作（可运行）

一个真正能跑的技能：Claude 负责理解需求和解读结果，精确统计交给 Python 脚本。

8.1 结构

sales-analyzer/
├── SKILL.md                  # 正文把「运行脚本」写成了流程的一步
└── scripts/
    ├── stats.py              # 统计脚本（带输入校验和友好报错）
    └── sample-sales.csv      # 示例数据（故意留了一行空金额）

8.2 先单独跑脚本（不装技能也能验证）

cd sales-analyzer
python3 scripts/stats.py scripts/sample-sales.csv

预期输出：

记录数: 6
总额: 8502.25
平均: 1417.04
最大单笔: 3400.00
最小单笔: 150.20

注意：示例 CSV 有 7 行数据，但有一行金额是空的，脚本自动跳过了它，所以记录数是 6。这就是「确定性处理」交给脚本的好处——规则明确、不会算错。

试试错误处理

python3 scripts/stats.py 不存在的文件.csv
# 输出：[错误] 文件不存在: ...   （友好报错，不崩栈）

8.3 装上技能完整体验

cp -r sales-analyzer ~/.claude/skills/

开新会话：

帮我分析下这个销售数据：<把 sample-sales.csv 的绝对路径给它>

技能触发后，Claude 会去运行脚本拿到精确结果，再用人话解读给你听（而不是自己心算）。

8.4 看点：分工边界

• 脚本干的：读 CSV、跳空值、精确求和/平均/极值。
• Claude 干的：理解你的意图、决定调脚本、把数字解读成「哪天销售额偏高/偏低」这样的人话。

这正是第 08 章的核心——有唯一正确答案的活交给脚本，需要判断和表达的交给 Claude。

8.5 你会收获什么

• 一个可运行的「Skill + 脚本」范例。
• 直观体会「该算的交给代码」带来的准确和省心。
• 看到一份带输入校验、友好报错的「靠谱脚本」长什么样。

8.6 配套实践材料

以下材料已并入正文，便于阅读时直接对照和练习。

sales-analyzer/SKILL.md

---
name: sales-analyzer
description: 当用户需要统计、分析销售数据（CSV 格式），如计算总额、平均值、找出异常时使用。
---

# 销售数据分析

帮用户分析 CSV 格式的销售数据，并给出易懂的解读。

## 流程
1. 拿到用户提供的 CSV 文件路径（要求至少有一列是销售金额）。
2. 运行统计脚本：`python scripts/stats.py <csv文件路径>`
   - 脚本会输出：记录数、总额、平均值、最大单笔、最小单笔。
3. 解读脚本输出，用自然语言向用户汇报，并主动指出值得注意的点（如某些值明显偏离平均）。

## 注意
- 精确计算一律交给脚本，不要自己心算。
- 脚本报错时（如文件不存在），把错误原因转告用户并给出修正建议。

九、总结

• 为什么需要脚本：精确计算：算一长串数字的总和、复利、统计指标。
• 一个直观对比：Claude 只负责理解需求和解读结果。
• 怎么在技能里挂脚本：Claude 才知道该在这一步调用它，而不是自己算。
• 该让 AI 做还是脚本做？决策表：| 理解用户意图、决定做什么 | 🧠 Claude | 需要判断和灵活性 |
• 安全注意（重要）：脚本是真实执行的代码，有副作用，要谨慎：
• 常见错误：❌ 脚本不校验输入：文件不存在直接报错崩溃，体验差。