在技能中使用脚本

如何在你的技能中运行命令和捆绑可执行脚本。

Documentation Index
Fetch the complete documentation index at: https://agentskills.io/llms.txt

Use this file to discover all available pages before exploring further.

技能可以指导代理运行 shell 命令，并将可重用脚本捆绑到脚本/目录中。本指南涵盖了一次性命令、具有自身依赖关系的自包含脚本，以及如何设计代理使用的脚本接口。
(1)
一次性命令
当现有包已经满足你的需求时，你可以直接在你的 SKILL.md 指令中引用它，而无需脚本/目录。许多生态系统提供了在运行时自动解决依赖关系的工具。
uvx
pipx
npx
bunx
deno run
go run
uvx 在具有积极缓存的独立环境中运行 Python 包。它随 uv 一起发布。
uvx ruff@0.8.0 check .
uvx black@24.10.0 .
未与 Python 捆绑——需要单独安装。
快速。高速缓存积极进行，使得重复运行几乎瞬间完成。
关于技能中一次性命令的提示：
引脚版本 (例如，npx eslint@9.0.0)，因此随着时间的推移，命令的行为会保持不变。
在你的 SKILL.md 中说明先决条件 (例如，“Requires Node.js 18+”)，而不是假设代理的环境中存在这些先决条件。对于运行时级别的要求，请使用兼容性前缀字段。
将复杂的命令移动到脚本中。当你调用带有几个标志的工具时，一次性命令效果很好。当命令变得足够复杂，以至于第一次尝试很难正确执行时，在脚本/中使用经过测试的脚本会更加可靠。
(1)
来自 SKILL.md 的参考脚本
使用从技能目录根目录到引用捆绑文件的相对路径。代理会自动解析这些路径——无需绝对路径。
在你的 Skill.md 中列出可用的脚本，以便代理知道它们的存在：
SKILL.md

Available scripts

• scripts/validate.sh — Validates configuration files
• scripts/process.py — Processes input data
  然后指示代理运行它们：
  SKILL.md

  Workflow

1. Run the validation script:

   bash scripts/validate.sh "$INPUT_FILE"

2. Process the results:

   python3 scripts/process.py --input results.json

   相同的相对路径约定也适用于支持文件，如 references/*.md——脚本执行路径 (在代码块中) 是相对于技能目录根的，因为代理从那里运行命令。
   (1)
   自包含脚本
   当您需要可重用的逻辑时，可以将脚本捆绑在 scripts/中，以内联方式声明其自身的依赖关系。代理可以使用单个命令运行脚本——无需单独的清单文件或安装步骤。
   多种语言支持内联依赖声明：
   Python
   Deno
   Bun
   Ruby
   PEP 723 定义了内联脚本元数据的标准格式。在# ///标记内的 TOML 块中声明依赖关系：
   scripts/extract.py

   /// script

   dependencies = [

   “beautifulsoup4”,

   ]

   ///

from bs4 import BeautifulSoup

html = ‘

Welcome

This is a test.

Bad: hangs waiting for input

$ python scripts/deploy.py
Target environment: _

Good: clear error with guidance

$ python scripts/deploy.py
Error: –env is required. Options: development, staging, production.
Usage: python scripts/deploy.py –env staging –tag v1.2.3
(1)
使用–help 使用文档
–help 输出是代理学习脚本界面的主要方式。包括简要描述、可用标志和使用示例：
Usage: scripts/process.py [OPTIONS] INPUT_FILE

Process input data and produce a summary report.

Options:
–format FORMAT Output format: json, csv, table (default: json)
–output FILE Write output to FILE instead of stdout
–verbose Print progress to stderr

Examples:
scripts/process.py data.csv
scripts/process.py –format csv –output report.csv data.csv
保持简洁——输出与其他所有正在处理的内容一起进入智能体的上下文窗口。
(1)
编写有帮助的错误消息
当智能体收到错误时，这条消息会直接影响它的下一次尝试。一个不透明的 “错误：无效输入” 会浪费时间。相反，要说明哪里出错了，预期是什么，以及应该尝试什么：
Error: –format must be one of: json, csv, table.
Received: “xml”
(1)
使用结构化输出
优先选择结构化格式——JSON、CSV、TSV——而不是自由格式的文本。结构化格式可以被代理和标准工具 (jq、cut、awk) 使用，使你的脚本可以在管道中编译。

Whitespace-aligned — hard to parse programmatically

NAME STATUS CREATED
my-service running 2025-01-15

Delimited — unambiguous field boundaries

{“name”: “my-service”, “status”: “running”, “created”: “2025-01-15”}
将数据与诊断信息分离：将结构化数据发送给 stdout，并将进度消息、警告和其他诊断信息发送给 stderr。这使得智能体能够捕获干净、可解析的输出，同时在需要时仍能访问诊断信息。
(1)
进一步考虑
等效性。智能体可以重试命令。“如果不存在就创建” 比 “创建并在重复时失败” 更安全。
输入约束。拒绝带有明确错误的模糊输入，而不是猜测。尽可能使用枚举和封闭集。
干运行支持。对于破坏性或有状态的行动，一个 – 干运行标志可以让特工预览将要发生的事情。
有意义的退出代码。针对不同类型的故障 (未找到、无效参数、身份验证失败)，使用不同的退出代码，并将其记录在你的–help 输出中，以便智能体知道每个代码的含义。
安全默认。考虑破坏性行动是否应该需要明确的确认标志 (–confirm、–force) 或其他适合风险水平的保障措施。
可预测的输出大小。许多智能体会自动截断超过阈值 (例如，10-30K 个字符) 的工具输出，这可能会丢失关键信息。如果脚本可能产生大量输出，则默认使用摘要或合理的限制，并支持–offset 等标志，以便智能体在需要时请求更多信息。或者，如果输出较大且不适合分页，则要求智能体传递–output 标志，该标志指定输出文件或-，以显式选择加入 stdout。