An Agent Skill that helps AI agents write and revise academic text the way a careful expert would.
Draft papers and theses from your own notes · remove AI writing tells · restore the explanation compressed text leaves out · find and verify real citations · keep every equation and number intact
English · 中文
Language models write fluent academic prose that readers still struggle with. It opens by saying what the work is not, calls everything "crucial", packs three undefined terms into one sentence, and sometimes cites papers that do not exist. academic-writing gives your agent the rules that editors, style manuals and thesis examiners have applied for decades, a workflow that keeps you in charge of the content, and scripts that catch what a tired reader misses.
- See the difference
- What you get
- Quick start
- How it works
- Built-in checkers
- How it compares
- Grounded in the literature
- FAQ
- Roadmap
- Contributing and feedback
1. AI tells removed, facts kept.
Before: In today's rapidly evolving research landscape, sensor calibration plays a pivotal role in ensuring accuracy. This is not merely a technical step; it is a fundamental pillar of reliable measurement, highlighting the importance of rigorous protocols.
After (using the author's data): Without calibration the sensor reads 4 % high at 30 °C; after calibration the error stays below 0.3 %. We therefore calibrate before every run.
2. Compressed jargon turned into an explanation.
Before: We regularise via L2 and select λ by CV; the bias–variance trade-off then yields optimal generalisation.
After: We add a penalty proportional to the squared size of the model coefficients (L2 regularisation), which pulls them towards zero. Its strength λ is chosen by cross-validation [AUTHOR: how many folds?]: we fit the model on part of the data and keep the λ that predicts the held-out part best. A larger λ makes the fitted model less sensitive to noise in the training data, at the cost of a small systematic error.
The gap the author must fill is marked instead of guessed.
3. A fabricated reference caught before submission.
$ python scripts/check_references.py refs.bib
| Key | Status | Detail |
|----------------|---------------|---------------------------------------------------------------|
| mensh2017 | ok | Mensh 2017, PLOS Computational Biology |
| wrongtitle2014 | mismatch | title differs (similarity 0.24); record title: "Ten Simple…" |
| fabricated2023 | doi-not-found | the DOI does not resolve; may be mistyped or fabricated |
| nodoi2014 | found-add-doi | likely DOI 10.1371/journal.pcbi.1003833 |
| Generate | Abstracts, introductions, literature reviews, methods, results, discussions, thesis chapters, reports and reviewer replies, written from your notes, data and references, with an outline in topic sentences first and a list of questions for you at the end. |
| Revise | A prioritised audit (structure first, word choice last), questions for the things only you know, suggested edits with the rule behind each, a check that nothing factual changed, and a change log. |
| Remove AI tells | Catalogues of 22 English and 19 Chinese patterns, each with an evidence level, an explanation of what it costs the reader, and a before/after repair. |
| Real citations | With a search tool, the agent finds candidate sources, confirms each exists, matches its metadata and supports the claim, and asks you to approve it. Without one, it marks [CITE: …] and never invents a reference. |
| Science and maths | Define before use, no forward references, symbols with type and units, equations punctuated as prose, captions that stand alone, limitations stated plainly. Draws on physics and mathematics style authorities. |
| LaTeX aware | A structural audit that follows \input/\include across a whole thesis, plus an invariant check and latexdiff recipes for reviewers. |
| Bilingual | English and Chinese rules, scripts and documentation. |
Claude Code
git clone https://github.com/ky001sg/academic-writing ~/.claude/skills/academic-writingFor a single project, clone into .claude/skills/academic-writing inside it.
Claude apps: download academic-writing.zip from the latest release and upload it as a custom skill in the app's skill settings.
Other agents that support the Agent Skills format: copy the folder into the agent's skills directory.
Then ask as you normally would:
Write a 200-word abstract from notes.md. Cite only the papers listed there.
Turn my results bullet points into a Results section; mark anything you need from me.
Check thesis/main.tex for undefined acronyms, forward equation references and unreferenced figures.
Find and verify sources for the three claims marked [CITE] in section2.tex.
Draft a response to reviewer 2 and a marked-up diff of my changes.
帮我把这份周报去掉AI味，但不要改动数字。
flowchart LR
A["Your notes, data<br/>and references"] --> G[Generate]
B[Existing draft] --> R[Revise]
C[Reviewer comments] --> P[Respond]
G --> Q{"Self-check<br/>tells · definitions · citations · invariants"}
R --> Q
P --> Q
Q --> O["Readable text<br/>+ questions for you"]
Six ground rules apply in every mode: write for a named reader; take content from the author and citations only from verified sources; describe problems as reader problems, never as guesses about AI authorship; explain where the reader needs it; keep equations, numbers and citations fixed; and let the author decide.
Standard-library Python, read-only. All run offline except check_references.py.
| Script | What it finds |
|---|---|
prose_audit.py |
AI tells, stacked hedges, vague attribution, nominal chains, negative openings, chat residue; English and Chinese; paragraph and rhythm statistics |
latex_audit.py |
Forward equation references, undefined or duplicate labels, figures never cited or cited out of order, missing display punctuation, sentences starting with symbols, acronyms used before definition, short or uncredited captions, obsolete LaTeX, chapters without equations |
check_invariants.py |
Any change to math, citation keys, labels, references, graphics, URLs or numbers between two versions |
check_references.py |
DOIs that do not exist, titles that do not match their DOI, likely DOIs for entries without one (queries Crossref with titles and DOIs only) |
latex_audit.py reads a complete multi-file thesis in a couple of seconds.
| Typical "humanizer" prompts | academic-writing | |
|---|---|---|
| Goal | Make text sound less like AI, often by shortening it | Make text easier for a real reader to follow; often adds explanation |
| Missing facts and sources | Frequently filled in plausibly | Marked for the author; citations searched and verified, never invented |
| Equations, numbers, citations | Can change silently | Checked by script before and after |
| Scientific structure | Rarely addressed | Definitions, notation, forward references, captions, limitations |
| AI detectors | Often the target | Deliberately not a target; detectors are unreliable and biased against non-native writers |
| Evidence | Lists of words | Each pattern graded by the strength of published evidence |
Every rule is paraphrased and attributed. The main sources are:
- Style: Strunk (1918), Gopen & Swan (1990), Pinker (2014), Williams, Mensh & Kording (2017), Whitesides (2004)
- Physics and mathematics: Mermin (1989), the AIP Style Manual, the APS Physical Review style guide, Halmos (1970), Knuth, Larrabee & Roberts (1989), Tsitsiklis, Tao
- Theses and review: Golding et al. (2014) on what examiners do, university guidance on theses that include publications, guidance on responding to reviewers
- AI-assisted text: Kobak et al. (2025), Liang et al. (2024), Reinhart et al. (2025) on measured style markers; studies of detector reliability; publisher policies
The full bibliography, with verification status and licence for each source, is in references/sources.md.
Will it make my text undetectable by AI detectors? No, and it does not try. Detectors are unreliable and misjudge non-native writers. The skill makes text clearer, which is what readers, reviewers and examiners care about.
Will it write my paper for me? It drafts from your material: your results, your derivations, your references. Anything it does not know is marked as a question. You remain the author, and you should disclose AI assistance where your institution or journal requires it; the skill includes a disclosure template.
Is my text sent anywhere?
The scripts run locally. Only check_references.py goes online, and it sends titles and DOIs to Crossref, never your text. What your agent does with your text depends on the agent you use.
Does it work outside Claude? Any agent that supports the Agent Skills format can load it, and the scripts run on their own with Python 3.8+.
Does it only handle physics? The writing rules apply to any discipline. The mathematics, notation and LaTeX parts are most useful in the sciences and engineering.
Why does my agent sometimes mention this repository?
Once per conversation, after a completed task, the skill may add one line to the chat suggesting a star or feedback. It never appears in your documents. Delete the "After the task" section in SKILL.md to turn it off.
- More languages for the writing-tell catalogues
- Section guides for more disciplines (life sciences, social sciences, engineering reports)
- Word (.docx) support in the audit scripts
- Export of the rules as Vale styles for editors and CI
Suggestions are welcome in issues.
If this skill saved you an evening of editing, please star the repository ⭐. It helps other researchers find it.
Feedback makes it better:
- Found a false positive or a missed problem? Open an issue with a short example (synthetic text is fine).
- Have a rule, language or discipline to add? Pull requests are welcome; please paraphrase sources and give full references.
- Run the tests before submitting:
python evals/test_scripts.py
SKILL.md workflow and quick reference (loaded when the skill triggers)
references/ detailed rules, loaded only when needed
academic-sections.md writing from a brief, section by section (W1–W14)
finding-references.md finding and verifying citations (C1–C7)
ai-tells-en.md / ai-tells-zh.md writing-tell catalogues (T1–T22, Z1–Z19)
reader-and-structure.md reader, structure, paragraphs, sentences (R1–R19)
definitions-and-notation.md, equations-as-prose.md, explanation-and-derivation.md,
figures-and-captions.md, scope-and-robustness.md, theses-and-reviews.md,
latex-and-tools.md, integrity-and-ai-use.md, sources.md
scripts/ prose_audit.py, latex_audit.py, check_invariants.py,
check_references.py (+ writing_lib.py)
assets/ drafting brief, audit report, author questions, revision log,
reviewer response, AI-use disclosure, project terms
evals/ evaluation prompts, synthetic fixtures, script tests
If you use this skill in your work, GitHub's "Cite this repository" button gives a ready citation from CITATION.cff.
Scripts are released under the MIT License. The text (SKILL.md, references/, assets/, README files) is released under CC BY 4.0. Policy summaries were checked in September 2026 and may change; follow your institution's and publisher's current rules on AI assistance.