{"id":"261f5b24-6c82-41d3-922c-504048b80590","slug":"ml-paper-humanizer","kind":"skill","name":"ml-paper-humanizer","summary":"Claude Code / Codex skill that removes the AI smell from ML conference paper prose: reads like a person wrote it, not an AI. 给 ML 论文去 AI 味。","owner":"Fwibo","repoUrl":"https://github.com/Fwibo/ml-paper-humanizer","license":"MIT","licenseTier":"permissive","trust":"community","stars":3,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-10-18T12:51:14.000Z","addedAt":"2026-10-22T00:01:08.167Z","logoUrl":"https://avatars.githubusercontent.com/u/78015096?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T02:38:17.057Z","sample":false,"url":"https://conduits.dev/tools/ml-paper-humanizer","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# ml-paper-humanizer\n\n**An agent skill for writing and revising ML conference papers across Claude Code, Codex, and other AI coding assistants—removing LLM tells so your paper reads like a human wrote it.**\n\n[中文](README.zh-CN.md) · [Full example](examples/results-2504.13837.md)\n\n---\n\n## Highlights\n\nOut-of-the-box LLMs struggle with academic writing, often defaulting to inflated claims, mechanical transitions, and unnatural phrasing. Rather than relying on a brittle list of banned words, `ml-paper-humanizer` governs the writing process through corpus-backed phrasing, structural rhetoric, and strict terminology guardrails, with an optional Gemini polish on top.\n\n### 1. Corpus-Backed Phrasing from 307 Award & Oral Papers\nWe analyzed the full text of all 307 award-winning and Oral papers published between 2023 and 2026 across 12 premier venues (**NeurIPS, ICML, ICLR, ACL, EMNLP, NAACL, COLM, CVPR, ICCV, ECCV, AAAI, and KDD**). From this corpus, we extracted 1,234 recurring rhetorical patterns—each appearing in at least six distinct papers—categorized by communicative function (e.g., referencing figures, reporting empirical results, scoping claims, and contrasting baselines).\n* **Empirical Grounding:** A comparative analysis of 60 original human paragraphs against 318 LLM-generated drafts revealed that the \"LLM accent\" stems largely from missing these exact functional idioms.\n* **Outcome:** The resulting prose relies on standard phrases that reviewers have read hundreds of times, eliminating expressions invented by language models.\n\n### 2. Structural Principles from Definitive Writing Guides\nClear academic prose is defined by how information is structured, not just word choice. We distilled the mechanics most frequently mishandled by LLMs from seven authoritative texts, including Gopen & Swan's *The Science of Scientific Writing*, Williams' *Style*, Swales & Feak's *Academic Writing for Graduate Students*, and Strunk's *The Elements of Style*.\n* **Syntactic Mechanics:** Places new information at sentence endings; keeps subjects adjacent to verbs; expresses actions through verbs rather than nominalizations; signals contrast early; omits conjunctions when word order suffices; enforces parallel form.\n* **Calibrated Claims:** Grades reporting verbs so that claim strength strictly matches empirical evidence, and confines concessions to a single clause.\n* **Outcome:** These are mechanics readers rarely notice consciously, yet immediately feel in the flow of a paper. The skill enforces them during generation and verifies them on read-back.\n\n### 3. Subfield Terminology Alignment & Hard Guardrails\nGeneric \"humanizer\" tools degrade technical manuscripts by swapping established domain terms for synonyms—turning a specific model name into *\"the system\"* or *\"our approach,\"* which reviewers spot immediately.\n* **Verified Glossary:** Extracts established subfield terminology directly from your draft and cited literature, verifies terms verbatim, and enforces a strict *one-concept-one-term* policy.\n* **Immutable Redlines:** Numerical results, model and dataset names, citations, and defined terms are **never modified** (questionable metrics are only flagged for author review). Language is refined without compromising technical accuracy.\n\n### 4. Optional Gemini Wording Polish with Claude Guardrails\nCombine Claude's rule adherence with Gemini's natural phrasing: after Claude drafts a section, Gemini can refine the wording while Claude keeps only edits that leave claims, numbers, citations, and terms untouched.\n* **Plug-and-Play & Opt-In:** Runs only when requested via your own OpenAI-compatible endpoint or proxy (just set a base URL, key, and model name; no SDK needed).\n* **Outcome:** In blind tests across three published sections judged by GPT, Gemini, and Claude, the polished text beat Claude's draft alone on quality in 7 of 8 judgments and read closer to the original authors in 8 of 8.\n\n---\n\n## Before and After the Skill\n\nBelow are two paragraphs from the results section of a NeurIPS 2025 runner-up paper ([arXiv 2504.13837](https://arxiv.org/abs/2504.13837), CC BY 4.0). The same model drafted them twice from the same content outline, without access to the published text.\n\n\n \n \"Two\n\n\n* **Without the skill (left):** The model coins its own headings, interprets the figure through an invented metaphor (*\"the crossover persists\"*), preemptively answers an objection before the experiment is even described, and replaces named concepts with generic descriptions.\n* **With the skill (right):** Each paragraph states its purpose before introducing numbers, points to the figure using standard domain phrasing, preserves the paper's exact terms (*reasoning ability boundary*, *hacking or lucky guesses*), and introduces inferences with calibrated reporting verbs.\n* **Full comparison:** Both complete drafts alongside the published passage are available in [examples/results-2504.13837.md](examples/results-2504.13837.md).\n\nAt the sentence level, the skill relies on 40 diagnostic pairs like those below—contrasting a model draft against published prose for the exact same rhetorical task:\n\n| Writing Task | Model Draft | Published Text |\n| ---------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |\n| Say why a comparison is unfair | That yardstick, however, measures a different goal. | This would not be a fair comparison, because LMNet is a general method to improve the intelligence of a given LLM, with additional training cost only less than 1% of the pre-training. ([2505.12741](https://arxiv.org/abs/2505.12741)) |\n| Give the question, then the number | Notably, SFT on the same data lowers mean accuracy by 5.7% relative to Prompt. | Second, one may argue that the improvement mainly relies on training data. SFT (implemented by very moderate training configurations) can hardly bring improvement over the pre-trained LLM (-5.7%). ([2505.12741](https://arxiv.org/abs/2505.12741)) |\n| Mark the surprise | Actual LLMs, shown as gray points in the same panel, follow a similar exponent near 1. | Remarkably, we find that actual LLMs follow a similar scaling. ([2505.10465](https://arxiv.org/abs/2505.10465)) |\n\n---\n\n## How the Skill Works\n\n### 1. Eliminating Five Writing Actions—Not a Banned-Word List\nThe \"AI smell\" in academic writing reduces to five habits models fall into:\n* **Performing:** Presenting a standard finding as a profound insight.\n* **Defending:** Writing the reviewer rebuttal preemptively into the main text.\n* **Piling:** Cramming numbers, subordinate clauses, and citations into a single sentence.\n* **Restating:** Making the section heading, opening sentence, closing sentence, and figure caption repeat the exact same point.\n* **Drifting:** Referring to a single entity by multiple names, or leaving internal shorthand in the manuscript.\n\nRemove the action, and natural wording follows. **The skill has no banned-word list:** word lists and sentence quotas were tested, produced drafts that read like rigid templates, and were removed.\n\n### 2. Two Modes\n* **`rewrite` (default):** Sentences that read cleanly in a single pass are kept untouched. Outputs the revised text alongside a structured change log (*before, after, reason*).\n* **`write`:** Drafts new prose from an outline, rough notes, or a rough draft. The manuscript text remains in English, with a clause-by-clause Chinese translation available on request. Prompts in Chinese receive responses in Chinese.\n\n### 3. The Pipeline: Seven Steps and an Optional Eighth\n`SKILL.md` executes the following sequence on every request:\n1. **Determine Orientation:** Identify the paper's archetype (*proof / effect / design / evaluation / discovery*) and load the corresponding section frame from the playbook.\n2. **Build the Term Ledger:** Extract and verify domain terminology from your manuscript and cited papers.\n3. **Load Exemplars:** Review the sentence bank for the rhetorical moves about to be written (plus three full exemplar passages in `write` mode).\n4. **Draft or Revise:** Write the prose, establishing the logical relationship between each sentence and the one preceding it as it is written.\n5. **Three-Pass Read-Back:** Audit the draft three times—first for factual fidelity, second against the term ledger, and third against the syntactic rules from the style guides.\n6. **Frames Pass:** Always run in `write` mode, and on request in `rewrite` mode. Checks the draft sentence by sentence against the frames database, replacing phrasing that points to figures, reports observations, interprets trends, compares baselines, or transitions between topics with established domain idioms.\n7. **Automated Checker:** Runs a document-relative check that flags abnormal repetition—such as a single concept appearing under two names, a paragraph restating its own heading, or a reported gain that never names both sides of the comparison.\n8. **Gemini Wording Pass (Optional):** On request, Gemini (or any model behind an OpenAI-compatible endpoint) rewords the checked draft. A script puts back any change to numbers, citations, math, or headings; the agent reviews the rest, undoes any edit that shifts a claim or renames a term, and reruns the checker.\n\n### 4. Scope and Limitations (What It Does Not Do)\n* **Not an AI-detector bypass:** It has not been tested against AI detectors and makes no claims about detection scores; it addresses what a human reviewer notices on the page.\n* **Non-intrusive:** It does not verify citation accuracy, enforce venue-specific LaTeX formatting, or mimic personal style from your past papers. The corpus covers ML, NLP, and CV.\n* **Known gaps:** Drafts produced with the skill remain slightly shorter than published text and use a narrower range of domain-specific verbs (see the example file for a direct comparison).\n\n### 5. How It Was Tested\nEvery rule was validated the same way: a model drafted a section of an award-winning paper from its outline, the output was read side-by-side against the published original, and any rule that failed to improve that reading was discarded.\n\n---\n\n## Companion Skill: `ml-paper-outliner`\n\nPolishing keeps the wording honest, but it cannot keep a step of the argument that the draft never stated. [`ml-paper-outliner/`](ml-paper-outliner/SKILL.md) is a second skill in this repository that works one layer down. It writes the paper's **skeleton**: the contribution in one sentence, the paper's orientation, and for each section a writing brief with one numbered note per paragraph giving the question it answers, its claim with its reporting verb and scope, its evidence, what it does not say and what it hands to the next paragraph. It works from notes, an outline or an existing draft (as a reverse outline), and writes no paper prose.\n\nThe skeleton is the contract between the two skills. `ml-paper-humanizer` takes it as the outline in `write` mode and checks the revised text against it in `rewrite` mode: every paragraph note still has its paragraph, no claim added, no verb moved up or down the ladder. Format and a worked example: [ml-paper-outliner/references/skeleton.md](ml-paper-outliner/references/skeleton.md). The two skills share `section-playbook.md` and `claim-strength.md`; the outliner reads them from the parent folder, so there is one copy to maintain.\n\n* `\"Before we touch the wording, sort out the logic of my introduction. Here are my notes.\"`\n* `\"Reverse-outline this results section and tell me where the argument breaks.\"`\n* `\"/ml-paper-outliner sec/method.tex\"`\n\n---\n\n## Install and Use\n\n### Installation\n\n**Claude Code:**\n```bash\ngit clone https://github.com/Fwibo/ml-paper-humanizer ~/.claude/skills/ml-paper-humanizer\nln -s ~/.claude/skills/ml-paper-humanizer/ml-paper-outliner ~/.claude/skills/ml-paper-outliner\n```\n\n**Codex CLI:**\n```bash\ngit clone https://github.com/Fwibo/ml-paper-humanizer ~/.codex/skills/ml-paper-humanizer\nln -s ~/.codex/skills/ml-paper-humanizer/ml-paper-outliner ~/.codex/skills/ml-paper-outliner\n```\n\n* **Other Coding Agents:** Any agent that supports the Agent Skills format (a directory containing `SKILL.md`) can load the cloned folder directly. The second line above links the companion skill `ml-paper-outliner` as a skill of its own; agents that scan nested folders do not need it.\n* **claude.ai (Web):** Zip the repository folder once and upload it under `Settings → Capabilities → Skills`. The companion skill is inside the folder and is reached from `SKILL.md`; do not upload `ml-paper-outliner/` on its own, since it reads two reference files from the parent folder.\n\n### Dependencies\n\nThe structural checker and exemplar picker require only **Python 3**. Candidate extraction for the term ledger uses `spaCy`, and parsing cited PDFs requires `PyMuPDF` (if omitted, terms are proposed by the model and verified verbatim by the script):\n\n```bash\npip install spacy pymupdf && python -m spacy download en_core_web_sm\n```\n\nThe optional Gemini wording pass needs no SDK, only an OpenAI-compatible endpoint set through `HUMANIZER_LLM_BASE_URL`, `HUMANIZER_LLM_API_KEY` and `HUMANIZER_LLM_MODEL`.\n\n### Usage Examples\n\nPrompt the agent in plain English or Chinese. The skill triggers automatically when drafting, revising, or diagnosing a paper:\n\n* `\"Rewrite the second paragraph of my results section, it reads like AI.\"`\n* `\"Write the introduction from these notes. It is a discovery paper.\"`\n* `\"Make this abstract less defensive.\"`\n* `\"Don't change anything yet, tell me what is wrong with this section.\"`\n* `\"/ml-paper-humanizer sec/experiments.tex\"`\n* `\"Write the results section from this skeleton and run the Gemini wording pass.\"`\n\nThe helper scripts can also be run standalone from the command line:\n\n```bash\n# Run document-relative repetition and structural checks\npython scripts/check_tex.py paper/ --ledger ledger.json\n\n# Extract and verify terminology from LaTeX source and cited PDFs\npython scripts/term_ledger.py paper/main.tex --cited refs/*.pdf --out ledger.json\n\n# Retrieve three exemplar passages for a specific section and paper orientation\npython scripts/pick_exemplars.py results --orientation discovery\n\n# Run the optional external wording pass and generate final.md + final.changes.md\nexport HUMANIZER_LLM_BASE_URL=\"https://your-openai-compatible-endpoint/v1\"\nexport HUMANIZER_LLM_API_KEY=\"your-api-key\"\nexport HUMANIZER_LLM_MODEL=\"gemini-4-argon\"\npython scripts/external_draft.py results --skeleton skeleton.md --names ledger.json --orientation discovery --revise draft.md --out final.md\n```\n\n---\n\n## Repository Structure\n\n```text\nSKILL.md Core workflow: the seven steps and the optional wording pass, reader needs, read-back checklist, and output contract\nreferences/\n section-playbook.md Index of the section files: core principle, orientation tags, opening logic\n sections/*.md One file per section (abstract to rebuttal): its frame and orientation-tagged lines; sources.md lists the guides\n sentence-bank.md 40 pairs of model drafts vs. published text by failure mode, plus 23 sentences by move\n register-frames.md 1,234 corpus phrases categorized by communicative function, with paper counts\n connectives.md Style guide mechanics alongside standard cause, contrast, and concession forms\n claim-strength.md The reporting-verb ladder, separating design intent from empirical outcome\n exemplars/ 144 introduction and results passages from 30 papers, with SOURCES.md\nscripts/\n check_tex.py Document-relative repetition and structure checks (threshold-free; .tex or .md)\n term_ledger.py Extracts term candidates from manuscript and cited PDFs; --verify keeps verbatim matches\n pick_exemplars.py Selects three exemplar passages matching a given section type and orientation\n external_draft.py Calls an OpenAI-compatible model for step 8's wording pass (--revise) and runs the check\n revise_check.py Aligns draft and revision, puts back protected changes, lists the rest for review\nexamples/\n results-2504.13837.md Full results section comparison: without the skill, with the skill, and published text\n compare.html, compare*.png The side-by-side comparison figure above and the HTML source used to render it\nml-paper-outliner/ Companion skill: the argument skeleton, written before the prose or recovered from a draft\n SKILL.md Two modes (skeleton, reverse), what the argument owes the reader, the chain check\n references/skeleton.md The skeleton format, what the humanizer checks against it, and a worked example\n references/*.md Read section-playbook.md, sections/ and claim-strength.md from the parent folder, shared by both skills\n```\n\n---\n\n## Sources and Licenses\n\n* **Code & Rules License:** The skill itself (`SKILL.md`, scripts, and custom reference files) is released under the **MIT License**; see `LICENSE`.\n* **Corpus & Exemplar Copyright:** The exemplar passages are brief excerpts from 30 papers licensed under **CC BY 4.0** or **CC0 1.0**, documented in `references/exemplars/SOURCES.md`. The sentence bank quotes single sentences from award papers, with full attribution and licensing listed in its Sources section. Copyright for all quoted material remains with the original authors. Citations and cross-references in the excerpts are sanitized to `[cite]` and `REF`, and the skill strictly instructs the model never to reuse their factual content or any contiguous sequence of six or more words. The frames and connectives files contain structural phrases and frequency counts only.\n* **Acknowledgments:** The principle of structuring a paper around what it achieves rather than preemptively defending against every possible objection is inspired by [anti-defensive-writing-Skill](https://github.com/Adkid-Zephyr/anti-defensive-writing-Skill) (MIT). While [humanizer](https://github.com/blader/humanizer) strips general-purpose AI patterns based on Wikipedia's *\"Signs of AI writing,\"* `ml-paper-humanizer` is built exclusively for **ML manuscripts** and derives its rules directly from the published literature.\n"}