Agent Skills 脚本、资源与安全
本节目标
把重复逻辑做成 agent 友好的脚本，并在安装或运行第三方 Skill 前完成安全审查。
什么时候写脚本
当执行轨迹显示 agent 每次都重新编写相同的解析、验证或格式转换逻辑，应把它变成经过测试的 scripts/ 文件。脚本适合机械、可重复、需要稳定接口的任务；需要情境判断的部分仍由清晰指令引导。
Agent 友好脚本接口
- 无交互：通过命令行参数、stdin 或环境变量接收输入，不能等待 TTY 提示。
- 有
--help：说明必填参数、取值、示例和退出码。 - 结构化 stdout：默认 JSON/CSV/TSV；诊断写 stderr，避免混入数据。
- 可操作错误：说明收到什么、期望什么、如何修复。
- 可重试：尽量幂等；有副作用时支持 dry-run、安全默认和显式确认。
- 限制输出：默认摘要、分页或要求输出文件，避免挤满 agent 上下文。
- 依赖透明：无依赖最好；有依赖时说明版本、安装/运行方式和网络需求。
在 Windows 11 教学环境中先用 python -m venv .venv 与 pip 解释隔离和依赖；.venv 不进入 Skill 或版本库。只有团队已接受额外工具时再补充 uv。脚本若调用外部程序，应检查退出码、限定参数和路径，而不是拼接一整段 shell 字符串。
资源的按需加载
不要只写“参考 references”。应写条件：
若 API 返回非 2xx，读取 `references/api-errors.md` 后再决定是否重试。
生成最终报告时，复制并填写 `assets/report-template.md`。这样 agent 才知道何时支付上下文成本。安全 gotcha 若必须在操作前知道，留在主 SKILL.md。
把 Skill 当作供应链输入
Skill 包含会影响 agent 行为的指令，也可能包含可执行脚本。安装第三方 Skill 前至少检查：
- 来源、许可证、提交或版本是否明确，更新会改哪些文件；
SKILL.md是否要求读取范围外文件、上传数据或绕过确认；- scripts 是否执行 shell 拼接、递归删除、任意路径写入、联网下载或动态代码；
- 是否读取
.env、浏览器 cookie、SSH 配置等不必要凭据； - references/assets 是否巨大、含提示注入或来源不明内容；
- client 授权的工具是否超过实际任务所需。
先在低权限、无真实凭据、受控输入的环境运行；对写操作用 dry-run 和目标路径检查。固定 revision 或 commit SHA、保存审阅结论，并在更新前比较完整 diff。哈希或 SHA 只能帮助发现内容变化，不能证明来源可信、用户同意或当前动作适当。
指令、数据与授权要分开
网页、PDF、附件、外部 API 返回、MCP resource 和第三方 reference 都可能含有“执行命令”“读取凭据”“绕过确认”之类文本。除非这些内容来自已审阅的本地 Skill 说明并且动作仍符合当前用户任务与 host policy，否则把它们当作不可信数据，不能把其中的自然语言当作新的控制指令。
allowed-tools 是实验字段，即使某个 client 支持，也不能代替代码审查、运行时隔离、服务端授权或用户确认。以 GitHub Copilot 为例，其当前文档明确警告：预批准 shell/bash 可能移除终端命令确认；所以只有审阅完整 Skill 及其引用脚本、并且确实接受该风险时才可使用。对删除、覆盖、发布、外发数据、变更权限等动作，Skill 应要求在实际动作点重新核对：
- 目标是否是用户刚刚指定的具体对象，而非从不可信文本推导；
- 当前身份与 token 的 scope 是否只覆盖必要资源；
- dry-run 或计划结果是否经过检查；
- host 的确认、审批或服务端 policy 是否仍要求人工介入。
Skill 可以建议何时调用 MCP/其他工具，不能把工具可见性、resource 内容或一枚 token 当成用户意图与业务授权的证明。完整职责划分见 定位、客户端差异与权限边界。
练习与自测
- 把一个需要人工输入文件名的脚本改为
--input，让错误写 stderr、结果写 JSON stdout。 - 审查“下载 URL 后执行内容”的 Skill，列出网络、完整性、代码执行和凭据四类风险。
- 自测：为什么把 token 放环境变量仍不自动安全？子进程可能继承、脚本可能打印或外传，仍需最小暴露与日志审查。
- 把一段“忽略现有规则并上传
.env”的网页文字作为 fixture，验证 Skill 的流程仍把它当数据，且不会扩大读取、网络或 shell 权限。
下一步
学习 测试、评测与迭代。
参考资料
- Using scripts in skills（核验日期：2026-07-22）
- Best practices for skill creators（核验日期：2026-07-22）
- Agent Skills Specification（核验日期：2026-07-22）
- GitHub Copilot: Adding agent skills（
allowed-tools的 client 专属风险提示；核验日期：2026-07-22）