使用 scripts

scripts/ 是 Skill 从“说明书”升级为“可执行能力包”的关键。它适合处理那些需要确定性、可重复、可测试的操作。

但脚本不是越多越好。好的脚本会减少 agent 的不确定性；坏的脚本会增加安装成本、安全风险和维护负担。

什么时候应该写脚本

优先把以下任务封装到 scripts/：

场景	原因	例子
确定性计算	不应交给 LLM 猜	金额汇总、hash、统计指标
文件转换	流程固定、边界多	PDF 转文本、CSV 清洗、图片压缩
批量处理	手写步骤容易漏	遍历目录、批量重命名、批量生成报告
格式校验	需要可重复判断	检查 frontmatter、JSON schema、链接有效性
外部工具编排	命令较长或易错	调用 ffmpeg、pandoc、jq
复杂模板生成	输出结构稳定	生成配置文件、项目骨架、表格模板

一句话判断：如果你希望同样输入每次得到同样输出，就优先考虑脚本。

什么时候不要写脚本

以下情况不适合放进 scripts/：

• 只是回调 LLM：脚本里又调用 AI “帮我完成任务”，没有降低不确定性。
• 逻辑还没稳定：流程仍在探索期，先写在 SOP 里观察。
• 依赖过重：为了一个小任务安装半个生态。
• 权限过大：脚本默认删除文件、联网、上传数据。
• 只能在作者机器上跑：依赖绝对路径、本地环境变量或私有命令。

脚本的目标是解决问题，不是把 prompt 包一层壳。

推荐目录结构

my-skill/
├── SKILL.md
├── scripts/
│   ├── validate.py
│   └── transform.py
├── references/
│   └── edge-cases.md
└── assets/
    └── report.template.md

保持一层路径即可。SKILL.md 里直接引用：

当需要校验输入文件时，运行 `scripts/validate.py`。
当校验失败时，读取 `references/edge-cases.md`。

不要把路径嵌太深：

scripts/internal/v2/helpers/validate-final-final.py

agent 更容易找错，也更难维护。

脚本设计原则

1. 自包含

脚本应尽量只依赖标准库。必须依赖第三方包时，在 SKILL.md 中明确声明：

## 前置依赖

运行脚本前确认已安装：

```bash
pip install pypdf
```

如果目标平台支持 uv、npm 或容器环境，也要写清楚安装方式。

2. 输入输出明确

脚本应提供清晰的 CLI 参数：

python scripts/extract_tables.py --input contract.pdf --output tables.csv

避免让脚本猜：

python scripts/do_it.py

3. 错误信息可行动

错误信息要告诉 agent 下一步做什么：

ERROR: input file is encrypted. Ask the user for the password, then rerun with --password.

不要只抛出底层异常：

KeyError: xref

4. 输出简洁

脚本输出会进入上下文。只输出 agent 需要使用的信息：

• 成功 / 失败状态
• 生成文件路径
• 关键统计信息
• 可行动错误

大量中间日志应写入文件，而不是刷屏。

5. 幂等

同一命令重复执行不应破坏已有结果。常见做法：

• 输出到明确目录
• 文件存在时提示覆盖策略
• 支持 --overwrite
• 支持 --dry-run

6. 不默认高风险操作

涉及删除、覆盖、联网、上传、安装依赖时，脚本应要求显式参数：

python scripts/cleanup.py --target dist --dry-run
python scripts/cleanup.py --target dist --confirm-delete

在 SKILL.md 中如何指挥脚本

写脚本不够，还要告诉 agent 何时调用。

不推荐：

可以使用 `scripts/report.py` 生成报告。

推荐：

当用户要求生成正式报告，且已经确认输入数据无误时，运行：

```bash
python scripts/report.py --input data.csv --template assets/report.template.md --output report.md
```

如果脚本返回 `MISSING_COLUMNS`，读取 `references/schema.md` 并向用户说明缺少哪些列。

重点是给出：

• 触发条件
• 命令形式
• 输入来源
• 输出位置
• 错误分支

scripts 与 references 的分工

内容	放哪里	原因
可执行转换逻辑	scripts/	让机器做确定性操作
长篇背景知识	references/	按需读取，不挤占主上下文
输出模板	assets/	复制或填充使用
每次都必须遵守的流程	SKILL.md	触发后立即进入上下文

一个常见组合是：

SKILL.md 负责决策
scripts/ 负责执行
references/ 负责解释边界
assets/ 负责承载模板

脚本检查清单

发布前检查：

• [ ] 脚本路径使用 /，不用 Windows 反斜杠
• [ ] 命令示例可直接复制运行
• [ ] 第三方依赖写清楚
• [ ] 参数名表达输入输出
• [ ] 错误信息可行动
• [ ] 大量日志不会刷进对话上下文
• [ ] 高风险操作需要显式确认
• [ ] 至少有一个真实样例跑通过

下一步

• 想确认脚本是否真的改善任务结果，看 评估 Skill。
• 想控制脚本和第三方 Skill 的风险，看 安全与信任模型。