Agent Skills

在 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.py

uv 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').text
ruby 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。