anti-defensive-writing 是一个用于 Codex 和 Claude Code 的写作技能（Agent skill），专门删除论文和专业文本中的防御性表达。它的安装设计非常克制：整套 install.sh 安装脚本只下载一个SKILL.md文件，配合先下载、后校验、再替换的安全机制，即使下载失败也不会破坏已有安装。本文拆解这套安装脚本的安全校验与更新机制，适合想了解 Codex skill 如何安全分发的新手阅读。

为什么"只装一个文件"值得关注 🤔

大多数工具安装器会下载整个仓库压缩包，但 anti-defensive-writing 反其道而行。查看包元数据 skill.json，可以看到明确声明：

"installed_files": [ "SKILL.md" ]

安装完成后，你的技能目录里只有这样一个结构：

<技能目录>/ └── anti-defensive-writing/ └── SKILL.md

带来的好处很直接：

• 依赖极少：不需要 Git、Python、Node.js 或包管理器，macOS/Linux 有sh和curl即可；
• 占用极小：不携带 README、图片、测试或 Agent 配置；
• 更新简单：技能规则全部集中在 SKILL.md 一个文件里，更新就是替换这一个文件。

安装脚本如何工作：三步流程

install.sh 支持--dest（目标目录）、--ref（分支/标签/提交）和--force（强制覆盖）三个参数，执行流程分三步：

1. 前置检查：确认目标位置不是符号链接、不存在已安装目录（除非加了--force），然后在目标目录下用mktemp创建临时暂存区（staging）；
2. 下载并校验：只抓取$REF/SKILL.md这一个文件到暂存区，然后检查内容是否合法；
3. 原子替换：校验通过后才删除旧目录，把暂存区整体mv为最终目录。

如果脚本是本地直接运行（而非管道执行）且未指定--ref，它会优先使用脚本旁边的本地SKILL.md，完全跳过网络下载。

安全校验机制：四道防线 🔒

这套脚本的安全设计值得单独拆解：

第一道：参数与路径检查

if [ -L "$target" ]; then echo "Destination is a symbolic link: $target. Choose another directory." >&2 exit 1 fi

拒绝写入符号链接，避免安装过程意外改动链接指向的其他位置；对--dest、--ref缺值或未知参数也会直接报错退出。

第二道：严格错误模式

脚本开头是set -eu，任何一条命令失败都会立即终止，不会"带病"继续执行。

第三道：内容校验——拒绝"假文件"

下载完成后，脚本读取第一行并校验 YAML frontmatter：

IFS= read -r first_line < "$staging/SKILL.md" [ "$first_line" = '---' ] || { echo "Invalid SKILL.md: missing YAML frontmatter." >&2; exit 1; }

如果下载回来的是 HTML 错误页或空文件，会在替换旧版本之前就被拦截。

第四道：失败自动清理

通过trap注册退出钩子，无论成功、失败还是被中断，临时暂存区都会被清除，不会在技能目录里留下.tmp残留文件。

更新机制：失败不破坏旧版本 🔄

更新是这套机制最精巧的部分。核心原则是：新文件下载并检查成功后才替换。

• 默认不覆盖：目标目录已存在时，不带--force直接运行会报错退出，已有安装原样保留；
• 先校验、后删除：脚本注释写得很清楚——Download and validate before replacing an existing installation。只有暂存区的文件通过了 frontmatter 校验，才会执行rm旧目录 +mv暂存区的动作；
• 下载失败零影响：curl -fsSL遇到 404 或网络错误会失败退出，由于替换动作还没发生，旧版本完好无损，无需手动回滚。

更新已有安装只需一条命令：

./install.sh --dest "$HOME/.agents/skills" --force

Windows 侧的 install.ps1（要求 PowerShell 7）实现了完全对等的逻辑：-Dest、-Ref、-Force参数、符号链接检测、暂存目录加try/finally清理、以及同样的"先校验后替换"顺序。

测试如何验证这些行为 🧪

仓库自带两套安装器测试，用模拟下载的方式逐条验证上述安全承诺：

• tests/test_install.py：Shell 脚本测试，覆盖四类安装目录、路径含空格、管道执行只下载SKILL.md、旧文件需--force才能清除、--ref生效、以及下载失败后旧安装保持不变；
• tests/test-install.ps1：PowerShell 脚本测试，额外校验安装文件的哈希与源文件一致、失败后暂存文件被清理。

其中最有代表性的断言是：向不存在的 ref（missing-ref）发起--force更新后，测试仍能从旧安装中读到完整且未变的技能内容——这正是"失败不破坏旧版本"承诺的自动化证明。

手动更新与常见场景 💡

• 指定版本安装：加--ref <标签或提交>（Shell）或-Ref <标签或提交>（PowerShell），适合想锁定某个稳定版本的场景；
• 手动安装：无需运行脚本，在技能目录下建anti-defensive-writing文件夹，把 SKILL.md 放进去即可；需要按目录安装的工具可改用镜像副本 skill/anti-defensive-writing/SKILL.md；
• 旧文件残留：如果技能目录里混进了别的文件，用--force更新会被重置为"只有一个 SKILL.md"的干净状态；
• 需要 clone 仓库时：仓库地址为 https://gitcode.com/gh_mirrors/an/anti-defensive-writing

小结

anti-defensive-writing 用"只装一个文件"把技能分发做到了极致精简，而 install.sh 中的参数检查、严格错误模式、frontmatter 校验和原子替换四道防线，加上 tests/ 下的自动化测试，让这套极简设计在安全性上并不缩水：装错有拦截、更新失败有兜底、过程无残留。对新手来说，这也是一个学习"如何写安全安装脚本"的很好范本。