“

Claude Skills 的官方标准明确支持在 Skill 里打包可执行脚本。但大多数人只写 Markdown，忽略了 scripts/ 目录。这篇文章结合 agentskills.io 的官方规范和我在量化投资领域的实践，聊聊为什么脚本比 Markdown 重要得多。

官方怎么说

agentskills.io 是 Claude Code Skills 遵循的开放标准。它的 Using Scripts 页面明确定义了三种在 Skill 里使用代码的方式。

方式一：一次性命令

如果现成的工具就能干活，直接在 SKILL.md 里写命令，不需要 scripts/ 目录。官方推荐的运行方式包括 uvx、npx、bunx、deno run、go run 等，都支持自动解析依赖。

比如你的 Skill 需要格式化代码，直接写 uvx ruff@0.8.0 check . 就行。关键是要锁定版本号，确保每次行为一致。

方式二：打包脚本到 scripts/ 目录

当逻辑变复杂，就该把代码放进 scripts/ 文件夹。在 SKILL.md 里列出可用脚本，然后在工作流程中引用：

## 可用脚本- scripts/validate.sh — 校验配置文件- scripts/process.py — 处理输入数据## 工作流程1. 运行校验：bash scripts/validate.sh \"$INPUT_FILE\"2. 处理结果：python3 scripts/process.py --input results.json

路径用相对路径，Agent 会自动解析。

方式三：自包含脚本（依赖内联声明）

这是最优雅的方式。Python 的 PEP 723 允许你在脚本文件内部声明依赖：

# /// script# dependencies = [\"beautifulsoup4\"]# ///from bs4 import BeautifulSoup# ... 你的逻辑

用 uv run scripts/extract.py 执行，它会自动创建隔离环境、安装依赖、运行脚本。一条命令搞定，不需要 requirements.txt。

给 Agent 写脚本的四条铁律

官方文档特别强调了为 AI Agent 设计脚本时的注意事项，这些跟给人写脚本很不一样。

第一：绝对不能有交互式提示。 Agent 在非交互式 shell 里运行，遇到需要用户输入的地方会直接卡死。所有输入必须通过命令行参数、环境变量或 stdin 传入。

第二：必须有 --help 输出。 这是 Agent 学习你脚本接口的主要方式。写清楚有哪些参数、什么格式、给个例子。保持简洁——输出会进入 Agent 的上下文窗口，太长会挤占其他内容的空间。

第三：错误信息要有指导性。 Agent 拿到错误信息后会决定下一步怎么做。"Error: invalid input" 毫无帮助。要说清楚哪里错了、期望什么、怎么修：

Error: --format must be one of: json, csv, table.       Received: \"xml\"

第四：输出用结构化格式。 JSON、CSV 优于自由文本。结构化输出可以被 Agent 和标准工具（jq、awk）直接消费。数据走 stdout，诊断信息走 stderr，分开来。

更深层的设计考量

官方还提到了几个容易忽略的点：

幂等性 — Agent 可能重试命令。"如果不存在则创建"比"创建，重复则报错"安全得多。

Dry-run 支持 — 对有副作用的操作（删除文件、发送请求），提供 --dry-run 参数让 Agent 先预览结果。

可预测的输出大小 — 很多 Agent 框架会自动截断超过 10-30K 字符的工具输出。如果你的脚本可能产生大量输出，默认输出摘要，支持 --offset 分页，或者用 --output 参数写文件。

量化实战：从理论到落地

说完官方规范，聊聊我在实际项目中的体会。

我做了一个叫 portfolio-distiller 的 Skill，用来把散户的 181 只持仓"蒸馏"成 15-20 只有纪律的组合。它的结构是：

portfolio-distiller/├── SKILL.md              ← 流程编排 + 输出规范（约 200 行）├── scripts/│   ├── score.py          ← 因子打分引擎（约 300 行）│   └── transition.py     ← 税务优化过渡计划（约 300 行）├── references/│   └── factors.md        ← 因子定义文档└── gotchas.md            ← 踩坑记录

为什么 score.py 比 SKILL.md 重要

score.py 里做了几件 Markdown 做不到的事：

ROE 截断处理——超过 50% 的 ROE 很可能是高杠杆导致的虚高，代码里一行 roe_capped = stocks['roe'].clip(upper=0.5) 就解决了。如果写在 SKILL.md 里提醒 Claude "注意处理高杠杆 ROE"，它可能记得也可能忘。

百分位排名——不同量纲的指标（ROE 是百分比、PE 是倍数、价格涨幅是百分比）必须归一化才能比较。这种数学运算写在 Python 里一劳永逸，不能指望 Claude 每次心算。

缺失值处理——如果两个以上因子缺数据，标记为需要人工审核，不自动打分。这种边界条件在 Markdown 里很容易被忽略，在代码里是强制执行的。

transition.py 的税务逻辑

过渡计划生成器更能体现脚本的价值。它需要判断：每个持仓的持有期是长期还是短期？离满一年还有多少天？卖出的税率是多少？先卖亏损的（tax loss harvest）还是先卖盈利的？

这些逻辑有大量条件判断和计算，每次用户的情况都不同。如果让 Claude 从头推理，每次可能走不同的路径。写成 Python 脚本，逻辑是锁死的——同样的输入永远得到同样的输出。

价值分布

经过实践，我认为这个 Skill 的价值分布是：SKILL.md 占 20%，scripts 占 60%，gotchas 占 20%。

SKILL.md 的角色很薄——告诉 Claude 什么时候跑什么脚本、结果怎么呈现。真正的核心能力在 scripts 里。而 gotchas.md 会随着使用不断积累，最终成为信噪比最高的内容。

诚实的局限

即使有了脚本，这个 Skill 仍然有几个问题没解决：

因子权重没有经过回测验证。动量 40%、质量 35%、价值 25% 是根据学术文献设定的，不是从历史数据优化出来的。这需要再加一个 backtest.py。

没有换手约束。每月重新打分可能导致大洗牌，交易成本和税会吃掉收益。需要在 score.py 里加 --max-turnover 参数。

聚类太粗糙。只按行业分类，没有用收益率相关性矩阵。这也是代码层面的改进。

这些局限进一步证明了一个观点：Skill 的天花板取决于 scripts 文件夹里的代码质量，不取决于 SKILL.md 写得多漂亮。 后续迭代的精力应该花在 Python 上，不是 Markdown 上。

总结

如果你在做 Claude Skills，记住这个优先级：

1. 先写脚本，确保核心逻辑可靠、可复现
2. 脚本要遵守四条铁律：无交互、有 help、错误信息有指导、输出结构化
3. SKILL.md 只做流程编排和输出规范，越薄越好
4. gotchas.md 持续更新，每次踩坑都记录
5. 没有回测的量化 Skill 只是好看的排序器——一定要验证

Skills 的真正价值不在那份 Markdown 文档有多精美，在于它调用的代码有多可靠。