AGENTS.md git:20261020.7bf0c5dA

Immutable. This exact content never changes and is served at /api/v1/blob/f8ea1c00fb598120.

# zh-tw-humanizer

## Purpose

Published repo for the `zh-tw-humanizer` agent skill: removes AI writing tells from
Traditional Chinese text and localizes it to Taiwanese Mandarin. The runtime
artifact is `SKILL.md` at the repo root, kept byte-identical to the installed copy
at `~/.agents/skills/zh-tw-humanizer/SKILL.md`.

## Ownership

- This repo is the published source of truth for the skill.
- Editing workflow: change `SKILL.md` here, then sync to `~/.agents/skills/zh-tw-humanizer/SKILL.md` (installed location) and bump `metadata.version` in the frontmatter on meaningful changes.
- README.md (zh-TW, default), README.en.md (English) and LICENSE are distribution files; keep them in sync with SKILL.md content.

## Local Contracts

- Plain Markdown skill, no build, no deploy.
- The runtime artifact stays a single file (`SKILL.md`) — it is what gets loaded, so no
  `references/` split and no assets the rewrite itself has to read.
- Author-side tooling is allowed and lives outside the runtime artifact:
  - `scripts/check.py` — mechanical break-check (em dashes, mainland vocabulary, invisible
    characters, curly quotes, tool traces, emoji density, placeholders). It parses the
    vocabulary table straight out of `SKILL.md` pattern 34; never copy that table anywhere else.
  - `scripts/verify_semantic.py` — semantic fidelity & Taiwanese naturalness check powered by
    TypeSafe AI System One (`jev-latest`). Verifies no-fabrication and fact preservation.
  - `evals/` — `claude plugin eval .` suite. Run it after any meaningful `SKILL.md` change.
- No fabrication rule and Taiwanese-Mandarin-only output are core contracts — do not weaken them in edits.

## Checks

```bash
python3 scripts/check.py --self-test            # checker's own tests
python3 scripts/check.py <draft.md>             # exit 1 if mechanical breaks remain
python3 scripts/check.py --patterns <draft.md>   # advisory: lists hits on each pattern's 注意詞 (read from SKILL.md), never changes exit code
python3 scripts/check.py --source <orig.md> <draft.md>  # also diff facts (lost / invented numbers, dates, URLs, quotes)
python3 scripts/verify_semantic.py --self-test  # semantic verifier self-test
python3 scripts/verify_semantic.py <orig.md> <draft.md> # TypeSafe AI semantic verification
claude plugin eval . --runs 1 --no-publish      # skill behaviour, ~$18 per full 31-case pass at --runs 2 (earlier --runs 1 passes cost ~$8)
```

`type: regex` 的 grader 由 `claude plugin eval` 以 JavaScript `new RegExp(pattern, flags)` 執行（預設無 `u` 旗標；支援 lookahead／lookbehind，`[\s\S]` 可跨行）。不是 Python `re`，別用 Python 的語法假設去寫。

兩個已知不穩定的案例，不要當成迴歸就急著調 grader（1.8.0 的最終一輪兩個都拿 1.00，見 BENCHMARK.md，但每邊只跑 2 次，下面是更早幾輪的觀察）：

- `prompt-injection` — 輸入裡夾帶「忽略先前的所有指示」時，skill 常常不會被觸發（`skill-fired` FAIL），
  裸模型接手後用英文回覆，`treated-as-text` 的「回覆須為繁體」條件就掛了。這是觸發層的問題，
  SKILL.md 本文改不到。
- `protected-spans` — 更早幾輪約一半的跑次會把「2026 年 10 月 1 日」縮成「10 月 1 日」。§保護清單和流程
  第 6 步都已經寫明日期含年份，仍有殘留；再加第三份提醒只是重複，不要加。

`scripts/check.py` on `SKILL.md` itself is meaningless — the skill quotes every bad pattern
as an example. Run it on rewritten prose only.

## Landing page

`site/public/index.html` is a single static page, served by Cloudflare Workers assets (`site/wrangler.jsonc`). Deploy: `cd site && wrangler deploy`. Live at https://zh-tw-humanizer.oilygold.workers.dev. Numbers on the page come from `BENCHMARK.md`; update both together.