这是一篇聚合型实操课(aggregate),不是工具横评(compare)。我把「带脚本 Skill」散落在各处的四类风险、权限模板、8 项审计清单、3 个真实翻车聚到一篇里,按合并前的顺序排好。本课只干一件事:给你的 Skill 加一个只读脚本,并在合并前过完审计闸。文末有可复制的脚本和四条验证命令,跑完就能交作业。
第 2 课里我们把 referência/ 和「先写计划文件再执行」校验环跑通了(上一课:给 Skill 加 reference/ 与「先写计划文件再执行」校验环)。这一课往前走一步:允许 Skill 带脚本——仓库里出现 .py / .sh / 可执行入口时,怎么审计、怎么设权限、怎么只从可信来源安装。
我自己踩过的坑:为了「省事」把一段临时清洗 CSV 的脚本塞进 Skill,同事在另一台机器触发时,脚本写了绝对路径,还 curl 了一个我忘了删的调试域名。演示没炸,值班炸了。默认立场很硬:脚本是能力,也是攻击面;没过审计清单,就别合并。
本课目标与你会带走什么

学完本课,你应该能独立完成三件事:
- 给「带脚本的 Skill」写一份最小安全审计表(来源、权限、副作用、回滚)。
- 把脚本权限收成:只读默认、写操作必须计划文件、外网默认关。
- 用至少 3 条真实报错/拒绝用例验证:不该跑的脚本真的跑不起来。
不追求把你变成安全研究员;追求你合并前敢签字。若团队还没有「Skill 可执行附件」规范,本课清单可以直接贴进 PR 模板。
前置条件(没做完第 2 课请先回去)
- 已完成第 1 课最小 Skill:30 分钟写出第一个会自动触发的 Claude Agent Skill.
- 已完成第 2 课 reference + 计划文件:第 2 课原文.
- 本地能打开 Skill 目录结构:至少有
SKILL.md;本课会新增scripts/(或官方约定的可执行附件目录)。 - 心里有数:生产密钥不进 Skill 仓库;演示用假数据。
若你跳过第 2 课直接挂脚本,我建议先回去——没有计划文件约束的写脚本,等于把「模型一时兴起」接到了文件系统。
概念:Skill 为什么会带脚本,风险在哪

官方与社区里,Skill 常把重复劳动下沉成脚本:格式转换、仓库扫描、固定 API 调用。好处是确定性高、token 省;坏处是一旦触发,行为不再只是「生成文本」,而是真的执行.
我把风险拆成四类,写进审计表:
- 来源风险:脚本从哪来?是你自己写的、同事 PR、还是网上下的「一键 Skill 包」?未知来源默认拒装。
- 权限风险:脚本能否写盘、改 git、访问外网、读
~/.ssh/ 环境变量?默认应最小。 - 触发风险:description 是否太宽,导致闲聊也拉起危险脚本?
- 供应链风险:脚本再
pip install/curl | bash了什么?二次下载等于把信任链拉长。
Anthropic 文档里强调 Skill 的渐进披露与文件捆绑;我的实践补充一句:捆绑得越方便,审计清单越不能省。目录结构看起来干净,真正脏的是 scripts/ 里那几行你以为「临时」的代码。
分步实操:加一个只读脚本并挂上审计

步骤 1:新建 scripts/ 并写最小只读脚本。例如统计仓库里 TODO 数量的 Python,只读文件系统、不写、不联网。入口参数全部显式传入,禁止读未声明路径。
# scripts/count_todo.py:只接受 --root;拒绝 .. 与绝对路径逃逸;不读环境密钥
# 完整可运行版本见文末「落地」节
这段脚本骨架我建议照着三条原则写:第一,参数先校验再干活,--root 解析成真实路径后必须仍在用户项目目录之内,否则直接退出并打印拒绝原因;第二,只遍历白名单扩展名(例如 .pye.mde.ts),遇到二进制、隐藏目录和符号链接一律跳过;第三,输出只写到标准输出,格式固定为「文件路径 + 行号 + 摘要」,不落盘、不调用网络、不读取任何环境变量。这样模型拿到结果后只负责解释和归类,真正的确定性动作留给脚本,而脚本本身又没有任何能造成副作用的能力。退出码也要约定清楚:零代表正常完成,非零代表被拒绝或参数错误,SKILL.md 里写明遇到非零时模型应原样转述错误、不要自作主张换参数重试。
步骤 2:在 SKILL.md 写清何时可调用。description 里写「仅当用户明确要求扫描 TODO / 技术债清单时」;禁止「帮助整理代码」这种宽触发。引用第 2 课:危险或有副作用的动作前,先写计划文件,用户确认后再执行。
步骤 3:权限清单进仓库。我习惯在 Skill 根放 SECURITY.md 或在 SKILL.md 专节列出:允许路径、禁止路径、是否允许网络、是否允许写、失败时如何停。
步骤 4:本地跑拒绝用例。故意用越界路径、缺计划文件、description 不匹配的闲聊,确认脚本不被调用。三条过不了,PR 不合并。
步骤 5:记录审计结论。谁审的、哪天、脚本 hash 或 commit、残留问题。没有记录等于没审。
权限边界模板(可直接抄)

| 项 | Por predefinição | 放宽条件 |
|---|---|---|
| 读仓库相对路径 | 允许(白名单扩展名) | 无 |
| 写文件 | 禁止 | 计划文件已确认 + 目标在白名单目录 |
| 外网 / curl | 禁止 | 单独「网络工具」Skill,且域名白名单 |
| 读环境变量 | 仅白名单非密钥项 | 密钥走本地密钥管理,不进脚本参数日志 |
| Instalação de dependências | 禁止运行时安装 | 依赖锁在镜像/开发机预装 |
有人会说「这样太严,Skill 不好用」。我的经验是:先严后宽。宽权限一旦进共享目录,收回成本远高于一开始多写两行白名单。团队真有稳定写盘场景,再开第二条「写权限 Skill」,而不是把只读 Skill 偷偷改宽。
安全审计清单(合并前勾选)

- 脚本来源:本人/本团队 PR,或已签名的内部源;拒绝来路不明 zip。
- 无
curl | bash、无运行时pip install、无下载后 exec。 - 路径:规范化后仍落在允许根目录;拒绝符号链接逃逸(能测则测)。
- 密钥:脚本与日志不打印 token;示例用假值。
- 触发:至少 5 条「不该触发」用例写在测试或 PR 描述。
- 计划文件:凡写/外网/付费,必须先计划后执行。
- 回滚:说明如何停用该 Skill(移出目录 / 关开关)。
- 复核人:非作者至少一人看过
scripts/diff。
我把这份清单贴进过两个小队的 PR 模板。第一周会有抱怨;第二周开始,有人靠它拦住了「顺手加的上传脚本」。拦一次就值回票价。
常见报错与翻车

报错 1:脚本触发了,但工作目录不对。现象是相对路径读到 Skill 目录而非用户仓库。修法:显式传 --root,并在 SKILL.md 写「必须以用户当前项目根为 root」。我第一次没写,清洗脚本把 Skill 自己的 README 改了——很羞,但很好记。
报错 2:description 过宽,闲聊也拉起扫描。用户说「帮我看看项目怎么样」,模型兴致勃勃跑全库扫描。修法:收紧触发词;加否定例;和第 2 课一样用失败用例迭代(预告第 4 课会系统做)。
报错 3:计划文件有了,脚本仍在确认前预跑。有的编排会「先试跑再展示」。对只读或许能忍,对写盘绝不行。修法:执行器层拦截——无确认标记则不调用 exec;单测覆盖。
额外翻车:把「临时调试 print」连同本地绝对路径提交。审计 diff 时搜 /Users/e/home/eAPI_KEY。脏一次,CI 加 grep 门禁。
练习:给自己的 Skill 加只读脚本并完成审计

作业(建议 45–90 分钟):
- 选一个已有 Skill(或新建),加一个只读脚本(统计、检查、只读报告均可)。
- 补齐 SKILL.md 触发边界 + SECURITY 段落 + 计划文件要求(若你预留了写权限开关,默认仍关)。
- 跑满审计清单 8 项,把勾选结果贴进 PR 或个人笔记。
- 写 5 条拒绝用例并实际试一次(至少 3 条应拒绝成功)。
验收标准:同事(或未来的你)只看仓库,不看你聊天记录,也能判断「这脚本在什么条件下会跑」。做不到,说明文档还在骗自己。自测只问一句:这个 Skill 进了共享目录,最坏能删掉什么、读到什么、往外网发什么?答不上来,就别开写权限。
落地:安装、跑通、配置、翻车、验收

① 安装。脚本放进 Skill 自己的 scripts/,不要放进用户项目。个人 Skill 在 ~/.claude/skills/<名字>/,项目 Skill 在仓库的 .claude/skills/<名字>/。下面这份我在 Python 3 上实际跑过,只用标准库,不用装依赖:
#!/usr/bin/env python3
"""只读:统计 --root 下白名单文件里的 TODO。不写盘、不联网、不读环境变量。"""
import argparse, pathlib, sys
ALLOW_EXT = {".py", ".md", ".ts", ".js"}
def main():
p = argparse.ArgumentParser()
p.add_argument("--root", required=True)
args = p.parse_args()
cwd = pathlib.Path.cwd().resolve()
root = (cwd / args.root).resolve()
if root != cwd and cwd not in root.parents:
print(f"REFUSED: {args.root} 越出当前项目目录", file=sys.stderr)
return 2
hits = 0
for f in sorted(root.rglob("*")):
rel = f.relative_to(root)
if f.is_symlink() or not f.is_file() or f.suffix not in ALLOW_EXT:
continue
if any(part.startswith(".") for part in rel.parts):
continue
for n, line in enumerate(f.read_text(errors="ignore").splitlines(), 1):
if "TODO" in line:
hits += 1
print(f"{rel}:{n}: {line.strip()[:80]}")
print(f"TOTAL {hits}")
return 0
if __name__ == "__main__":
sys.exit(main())
② 跑通。在用户项目根目录执行(cwd 就是边界,所以必须在项目根跑):
$ python3 ~/.claude/skills/todo-scan/scripts/count_todo.py --root src
app.py:1: # TODO: 拆分 parse()
notes.md:2: # TODO: 补测试
TOTAL 2 # exit 0;src/leak.py 是指向 /etc/passwd 的符号链接,被跳过
③ 配置。SKILL.md 只加三行,别多写:
## 脚本
- 仅当用户明确要求「扫描 TODO / 列技术债」时运行 scripts/count_todo.py,必须传 --root(项目内相对路径)。
- 退出码非 0:原样转述 stderr,不换参数重试,不改用其他命令绕过。
- 本脚本只读;任何写操作先按第 2 课写计划文件,等用户确认。
④ 翻车演练。下面三条必须全部失败,任何一条返回 0 就说明边界漏了:
$ python3 .../count_todo.py --root ../ # REFUSED: ../ 越出当前项目目录 exit 2
$ python3 .../count_todo.py --root /etc # REFUSED: /etc 越出当前项目目录 exit 2
$ python3 .../count_todo.py # argparse: --root is required exit 2
我最常见的翻车是在 Skill 目录里跑:cwd 变成 Skill 自己,脚本扫到的是 SKILL.md,结果看着「正常」。所以结果里出现 scripts/ 或 SKILL.md,先怀疑 cwd。第二个坑是用 startswith 比字符串判断路径边界,/repo-evil 能过 /repo 的前缀检查;上面用的是 parents,比的是路径层级,不是字符串前缀。
⑤ 验收。四条命令的输出连同退出码贴进 PR,外加审计清单 8 项勾选。合并条件就四条:scripts/ 默认只读、默认不联网;SECURITY.md 写清允许路径和退出码;越界用例全部 exit 2;description 的触发语足够窄。缺一条就不合并。
下一课预告与本系列目录

下一课预告:第 4 课会专门讲「用真实失败用例迭代 description」——把误触发/不触发案例收成回归集,改完 description 再跑一遍。带脚本之后,触发边界更值钱,所以顺序放在本课之后。
本系列目录(Claude Agent Skill 实战):
- Lição 1: Criar, em 30 minutos, a primeira «Claude Agent Skill» que se ativa automaticamente
- Lição 2: Adicionar uma referência ao Skill / O ciclo de verificação «escrever primeiro o documento de planeamento e só depois executar»
- 第 3 课:带脚本的 Skill 与安全审计(本文)
- 第 4 课:用真实失败用例迭代 description(系列内下一课)
- 第 5 课:把 Skill 接到真实仓库 CI / 团队共享目录(规划中)
若你本课作业卡住,优先把「外网默认关」和「写操作要计划文件」两条落地,其它条目可以下周补;别为了赶进度把危险默认值合并进共享目录。
最后一句不客气的话:合并按钮比脚本短,责任链比 diff 长。按住合并前,再扫一眼 scripts/。


评论列表 (0条):
加载更多评论 Carregando...