在 Skill 中使用脚本
如何在 Skill 中运行命令,并附带可执行脚本。
Skill 可以指导 Agent 运行 Shell 命令,也可以在 scripts/ 目录中附带可复用的脚本。本指南介绍单次执行命令、自行声明依赖的独立脚本,以及如何设计便于 Agent 使用的脚本接口。
单次执行命令
如果现有软件包已经能完成所需操作,可以直接在 SKILL.md 指令中引用,无须创建 scripts/ 目录。许多语言生态都提供了在运行时自动解析依赖的工具。
uvx
uvx 在隔离环境中运行 Python 软件包,并充分利用缓存。它随 uv 提供。
uvx ruff@0.8.0 check .
uvx black@24.10.0 .- 不随 Python 提供,需要单独安装。
- 运行速度快。充分利用缓存,重复运行几乎可以立即完成。
pipx
pipx 在隔离环境中运行 Python 软件包。可以通过操作系统的软件包管理器安装,例如 apt install pipx、brew install pipx。
pipx run 'black==24.10.0' .
pipx run 'ruff==0.8.0' check .- 不随 Python 提供,需要单独安装。
- 是
uvx的成熟替代方案。虽然uvx已成为通常推荐的工具,pipx依然可靠,而且支持它的操作系统软件包管理器更多。
npx
npx 按需下载并运行 npm 软件包。它随 npm 提供,而 npm 随 Node.js 提供。
npx eslint@9 --fix .
npx create-vite@6 my-app- 随 Node.js 提供,无须额外安装。
- 下载并运行软件包,缓存后供再次使用。
- 使用
npx package@version固定版本,以保证结果可复现。
bunx
bunx 是 Bun 中对应 npx 的工具,随 Bun 提供。
bunx eslint@9 --fix .
bunx create-vite@6 my-app- 在基于 Bun 的环境中,可以直接替代
npx。 - 仅适用于用户环境使用 Bun 而非 Node.js 的情况。
deno run
deno run 可以直接通过 URL 或模块说明符运行脚本,随 Deno 提供。
deno run npm:create-vite@6 my-app
deno run --allow-read npm:eslint@9 -- --fix .- 访问文件系统或网络时,需要指定
--allow-read等权限参数。 - 用
--将 Deno 的参数与工具自身的参数分开。
go run
go run 可以直接编译并运行 Go 软件包,是 go 命令的内置功能。
go run golang.org/x/tools/cmd/goimports@v0.28.0 .
go run github.com/golangci/golangci-lint/cmd/golangci-lint@v1.62.0 run- Go 内置,无须额外工具。
- 固定版本,或使用
@latest,明确命令要运行的版本。
在 Skill 中使用单次执行命令的建议:
- 固定版本,例如
npx eslint@9.0.0,使命令的行为不会随时间变化。 - 在
SKILL.md中说明前提条件,例如“需要 Node.js 18+”,不要默认 Agent 的环境已经具备。运行时层面的要求,使用compatibility前置元数据字段说明。 - 将复杂命令移入脚本。 调用工具时只需附带少量参数,单次执行命令就很合适。如果命令已经复杂到难以一次写对,使用
scripts/中经过测试的脚本会更可靠。
从 SKILL.md 引用脚本
引用随 Skill 提供的文件时,使用相对于 Skill 根目录的路径。Agent 会自动解析这些路径,无须使用绝对路径。
在 SKILL.md 中列出可用脚本,让 Agent 知道有哪些脚本可用:
SKILL.md
## 可用脚本
- **`scripts/validate.sh`**——验证配置文件
- **`scripts/process.py`**——处理输入数据然后指导 Agent 运行脚本:
SKILL.md
## 工作流
1. 运行验证脚本:
```bash
bash scripts/validate.sh "$INPUT_FILE"
```
2. 处理结果:
```bash
python3 scripts/process.py --input results.json
```注意
references/*.md等辅助文件也采用相同的相对路径约定:代码块中的脚本执行路径相对于 Skill 根目录,因为 Agent 从该目录运行命令。
自包含脚本
如果需要复用逻辑,就将脚本放入 scripts/,并在脚本内直接声明依赖。Agent 只需一条命令即可运行,无须独立的清单文件或额外安装步骤。
多种语言支持在脚本内声明依赖:
Python
PEP 723 定义了脚本内嵌元数据的标准格式。将依赖写在 # /// 标记内的 TOML 块中:
scripts/extract.py
# /// script
# dependencies = [
# "beautifulsoup4",
# ]
# ///
from bs4 import BeautifulSoup
html = '<html><body><h1>Welcome</h1><p class="info">This is a test.</p></body></html>'
print(BeautifulSoup(html, "html.parser").select_one("p.info").get_text())使用 uv 运行(推荐):
uv run scripts/extract.pyuv run 会创建隔离环境、安装声明的依赖,再运行脚本。pipx 也支持 PEP 723,运行方式为 pipx run scripts/extract.py。
- 使用 PEP 508 说明符固定版本:
"beautifulsoup4>=4.12,<5"。 - 使用
requires-python限定 Python 版本。 - 使用
uv lock --script创建锁文件,确保完全可复现。
Deno
Deno 的 npm: 和 jsr: 导入说明符,使每个脚本默认都能独立声明所需依赖:
scripts/extract.ts
#!/usr/bin/env -S deno run
import * as cheerio from "npm:cheerio@1.0.0";
const html = `<html><body><h1>Welcome</h1><p class="info">This is a test.</p></body></html>`;
const $ = cheerio.load(html);
console.log($("p.info").text());deno run scripts/extract.ts- npm 软件包使用
npm:,Deno 原生软件包使用jsr:。 - 版本说明符遵循语义化版本规则:
@1.0.0指定确切版本,@^1.0.0指定兼容版本。 - 依赖在全局缓存。使用
--reload强制重新获取。 - 带有原生扩展(node-gyp)的软件包可能无法运行,附带预编译二进制文件的软件包最合适。
Bun
如果找不到 node_modules 目录,Bun 会在运行时自动安装缺失的软件包。可以直接在导入路径中固定版本:
scripts/extract.ts
#!/usr/bin/env bun
import * as cheerio from "cheerio@1.0.0";
const html = `<html><body><h1>Welcome</h1><p class="info">This is a test.</p></body></html>`;
const $ = cheerio.load(html);
console.log($("p.info").text());bun run scripts/extract.ts- 无须
package.json或node_modules,原生支持 TypeScript。 - 软件包在全局缓存。首次运行时下载,后续运行几乎可以立即完成。
- 如果当前目录或任意上级目录中存在
node_modules,自动安装就会停用,Bun 会改用标准的 Node.js 解析方式。
Ruby
从 Ruby 2.6 开始,Bundler 随 Ruby 提供。使用 bundler/inline,即可直接在脚本中声明 gem:
scripts/extract.rb
require 'bundler/inline'
gemfile do
source 'https://rubygems.org'
gem 'nokogiri'
end
html = '<html><body><h1>Welcome</h1><p class="info">This is a test.</p></body></html>'
doc = Nokogiri::HTML(html)
puts doc.at_css('p.info').textruby scripts/extract.rb- 显式固定版本,例如
gem 'nokogiri', '~> 1.16',因为这里没有锁文件。 - 工作目录中已有的
Gemfile,或环境变量BUNDLE_GEMFILE,都可能产生干扰。
设计适合 Agent 使用的脚本
Agent 运行脚本后,会读取标准输出(stdout)和标准错误输出(stderr),以决定下一步操作。几个设计选择,就能显著降低 Agent 使用脚本的难度。
避免交互式提示
这是 Agent 执行环境的硬性要求。Agent 在非交互式 Shell 中运行,无法回应 TTY 终端提示、密码对话框或确认菜单。脚本如果停下来等待交互输入,就会一直挂起。
所有输入都应通过命令行参数、环境变量或标准输入(stdin)传入:
# 不好的写法:挂起并等待输入
$ python scripts/deploy.py
目标环境:_
# 好的写法:清晰报错,并给出操作指引
$ python scripts/deploy.py
错误:必须指定 --env。可选值:development、staging、production。
用法:python scripts/deploy.py --env staging --tag v1.2.3用 --help 说明用法
--help 输出是 Agent 了解脚本接口的主要途径。内容应包括简要说明、可用参数和使用示例:
用法:scripts/process.py [OPTIONS] INPUT_FILE
处理输入数据,并生成摘要报告。
选项:
--format FORMAT 输出格式:json、csv、table(默认:json)
--output FILE 将输出写入 FILE,而非 stdout
--verbose 将进度信息输出到 stderr
示例:
scripts/process.py data.csv
scripts/process.py --format csv --output report.csv data.csv保持简洁:这些输出会进入 Agent 的上下文窗口,与当前任务的其他内容共存。
编写有帮助的错误消息
Agent 遇到错误时,错误消息会直接影响下一次尝试。“错误:输入无效”这样含糊的消息,只会浪费一轮尝试。应说明哪里出错、预期是什么,以及可以尝试什么:
错误:--format 必须为以下值之一:json、csv、table。
收到的值:"xml"使用结构化输出
优先使用 JSON、CSV、TSV 等结构化格式,不要采用自由文本。Agent 和 jq、cut、awk 等标准工具都能处理这些格式,便于将脚本组合到流水线中。
# 用空白对齐——程序难以解析
NAME STATUS CREATED
my-service running 2025-01-15
# 用分隔符区分——字段边界明确
{"name": "my-service", "status": "running", "created": "2025-01-15"}**将数据与诊断信息分开:**结构化数据写入 stdout,进度消息、警告及其他诊断信息写入 stderr。这样,Agent 既能获取干净、可解析的输出,又能在需要时读取诊断信息。
其他注意事项
- 幂等性。 Agent 可能重试命令。“不存在则创建”比“直接创建,重复时报错”更安全。
- 输入约束。 对含糊的输入明确报错并拒绝处理,不要猜测其含义。尽可能使用枚举和限定的取值集合。
- 预演支持。 对于破坏性操作或会改变状态的操作,
--dry-run参数可以让 Agent 预览将要发生的变更。 - 有明确含义的退出码。 为不同失败类型设置不同退出码,例如未找到目标、参数无效、身份验证失败,并在
--help输出中说明,让 Agent 知道每个退出码的含义。 - 安全的默认行为。 根据风险程度,考虑是否要求破坏性操作显式提供
--confirm、--force等确认参数,或采用其他适当的防护措施。 - 可预期的输出量。 许多 Agent Harness(Agent 的执行框架)会自动截断超过阈值的工具输出,例如超过 10,000–30,000 个字符,关键内容可能因此丢失。如果脚本可能产生大量输出,默认返回摘要或设置合理的数量上限,并支持
--offset等参数,让 Agent 按需获取更多信息。另一种做法是:如果输出很长且不适合分页,就要求 Agent 传入--output参数,指定输出文件,或者显式填写-,选择将结果写入 stdout。