资源与脚本

适用版本：StablEdge 0.4.4 及以上

除了 SKILL.md，Skill 目录里还可以放参考文档、模板、素材和脚本。它们是三级加载里的第三级：只有在 Agent 明确读取、复制或运行时才会用到。

目录结构

my-skill/
├── SKILL.md
├── reference.md          参考文档：按需读进上下文
├── references/           参考文档较多时按主题分文件
│   ├── api.md
│   └── schema.md
├── scripts/              脚本：只有这里的脚本能被 run_script 运行
│   └── extract.py
└── assets/               模板和素材：复制到工作区后使用
    └── report-template.docx

除了 scripts/ 是运行脚本的硬性要求，其他目录名都是约定，可以按需调整。附带文件尽量只放完成任务真正需要的东西，不要放 README、安装说明、更新记录这类写给人看的文档。

Agent 如何访问附带文件

Skill 安装在 StablEdge 的数据目录里，不在工作区。Agent 不能用通用的文件或终端工具访问这些文件，只能通过 skill 工具：

动作用途限制
list_files列出附带文件和大小，声明过角色的会标注角色分页，每页最多 200 条。跳过以 . 开头的文件和目录、__pycache__、node_modules、符号链接，以及根目录的 SKILL.md。
read_file把一个文本文件读进上下文，可用 offset / limit 按行读取按 UTF-8 读取；前 8 KB 里含空字节的文件视为二进制，会被拒绝。
copy_file把文件复制到当前工作区，dest 是工作区内的相对路径，默认与文件在 Skill 里的相对路径相同单个文件不超过 20 MB；写入工作区需经过宿主的安全检查。
run_script由宿主在沙箱里运行 scripts/ 下的脚本见下文运行脚本。

加载 Skill 时，StablEdge 会把附带文件清单（最多前 20 项）和这些读法一起交给 Agent。所以在正文里引用附带文件时，写相对于 Skill 目录的路径即可，例如 reference.md、scripts/extract.py。路径必须留在 Skill 目录内：绝对路径、~ 开头的路径、盘符路径、用 .. 或符号链接跳出目录的路径都会被拒绝。

声明资源

Progressive Skill 可以在 frontmatter 的 resources 里声明附带文件和它们的角色。下面摘自内置 pdf Skill（builtin/pdf/SKILL.md，节选）：

resources:
  - path: reference.md
    role: reference
  - path: scripts/extract_text.py
    role: executable
  - path: scripts/merge_pdfs.py
    role: executable

每一项的校验规则：

  • path：相对于 Skill 目录的路径，反斜杠会转成 /；不能为空、不能是绝对路径或盘符路径、不能含 ..；
  • path 不能是 SKILL.md，同一路径不能声明两次；
  • 声明的文件必须真实存在于 Skill 目录内；
  • role 必须是下表四个值之一。

任一项不合规都会让整个 Progressive 校验失败，处理方式见 校验与降级。

resources 只在 frontmatter 同时有 progressive 时才会被解析；普通 Skill 写了也不生效。没有声明的文件同样可以被列出、读取和复制，声明的作用是提前校验文件存在，并在文件清单里标出角色。

资源角色

role适合放什么Agent 通常怎么用
reference接口文档、数据结构、详细规范等参考资料read_file 读进上下文
executablescripts/ 下的脚本run_script 运行
template要基于它生成产物的模板，如文档模板、项目骨架copy_file 复制到工作区再修改
asset图片、字体、示例文件等直接用在产物里的素材copy_file 复制到工作区

角色是给 Agent 看的标注，不会改变动作本身的限制，例如标成 executable 的文件如果不在 scripts/ 下，仍然不能用 run_script 运行。

运行脚本

需要稳定、可重复执行的操作（格式转换、批量处理、数据提取），比起让 Agent 每次重写代码，更适合写成脚本放进 scripts/。正文里写的“用 python 运行 scripts/xxx.py”，Agent 会转成 run_script 调用，由宿主执行，而不是交给 shell。

运行时

宿主按文件扩展名选择自带的运行时：

扩展名运行时
.py宿主自带的 Python（隔离模式、UTF-8）
.js、.mjs、.cjs宿主自带的 Node.js
.ts、.mts、.ctsNode.js + tsx
.sh、.bashBash（系统里需要能找到 Bash）
无扩展名按首行 shebang 识别 python、python3、node、bash、sh

其他类型（包括可执行程序）一律不支持。

限制

项目限制
脚本路径必须在 Skill 的 scripts/ 目录内
超时1–300 秒，默认 60 秒
参数通过 argv 逐项传入，最多 64 项，每项不超过 8 KB
网络默认使用 frontmatter 中声明的域名；也可以在调用时用 network_hosts 指定，最多 16 个，只接受精确的 HTTPS 域名（不接受 IP、端口、通配符和 URL）；传空列表即离线运行
工作区需要当前对话有可用的本地工作区，否则会返回 SKILL_SCRIPT_WORKSPACE_UNAVAILABLE

安全机制

  • 每次运行脚本都需要用户单独确认，确认卡上会显示将要放行的网络域名；
  • 宿主先为 Skill 目录做一份快照并校验内容 hash，确认与 Agent 加载时一致后才运行，防止运行期间被替换；
  • 脚本在操作系统沙箱里运行，工作目录是当前工作区；
  • 内置 Skill 的脚本要先 load 该 Skill 才能运行；
  • 运行结果以 status、exit_code、duration_ms、truncated、stdout、stderr 返回给 Agent。
安装预览时，包含脚本或可执行文件的 Skill 会被标为高风险（SKILL_INSTALL_EXECUTABLE_CONTENT），提醒用户先检查内容。

编写建议

  • 参数从命令行读取，结果写到标准输出或工作区内的文件，不要写死路径；
  • 出错时返回非零退出码，并把原因写到标准错误，方便 Agent 调整；
  • 尽量只依赖运行时自带的库，不要在脚本里临时下载或安装依赖；
  • 发布前实际运行一遍，确认输出符合预期。
本页目录