把一个 Skill 搬到另一款 Agent，先交代它依赖什么
从同一份发布说明 Skill 出发，检查目录、脚本运行环境、工作目录、凭据和权限，把共享知识与宿主能力分开，做一次可复查的迁移验收。
一份 Skill 在原来的 Agent 里能生成发布说明，搬到另一款工具后却找不到模板，或者停在安装依赖的步骤。先别急着重写提示词。同一套操作说明可以共享，脚本运行环境、文件位置和工具权限仍要逐项对齐。
本文于 2026 年 11 月 13 日重新读取 Agent Skills 规范和脚本编写指南。它接着规则文件与 Skills 的分工讨论具体迁移，不再介绍一遍概念。这里提供迁移样例与验收方法，未实际运行两款 Agent 的对照，也不声称自动触发效果相同。
先把依赖写在能被看见的地方
假设目标只是从一份公开变更清单生成本地发布说明，不提交、不推送、不创建远端发布。可以保留这样一个目录：
release-note/
├── SKILL.md
├── scripts/render.py
└── assets/release-template.md
入口示意如下。它只演示描述方式，脚本与模板仍需由团队提供，不是复制后就完整可运行的软件包：
---
name: release-note
description: Create a local release note from a public change list. Use when drafting release notes before publication.
compatibility: Requires Python 3.11+ and local file access; the render step needs no network.
metadata:
version: "1.0"
---
规范允许 compatibility 写环境要求，metadata 记录附加信息。版本字符串是维护线索，不是宿主一定执行的版本锁。description 要交代任务和触发条件；真正执行时，再读取完整步骤与所需资源。
不要把所有参考材料塞回主文件来修复一次触发问题。先确认宿主是否发现了正确目录、读到了哪份描述，以及是否实际加载了正文。格式有效与任务匹配，是两项不同验收。
路径要同时说明 Skill 目录和项目目录
脚本常有两种输入：随 Skill 分发的模板，以及用户项目里的变更清单。它们不一定相对同一个目录。
规范使用相对 Skill 根目录的文件引用。执行时仍应核对宿主怎样解析路径；不要把“模型看懂了相对路径”当成进程一定从那个目录启动。下面是已知两个绝对路径后，在 Bash 或 Zsh 中执行的命令示意，尚未在宿主中运行：
SKILL_DIR="/absolute/path/to/release-note"
PROJECT_DIR="/absolute/path/to/demo-project"
python3 "$SKILL_DIR/scripts/render.py" --input "$PROJECT_DIR/changes.json" --template "$SKILL_DIR/assets/release-template.md" --output "$PROJECT_DIR/release-note.md"
--input 等参数是这个教学脚本拟定的接口，团队要先实现它们。把输出路径明确给出，既能避免写到 Skill 安装目录，也能在验收时知道该检查哪个文件。Windows 原生命令行要适配自己的引用方式，不能把这段 Shell 原样认作跨系统脚本。
依赖能装上，也不等于允许执行
官方脚本指南建议明确前置工具、固定版本、提供简短 --help，并避免交互式菜单。uvx、npx 或其他临时运行器可能需要下载程序；“不改项目依赖”不等于“不访问网络”，也不代表企业环境自动允许。
allowed-tools 在通用规范中仍是实验字段，各宿主支持方式可能不同。它不会凭空创建一个工具，更不能绕过执行环境原有权限。若发布步骤要调用远端服务，应该另设明确授权条件，不让“写发布说明”默认扩大成“上线”。
凭据只写变量名与取得方式。不要把作者机器上的令牌、绝对私有路径或账户配置一起打包。有关工具返回内容的处理，可结合MCP 权限边界阅读；模型入口的 Key 管理见密钥安全。
用一份固定输入验收，再试自动触发
给两个宿主同一份公开 changes.json 和同一模板，先显式调用 Skill，检查这些结果：
| 检查项 | 能接受的结果 |
|---|---|
| 读取了哪份入口 | 能对应具体路径和版本记录 |
| 输入和模板 | 使用同一文件内容，没有自行替换 |
| 生成文件 | 写到约定位置，必需章节齐全 |
| 依赖缺失 | 清楚报告缺什么，不静默换工具 |
| 外部动作 | 本地写作范围内没有触发发布 |
脚本输出也要适合验收：结构化结果放标准输出，进度和错误放标准错误；非零退出码表示失败，不让模型从一句“完成了”猜状态。对于有写入或远端副作用的脚本，提供预览或 dry-run，并说明它验证到哪一步。
显式调用通过后，再检查自然提问能否匹配；这样能区分描述没匹配与脚本没执行。换模型时也可保留这份任务，但不能把一次通过写成普遍可靠或节省多少 Token。Skills 的共同维护规则解释了标准层面的变化；团队自己的依赖说明和验收记录，仍需要随每次迁移维护。
