Why use it: you clone blader/humanizer to add a pattern, edit a prompt, or open a PR. The repo has no build step, no test runner, no package.json — just one Python validator and two external check commands.
What it produces: a working tree that passes exactly the three commands CI runs, before you push.
Set up the environment
git clone https://github.com/blader/humanizer.git
cd humanizer
Requires: Python 3 (CI uses 3.12) and Node 22 for the other two check commands. There are no dependencies to install.
Three check commands — exactly what CI runs
Taken from .github/workflows/validate.yml, runs on every pull request and every push to 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 also requires running exactly these three commands before publishing.
Real output and exit codes
Healthy:
$ python3 scripts/validate-package.py
Humanizer package v2.11.2 is valid
$ echo $?
0
Broken (reproduced by changing metadata.version to 9.9.9 on a copy):
$ python3 scripts/validate-package.py
Use one package version in all files: ['2.11.2', '9.9.9']
$ echo $?
1
The validator uses raise SystemExit("<thông điệp>"), so every error exits with code 1 and prints exactly one reason line — there is no separate error code per error type. Fail-fast: it stops at the first error, and after fixing it you must run again to see the next error.
The other two commands when healthy:
$ npx --yes skills@1.5.20 add . --list
◇ Found 1 skill
◇ Available Skills
Humanizer
│ humanizer
$ claude plugin validate .
Validating marketplace manifest: <đường-dẫn>/.claude-plugin/marketplace.json
✔ Validation passed
Exactly what the validator checks
Read scripts/validate-package.py, nine gates in exact order:
| # | Gate | Breaks when |
|---|---|---|
| 1 | SKILL.md starts with YAML metadata |
missing the --- |
| 2 | block compatibility: No allowed-tools: |
field, or |
| 3 | an unsupported field is added metadata.version There is SKILL.md |
in version missing, or placing |
| 4 | at the root level | Three places with the same version SKILL.mdmismatch between plugin.json |
| 5 | , the first README entry, SKILL.md Exactly one |
usually at the repo root SKILL.md adding a second |
| 6 | plugin.json → "skills": ["./"] |
, or turning it into a symlink |
| 7 | AGENTS.md pointing the loader elsewhere |
still has all 5 Plain Language rule sentences |
| 8 | deleting a line in the "Writing style" section SKILL.md Patterns in |
numbered consecutively 1→35, and the README lists all 1–35 |
| 9 | SKILL.md adding/removing/skipping numbers, or forgetting to update the README table |
≤ 500 lines |
the prompt grows SKILL.md Currently is 456 lines AGENTS.md — 44 lines of headroom left. Adding a new pattern costs about 9–11 lines, so the 500-line ceiling is a real constraint, not a formality. "Prefer a short, clear instruction over another exception or repeated explanation."
Add or edit a pattern
Gate 8 counts every place a pattern touches four places, forget one and CI goes red:
SKILL.md— add an entry### NN. <tiêu đề>with all of Words/Phrases to watch, Problem, Before, After.README.md— add a line| NN | **Tên** | trước | sau |to the right group table.README.md— update the total number ("The 35 patterns") in the section heading.scripts/validate-package.py— updaterange(1, 36)in two places (lines 76 and 82).
Numbering must be continuous: pattern_numbers != list(range(1, 36)) compares against the ordered list, so numbers must not skip and items in the file must not be reordered.
Change the version
AGENTS.md: the version must match in three places, and must not add a version field at the root level of the skill:
grep -n 'version' SKILL.md | head -3
grep -n '^- \*\*[0-9]' README.md | head -1
grep -n '"version"' .claude-plugin/plugin.json
Include a short release note in the README for every behavior change or any non-obvious fix.
Mandatory writing rules
All comments, prompts, documentation, descriptions, validator messages and progress reports must be written in Plain Language (AGENTS.md → "Writing style"): state the main point first, use common words and the active voice, short sentences and paragraphs, one name per concept, use must for mandatory requirements, keep identifiers — commands — paths — schema fields — quotes — tracked phrases unchanged, and preserve the full technical meaning. Five of these sentences are checked word-for-word by the validator, gate 7.
Add one more rule: keep the skill portable. Do not write instructions that lock the skill to a specific agent. Claude Code, OpenCode, Codex are only examples, not limits.
Before opening a PR
python3 scripts/validate-package.py && \
npx --yes skills@1.5.20 add . --list && \
claude plugin validate . && \
echo "READY"
Getting to READY means passing exactly the set of CI gates that will run.