安全维护 Agent Skill 包：Humanizer 仓库的变更规范与校验机制深度解析-平芜编程栈

AI 技能
AI 写作

【免费下载链接】humanizer

Agent skill that removes signs of AI-generated writing from text

项目地址：https://gitcode.com/GitHub_Trending/humani/humanizer

导读

本文围绕 AGENTS.md 展开，系统拆解 Humanizer 这一以 Markdown 实现的 Agent Skill 仓库的内部结构、维护规则与发布校验流程。读者将掌握：为什么一个仅由SKILL.md驱动的无构建步骤仓库需要一整套版本同步与一致性校验；如何在不破坏提示词（prompt）与跨 Agent 兼容性的前提下安全新增或重排模式（pattern）；以及如何借助 scripts/validate-package.py 在发布前自动验证包完整性。本文适用于任何维护 Agent Skill、Claude 插件或 Cursor 插件的开发者。

一、仓库定位：一个"以 SKILL.md 为唯一产品"的 Skill 包

Humanizer 是一个用 Markdown 编写的 Agent Skill，SKILL.md就是 Agent 每次调用时读取的提示词本体。AGENTS.md开篇即点明仓库的核心事实：

仓库没有构建步骤（no build step），不存在编译、打包或生成产物；
SKILL.md是唯一的 skill 文件，也是"事实来源"（source of truth）；
维护的第一原则是保持 skill 的可移植性：不要写入只绑定一两个 Agent 工具的指令，让同一份提示词能在 Claude Code、Codex、Cursor、OpenCode、Gemini CLI 等不同 Agent 间通用。

从源码结构看，整个仓库的其余文件都围绕SKILL.md服务：要么向外部平台描述它（插件清单、市场清单、OpenAI 配置），要么记录它的演化（CHANGELOG），要么校验它与周边文件的一致性（验证脚本）。因此，"改好 Humanizer" 的本质是"改好 SKILL.md 及其配套元数据"，而AGENTS.md就是这份工作的操作手册。

SKILL.md的头部 YAML 元数据给出了 skill 的身份信息（SKILL.md）：

--- name: humanizer description: | Rewrite AI-sounding text so it reads like the writer without changing what it says. Use when editing or reviewing prose for AI tells: not-X-but-Y contrasts, one-line closers, staged openers, forced triads, dashes everywhere, inflated claims, sales language, stock AI words, bold labels, or filler. Based on Wikipedia's "Signs of AI writing." license: MIT metadata: version: "3.1.0" ---

注意版本号位于metadata.version下，而不是顶层version字段——这是 Agent Skills 规范的兼容性要求，也是AGENTS.md与验证脚本共同约束的格式细节。

二、关键文件地图：每个文件在包中的作用

AGENTS.md用一段清单界定了仓库内每个文件的职责，这是理解整个包结构的最佳入口：

文件	职责
SKILL.md	事实来源，仓库唯一的 skill 文件；包含可移植 YAML 元数据、AI 文本为何听起来像 AI 的成因说明，以及按强度与频率分组、按 1 起连续编号的模式清单
README.md	面向用户的安装、使用与模式说明
CHANGELOG.md	发布说明，新版本在前；旧条目保留其发布时使用的模式编号
.claude-plugin/plugin.json	描述 Claude 插件，并将其 skill 加载器指向根目录`SKILL.md`（`"skills": ["./"]`）
.claude-plugin/marketplace.json	让用户可以把本仓库添加为 Claude 市场（marketplace）来源
.cursor-plugin/plugin.json	描述 Cursor 插件；刻意省略`skills`字段，让 Cursor 直接加载根目录的`SKILL.md`
agents/openai.yaml	面向 OpenAI 兼容 Agent 的显示名、短描述与默认提示词
scripts/validate-package.py	校验包文件与共享值的一致性

几个容易忽略但至关重要的设计决策，都能在配置文件中得到印证：

Claude 插件只有一个 skill 入口：.claude-plugin/plugin.json中"skills": ["./"]把加载器指向仓库根目录，确保所有平台读到的是同一份SKILL.md，而不是多份可能漂移的副本。
Cursor 插件不声明 skills 路径：.cursor-plugin/plugin.json中没有任何skills字段。AGENTS.md明确要求"Omit askillspath so Cursor loads the rootSKILL.md"，验证脚本也专门检查这一点（见下文）。
OpenAI 兼容入口是纯提示词：agents/openai.yaml 仅含三行内容——display_name: "Humanizer"、short_description: "Make AI-written text sound like the writer"、default_prompt: "Use $humanizer to rewrite this text in my voice without changing its facts."，把 skill 暴露为可通过$humanizer引用的工具。

三、变更规则：改动 SKILL.md 前必须遵守的六条约束

AGENTS.md的核心部分是"Rules for changes"（变更规则），它们共同维护一个前提：SKILL.md与README.md必须保持同步（keep in sync）。具体约束如下。

3.1 模式（Patterns）编号规则

模式从 1 开始连续编号、不允许跳号，强度最高、出现最频繁的模式排最前。
新增一个"AI 特征"（tell）时，只有当现有模式都无法涵盖它时才值得立为新模式；否则优先把新发现折叠进已有模式。
一旦增删或重排模式，必须同步更新 README 中的模式表格、README 的小节标题，以及SKILL.md内所有§交叉引用。
模式总数由验证脚本从标题自动推导（正则匹配### N. 名称），并与 README 表格中的模式名逐一比对。

这条规则在SKILL.md中有着清晰的落地：当前共有 26 个模式，按 A～F 六个分组（Staging instead of stating、Rhythm by rule、Inflation and borrowed authority、Formatting by rule、Leftovers from the chat and the draft、Writing for the wrong reader）组织，其中 §1～§5 是"单次出现即可修改"的最强特征，而 §8、§9、§10、§11、§21 等标记为weak alone，需要同一段落内多个特征共同出现才动手。CHANGELOG 记录了模式的演化史——例如 3.0.0 版本曾把 35 个模式合并为 25 个并重排编号，3.1.0 又新增了第 26 个模式。

3.2 版本号同步

同一版本号必须同时出现在四处：

SKILL.md的metadata.version；
CHANGELOG.md的第一个版本标题（形如## 3.1.0）；
.claude-plugin/plugin.json的version；
.cursor-plugin/plugin.json的version。

同时，禁止在 skill 的 YAML 顶层添加version字段——版本必须放在metadata之下。这一约束既保证各平台读到的包版本一致，也避免非标准的顶层字段干扰 Agent Skills 加载器。

3.3 兼容性：Agent 名称只是示例，不是上限

安装与使用说明必须保持跨 Agent 中立。Claude Code、Cursor、OpenCode、Codex 等名称在文档中只是示例，不应把指令写成某个 Agent 专属。这与仓库"单一 SKILL.md 全平台复用"的架构一脉相承。

3.4 描述（Description）一致性

插件清单（plugin manifests）必须使用SKILL.md中 description 的第一句话。实际仓库中，SKILL.md的 description 首句 "Rewrite AI-sounding text so it reads like the writer without changing what it says." 与.claude-plugin/plugin.json、.cursor-plugin/plugin.json、.claude-plugin/marketplace.json中的描述完全一致，验证脚本会强制校验这一点。

3.5 长度预算：5500 词上限

SKILL.md的每一个词都会在每次调用时被 Agent 读取，因此它有一项严格的成本预算：验证脚本将字数上限设为 5,500 词。AGENTS.md对此的措辞是"a change that adds words should earn them"——新增的每个词都应当换来等价的表达价值。这一约束从根源上防止提示词无限膨胀拖慢每次调用。

3.6 历史与发布前检查

任何行为变更或不明显的修复，都必须在CHANGELOG.md中添加一条简短说明；
发布前必须依次运行三条检查命令：
- python3 scripts/validate-package.py
- npx skills add . --list
- claude plugin validate .

CHANGELOG.md本身也是维护规则的一部分：旧条目必须保留其发布时使用的模式编号。例如 3.0.0 的条目记录了完整的"旧编号→新编号"映射表（1→13, 2→17, 3→15...），让历史版本的读者仍能对照当时的编号体系。这正是AGENTS.md要求"old notes keep the pattern numbers their release used"的原因。

四、发布前校验：validate-package.py 逐项解析

scripts/validate-package.py 是整个维护流程的自动化核心，它"不依赖任何外部包"（docstring 明确说明 "without external dependencies"），只用标准库json、re、pathlib实现。逐项阅读源码，可以还原它实际检查的全部内容：

4.1 文件可读性与 JSON 合法性

脚本启动即读取SKILL.md、README.md、CHANGELOG.md，并解析三个 JSON 文件（.claude-plugin/plugin.json、.cursor-plugin/plugin.json、.claude-plugin/marketplace.json）。任何文件缺失、读取失败或 JSON 语法错误都会立即以SystemExit终止，并给出带相对路径的提示（如Cannot read .claude-plugin/plugin.json: ...或Fix the JSON in .cursor-plugin/plugin.json: ...）。

4.2 YAML 元数据约束

要求SKILL.md必须以---\n...\n---的 YAML 块开头；
禁止顶层出现version:、compatibility:、allowed-tools:三个非标准字段（源码第 48-50 行逐一遍历并报错）；
要求metadata.version存在且为数字.数字.数字的三段式版本号。

4.3 版本一致性校验

脚本收集四处的版本号——SKILL.md的metadata.version、CHANGELOG.md第一个## x.y.z标题、Claude 插件的version、Cursor 插件的version——放入一个集合。若集合大小不为 1，说明四处版本不一致，直接报错Use one package version in all files: {...}。这正是AGENTS.md中"同一版本出现在四个位置"规则的机器化落地。

4.4 skill 文件唯一性与加载路径

递归搜索整个仓库，确认只存在一个位于根目录的普通SKILL.md（不是符号链接、没有第二份副本）；
要求.claude-plugin/plugin.json的skills字段严格等于["./"]，即 Claude 加载器指向仓库根；
要求.cursor-plugin/plugin.json的name为humanizer，且不得包含skills字段——否则 Cursor 会去寻找自定义路径而不是根目录的SKILL.md。

4.5 描述一致性校验

脚本把SKILL.md中description: |缩进块的内容折叠为单行，并收集 Claude 插件、Cursor 插件、市场清单中的全部 description，要求：

所有清单描述完全相同（集合大小为 1）；
且SKILL.md描述以该共同描述开头（即清单使用第一句话）。

4.6 模式编号与 README 同步

这是校验器最精巧的部分：

从SKILL.md用^### ([0-9]+)\. (.+)$提取全部模式标题，要求编号是从 1 开始的连续整数序列；
从README.md用^| ([0-9]+) \| \*\*(.+?)\*\*提取表格中的模式编号与名称，要求编号集合与SKILL.md完全一致；
逐号比对模式名称，任何不一致都会报错Match the README pattern names to SKILL.md: ...；
要求 README 的模式小节标题精确等于## The {总数} patterns（例如当前为## The 26 patterns）；
最后扫描SKILL.md中所有§数字交叉引用，确保每个引用都指向 1 到模式总数范围内的有效编号——防止重排编号后留下指向错误或不存在模式的死引用。

4.7 字数预算

脚本用SKILL.split()统计SKILL.md的总词数，超过 5,500 即报错。这也是AGENTS.md中长度约束的直接实现。

全部检查通过后，脚本输出一行结果：Humanizer package v3.1.0 is valid。整条流水线证明：Humanizer 的"包"不是一个构建产物，而是一组必须彼此一致的文件约束，校验器正是这些约束的机器执行者。

五、写作风格规范：Plain Language 原则

AGENTS.md要求仓库内的一切文本——代码注释、提示词、文档、描述、校验消息、进度报告——都遵循 Plain Language（简明英语）原则。这不是随意的偏好，而是有明确技术动机的：

提示词即产品：SKILL.md下方从## Why AI text sounds the way it does开始的正文就是 Agent 每次实际读取的提示词，措辞直接影响改写质量；
面向多 Agent 复用：同样的文本会被不同 Agent 及其开发者阅读，简明语言能降低误解成本。

AGENTS.md给出的具体规范包括：

先给出主要观点（lead with the main point）；
使用常用词与主动语态（common words, active voice）；
句子与段落保持简短；
同一事物始终使用同一个术语（one term for the same item）；
用must表达硬性要求；
善用标题、列表与表格辅助阅读；
删去重复或多余词汇；
限制缩略语并解释技术术语；
避免双重否定；
保留精确的标识符、命令、路径、schema 字段、引文、受监控短语（watched phrases）与承载行为含义的示例——这些内容即使违反简明原则也不能简化，因为它们是机器与人类共同依赖的精确信息；
保持完整的技术含义（keep the full technical meaning）。

这些原则在仓库中有大量实例。例如SKILL.md的 §8 规则是绝对化表述："The final rewrite must not contain em dashes (—) or en dashes (–) unless the writer's sample uses them"；校验脚本的错误消息则直接使用must与动词开头的祈使句，如 "Keep SKILL.md at 5,500 words or fewer"、"Number SKILL.md patterns from 1 upward without gaps"。

六、编辑 SKILL.md 的三个操作准则

AGENTS.md在最后给出编辑 skill 本身的三条准则，可以视为对全文规则的浓缩：

保持 YAML 元数据合法——任何结构改动都不能破坏解析器依赖的元数据格式；
把元数据下方的提示词当作产品本身——它不是"说明文档"的附属品，而是用户实际消费的核心资产；
优先用一条简短清晰的指令，而不是再加一条例外或重复解释——这与 5,500 词预算互相呼应：提示词越精简，Agent 每次读取的注意力越集中，行为越稳定。

结合 SKILL.md 的实际结构可以看到这套准则的成果：26 个模式共用同一套"Watch for / Problem / Before / After"模板，每个模式只讲一件事；工作流被压缩为"标记特征 → 起草改写 → 对照检查 → 写出终稿"四个步骤；"何时不动手"（When not to act）与"保留哪些细节"（Keep the details that carry the writer's voice）作为独立章节放在末尾，避免在主流程中堆砌例外。

七、实操：一次完整的维护演练

将上述规则串联起来，一个规范的 Humanizer 变更流程应该是：

评估：通读SKILL.md，判断新发现的 AI 特征能否被现有 26 个模式涵盖；若能，则折入现有模式并只补充 watch list 或示例；若不能，才考虑新增模式（编号接在 26 之后）。
同步修改：在SKILL.md中更新模式正文与§引用；在README.md中同步模式表格、小节标题（## The N patterns）与使用说明；在CHANGELOG.md顶部添加新版本条目（新版本号，最新在前）。
版本对齐：将同一版本号写入SKILL.md的metadata.version、CHANGELOG.md首条标题、.claude-plugin/plugin.json与.cursor-plugin/plugin.json；确认没有在 YAML 顶层引入version字段。
自检：运行python3 scripts/validate-package.py，直到输出Humanizer package vX.Y.Z is valid；再运行npx skills add . --list与claude plugin validate .验证跨平台可安装性。
文字把关：按 Plain Language 规范审阅新增措辞，确认每个新增词都"挣得了"它的位置，且所有精确标识符（命令、路径、watched phrases）一字未改。

这套流程的价值在于：它把"维护一个提示词包"从纯手工的文字编辑，变成了有机器校验兜底的工程化流程。任何一个环节的遗漏——版本没对齐、README 表格没同步、模式编号出现断号——都会被validate-package.py在发布前拦截，从而保证用户在任何平台安装到的都是同一个、自洽的 Humanizer。

结语

AGENTS.md虽然只有几十行，却精确刻画了 Humanizer 仓库的全部维护契约：单一SKILL.md的产品架构、八个关键文件的职责划分、六条变更规则、一套由 scripts/validate-package.py 机器执行的发布校验，以及贯穿始终的 Plain Language 写作规范。对任何想要维护或复刻一个跨 Agent Skill 包的开发者而言，这份文档连同仓库中的实现，就是一份可以直接借鉴的工程模板。