shuorenhua: A Chinese-First Rewrite Skill That Protects Facts While Cutting AI Tone

The Problem: AI Tone in Chinese Text, and the Fact-Drift Trap

Chinese text generated by AI tools carries a recognizable flavor: template openers, performative politeness, engineer posturing, translationese, and unsourced authority. shuorenhua targets that tone. The README's own example shows the risk: a sentence about p95 latency dropping from 480ms to 160ms can be 'cleaned' into 'the optimization significantly reduced latency,' losing the numbers and the evidence. The project's core claim is that tone removal must not change facts. It is built for developers, maintainers, and writers who draft Chinese with AI and need output that sounds human without becoming inaccurate. The repository is a skill, not a standalone tool: it is a set of instructions and rules that an AI agent follows, not a Python script you run directly.

How It Works: Scenario Detection, Protected Spans, and Tiered Rewriting

The rewrite process is not a word-replacement table. The README describes a fixed order: determine the main scenario (chat, status, docs, public-writing), mark protected spans (numbers, versions, commands, citations, responsibility subjects, factual relations), judge hit strength (Tier 1/2/3) and rewrite intensity, handle sentence and paragraph patterns first, use the phrase list only as a fallback, then do a fidelity read-back. The 'fidelity contract' is explicit: numbers and their objects stay together, relations are not rewritten (potential is not implementation), and scope, condition, negation, modality, completion, direction, and intensity are treated as facts. Abstract information is not made concrete; missing information is flagged, not invented. A bidirectional check verifies that facts from the input can be found in the output and that new relations in the output trace back to input evidence. This mechanism is more disciplined than a simple style guide, but it depends on the agent following it correctly.

Getting It Running: Commands for Claude Code, Codex, and Others

Installation varies by agent. For Claude Code, the README gives two commands: /plugin marketplace add MrGeDiao/shuorenhua and /plugin install shuorenhua@shuorenhua. For Codex, you clone the repo and run a single command: codex exec -C . "读取 ./SKILL.md，按其中规则改写以下文本：……". Other agents that support the skills command can use npx skills add MrGeDiao/shuorenhua. There are three distribution tiers: mini (dist/shuorenhua-mini.md, under 1,500 characters, self-contained), lite (SKILL.md), and full (SKILL.md plus references/). The mini tier is for single sessions or tight context windows; full is for long-term projects and public text. The README also suggests adding a trigger rule to AGENTS.md to apply the skill automatically for '去 AI 味' or '说人话' tasks, while excluding code, logs, config, and command output.

The Fidelity Contract: What It Protects and What It Refuses to Do

The fidelity contract is the project's backbone. It lists five rules: numbers and their modifiers stay together, relations are not upgraded (potential stays potential), scope and modality are facts, abstract claims are not made concrete, and missing information is flagged rather than filled in. The README gives a concrete failure mode: '展示了云原生架构的潜力' must not become '采用了云原生架构'. This is a real constraint, not a slogan. The contract also defines two read-back directions: input facts must be recoverable in the output, and every new output relation must trace back to an input basis. This is a strong guard against the common rewrite failure where a sentence becomes fluent but the meaning shifts. However, the contract only works if the agent actually performs the read-back. The project provides a zero-dependency script, python3 automation/eval/hard_metrics.py, to check word retention, dash density, and protected spans, but that is for evaluation, not for every rewrite.

Scene Packs and Scope: Context-Specific Rules and Conservative Long-Form Editing

Different text types get different treatment. Scene Packs cover README, release note, forum post, issue reply, API reference, and FAQ. Each pack has a focus: release notes list changes and limitations without a release manifesto; issue replies state reproducibility first; API references protect endpoints, methods, fields, status codes, and recovery actions. For long-form text, three scopes define how much can be cut: structural allows deleting and rearranging whole sentences, bounded (the default for long public-writing) moves empty sentences to a 'suggested deletion (pending confirmation)' list, and in-place only lowers tone within sentences without removing any. This is a thoughtful answer to the problem of over-aggressive rewriting. The bounded default is conservative, which means it may not satisfy users who want a heavily condensed rewrite, but it reduces the risk of destroying rhythm and meaning.

Evaluation Rigor: A 111-Case Benchmark and a Four-Tier Release Gate

The project takes evaluation seriously. The benchmark has 111 cases: 61 SF (should fix) and 50 SNF (should not fix), plus 20 scene samples that are evaluated separately. There are also 8 HUMAN long-form residual comparisons, but they are only for observing false positives, not for setting a 'human' threshold. The release gate from v2.1.0 has four tiers: L1 hard constraints (fabrication, protected-span drift, attribution change, scope violation) must have zero failures; SNF mis-kill rate must stay below 10%; L2 style goals are reported per model; L3 style observations are recorded but do not block. Models are tested on a blind, shuffled benchmark without expected answers. The v2.3.1 release notes claim Opus passed with zero L1 failures and 57/61 SF, but DeepSeek V4 Pro was dropped due to a real L1 issue and run-to-run variance. This is an honest limitation: results are model-dependent, and you cannot assume the same quality on your own setup.

Limitations and the Wrong Tool Cases

shuorenhua is not a universal style fixer. It is Chinese-first; the README's English section is a brief summary, and the rules are built for Chinese text. If your output is primarily English, this skill is likely the wrong tool. The bounded scope default also means it will not aggressively shorten long text; if you need a heavy rewrite, you must explicitly request structural scope. Another limitation is model variance: the release notes document that DeepSeek V4 Pro failed a real L1 constraint and showed run-to-run variance, so the skill's reliability depends on the underlying model. The HUMAN corpus is missing docs and status samples, which the check_repo flags as a known gap. Finally, the corpus text and adaptations follow their own licenses, not the repo's MIT, so if you reuse that material, you must check those licenses separately.

Alternatives: Generic Style Prompts vs. Structured Skills

The obvious alternative is a custom prompt like 'rewrite this to sound more natural' or a style guide in your AGENTS.md. That approach has no protected-span mechanism, no scene packs, and no benchmark. It relies entirely on the model's interpretation, which is exactly where fact drift happens. Another alternative is a deterministic text-processing tool that strips specific phrases, but the README explicitly argues against a pure word-replacement table, because it cannot handle context or preserve relations. shuorenhua's difference is the combination of structured rules, a fidelity contract, and an evaluation suite. That is a real contrast: a prompt is a one-shot instruction; this skill is a multi-layer rule system with a verification step. For teams that value reproducibility, the benchmark and release gate provide a level of confidence that a plain prompt cannot.

Maintenance and Upgrade Cost, and License Notes

The project is actively maintained, with releases in August 2026 and a clear versioning scheme. Upgrading means pulling new releases, which can change behavior: v2.3.1 introduced a mini distribution, expanded Scene Packs, and changed the fidelity read-back to a clause-level ledger. That means your installed skill may behave differently after an update, so you should re-test on your own text. The Claude Code plugin is the easiest way to follow updates, but manual installation requires copying files or using symlinks. The license is MIT, which permits commercial use and modification, but the README notes that the HUMAN evaluation corpus does not fall under the repo's MIT license. That is a practical detail if you plan to reuse that corpus. The maintenance cost is low for a skill: it is mostly text files and a small Python script for evaluation. The real cost is verifying that each new version still meets your quality bar on your own models.

Editorial conclusion

Adopt shuorenhua if you write Chinese-facing text with AI tools and need tone cleanup without fact drift, especially for READMEs, release notes, issue replies, or API references. Skip it if you write primarily in English or need aggressive rewriting of long-form prose; the bounded scope default is conservative. Before adopting, verify the v2.3.1 benchmark results against your own model, since DeepSeek V4 Pro was dropped due to run-to-run variance, and check the missing docs and status HUMAN samples in the eval corpus. Confirm the MIT license fits your use, and note that the HUMAN corpus is not under MIT.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes