dym-humanizer-contributor-validate-and-release

用途

该技能用于修改 Humanizer 本身，面向贡献者：当你克隆 blader/humanizer 仓库以添加 pattern、修改 prompt 或提交 PR 时，用它来在推送前本地复现 CI 会运行的校验。仓库没有构建步骤、没有测试运行器、没有 package.json，只有一个 Python 校验器和两条外部检查命令。

环境准备

git clone https://github.com/blader/humanizer.git
cd humanizer

需要 Python 3（CI 使用 3.12）以及 Node 22 用于另外两条检查命令。没有需要安装的依赖。

三条校验命令

以下命令取自 .github/workflows/validate.yml，在每次 pull request 和每次推送到 main 时运行：

python3 scripts/validate-package.py
npx --yes skills@1.5.20 add . --list
npm install --global @anthropic-ai/claude-code && claude plugin validate .

AGENTS.md 也要求在发布前运行这三条命令。

输出与退出码

通过时：

$ python3 scripts/validate-package.py
Humanizer package v2.11.2 is valid
$ echo $?
0

失败时（示例：在副本中把 metadata.version 改为 9.9.9）：

$ python3 scripts/validate-package.py
Use one package version in all files: ['2.11.2', '9.9.9']
$ echo $?
1

校验器使用 raise SystemExit("<消息>")，因此所有错误都以退出码 1 结束，并只打印一行原因，没有按错误类型区分的独立错误码。它是 fail-fast：在第一个错误处停止，修复后需重新运行才能看到下一个错误。

另外两条命令通过时：

$ npx --yes skills@1.5.20 add . --list
◇  Found 1 skill
◇  Available Skills
Humanizer
│    humanizer

$ claude plugin validate .
Validating marketplace manifest: <路径>/.claude-plugin/marketplace.json

✔ Validation passed

校验器检查的内容

读取 scripts/validate-package.py，共有九道检查，按顺序如下：

SKILL.md 以 YAML 元数据开头——缺少 --- 块时失败。
不得有 compatibility: 或 allowed-tools: 字段——添加不支持的字段时失败。
SKILL.md 中必须有 metadata.version——缺失，或把 version 放在根级时失败。
三处版本一致——SKILL.md、README 第一个条目、plugin.json 之间不一致时失败。
仓库根目录只有一个普通 SKILL.md——添加第二个 SKILL.md，或把它变成符号链接时失败。
plugin.json 中 "skills": ["./"]——指向别处时失败。
AGENTS.md 保留全部 5 条 Plain Language 规则——删除 "Writing style" 部分中的一行时失败。
SKILL.md 中的 pattern 编号连续 1→35，且 README 列出完整 1–35——增删、跳号，或忘记更新 README 表格时失败。
SKILL.md 不超过 500 行——prompt 膨胀时失败。

目前 SKILL.md 有 456 行，还剩 44 行余量。新增一个 pattern 大约占 9–11 行，因此 500 行上限是真实约束，不是形式要求。AGENTS.md 明确写道："Prefer a short, clear instruction over another exception or repeated explanation."

新增或修改 pattern

第 8 道检查意味着一个 pattern 涉及四处，漏掉任何一处 CI 都会变红：

SKILL.md——添加 ### NN. <标题> 小节，包含完整的 Words/Phrases to watch、Problem、Before、After。
README.md——在对应分组表格中，于 | NN | 名称 | 之前/之后添加一行。
README.md——修改章节标题中的总数（"The 35 patterns"）。
scripts/validate-package.py——修改两处 range(1, 36)（第 76 行和第 82 行）。

编号必须连续：pattern_numbers != list(range(1, 36)) 按有序列表比较，因此不能跳号，也不能颠倒文件中各小节的顺序。

修改版本号

AGENTS.md 规定：版本必须在三处一致，且不得在 skill 根级添加 version 字段：

grep -n 'version' SKILL.md | head -3
grep -n '^- \*\*[0-9]' README.md | head -1
grep -n '"version"' .claude-plugin/plugin.json

对于任何行为变更或任何不明显的修补，需在 README 中附一条简短的发布说明。

强制写作规则

所有注释、prompt、文档、描述、校验器消息和进度报告都必须使用 Plain Language（AGENTS.md → "Writing style"）：先讲要点，使用常用词和主动语态，句子和段落简短，一个概念一个名称，用 must 表示强制要求，保留标识符——命令——路径——schema 字段——引用——被跟踪短语，并保持完整技术含义。其中五条规则会被校验器逐字检查，即第 7 道检查。

另有一条规则：保持 skill 可移植。不要写死针对某个特定 agent 的指令。Claude Code、OpenCode、Codex 只是示例，不是限制。

提交 PR 前

python3 scripts/validate-package.py && \
npx --yes skills@1.5.20 add . --list && \
claude plugin validate . && \
echo "READY"

输出 READY 即表示通过了 CI 将运行的全部检查。

适用场景与限制

适用于 Humanizer 仓库的贡献者工作流：添加 pattern、修改 prompt、更新版本、准备 PR。限制包括：仓库无构建步骤与测试运行器；校验器 fail-fast，一次只报一个错误；SKILL.md 有 500 行硬上限；pattern 编号必须连续且 README 同步；版本需三处一致；文档必须使用 Plain Language。