manuscript-polishing
Skill2 starsChanged 36 days agoMITView on GitHub
Adapts a finished review draft to the locked journal: wording, consistency, overclaim hedging, citation audit, and a docx export. Use when the user says "polish the manuscript", "fit the word limit", "overclaim", "change log", or "export docx". Do not use to add results, add references, choose a journal, or respond to reviewers. For restructuring the argument, removing paper-by-paper listing, or editing a Word file with live Zotero fields, use review-writing first.
- Installs packages
In this repository20 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .cursor/rules/literature-review.mdcCursor rule
- exemplar-review-analysisSkill
- figure-permissionsSkill
- journal-selectionSkill
- literature-screeningSkill
- paper-deep-readingSkill
- reviewer-responseSkill
- review-figures-and-tablesSkill
- review-orchestratorSkill
- review-outline-builderSkill
- review-project-setupSkill
- review-scoping-and-gapsSkill
- review-section-drafterSkill
- review-writingSkill
- search-export-and-dedupSkill
- search-strategy-builderSkill
- submission-packageSkill
- zotero-library-syncSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. About 0 are common, 4 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 35
Stop if the journal is not locked.
- Very specific: line 59
Create <project>/10-polish/change_log.csv with the header in references/change_log_template.md before the first edit.
- Very specific: line 60
If you drop an outline evidence ID, the reason cell must contain the words dropped E014 (real ID).
- Distinctive: line 93
If the user supplied the journal's own reference docx (not a file from an unofficial template site):
- Very specific: line 103
If pandoc is not installed, stop and ask the user to install it from https://pandoc.org/installing.html, or to run the python-docx fallback …
- Very specific: line 105
After export, confirm the docx text has no <!-- and no bare evidence-ID comments.
- Distinctive: line 129
No separate project-level gate.
- Very specific: line 143
Every change-log after cell is free of block phrases.
- Very specific: line 144
Every outline evidence ID is still cited, or its drop is logged as dropped E###.
- Distinctive: line 151
Do not add a finding, a citation, a sample size, or a mechanism that was not in the drafts.
- Very specific: line 152
Do not strengthen a hedge.
- Distinctive: line 153
Do not "fix" a reference by guessing page numbers or a DOI.
- Very specific: line 154
Do not describe the prose as professionally copyedited unless a person did that.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Manuscript polishing
Opening
On first use in a project, say this verbatim:
I am manuscript polishing. I fit the draft to the locked journal's style brief and I do not add claims.
When to use
Every outline section has a checked draft, the journal lock has been passed, and 06-exemplars/style_brief.md says Refreshed after journal lock: yes for that journal. This skill edits language and format. It does not add scientific claims. If the argument itself needs restructuring, or the user supplies a Word file with live Zotero fields, run review-writing first; its docx-citation-safety reference also governs any later edit to such a file.
Inputs (paths) / Preconditions
<project>/11-journal/journal_shortlist.mdwithjournal lockalready inLOG.md. Read the locked journal's word limit, reference style, andDouble-anonymizedline.<project>/06-exemplars/style_brief.mdwithRefreshed after journal lock: yes, a heading pattern, an abstract shape, and a figure budget.<project>/09-draft/S*.mdand<project>/07-outline/outline.md.<project>/evidence/evidence_table.csv<project>/08-figures/figure_ledger.csvshared/writing_rules.md- Phrase list:
references/overclaim_words.md
Stop if the journal is not locked. Stop if any section file still fails check_citations.py.
Procedure (numbered steps)
- Assemble the section prose in outline order:
python3 <suite>/skills/manuscript-polishing/scripts/assemble_manuscript.py \
--outline <project>/07-outline/outline.md \
--drafts <project>/09-draft \
--output <project>/10-polish/manuscript.md- Apply
06-exemplars/style_brief.mdbefore any other edit. Set the##headings to theHeading patternline, in that order, including Limitations and Next questions. If the outline titles do not match that pattern, stop and ask the user to reopen the outline lock. Do not drop either required section. Write the abstract with theAbstract shapelabels in order (backgroundbecomes**Background.**), using only claims already in the drafts. Keep the same evidence IDs. UniqueFig. Nmentions must not exceedFigure budget. If the journal is double-anonymized, do not put author names, affiliations, or funding in this file. Those stay on the title page. Then run:
python3 <suite>/skills/manuscript-polishing/scripts/check_style_fit.py \
--brief <project>/06-exemplars/style_brief.md \
--manuscript <project>/10-polish/manuscript.md \
--journal "<locked journal name>"Do not continue while this command fails. Log heading and abstract edits as structure or format in the change log you create in the next step. Create that log before the edits if you need a row for them; an empty log with only the header is allowed until the first edit.
- Create
<project>/10-polish/change_log.csvwith the header inreferences/change_log_template.mdbefore the first edit. Every later edit gets a row. Allowedchange_typevalues:hedge,language,consistency,citation,format,structure,cut_to_limit. There is no type for a new claim.aftermay be[deleted]only forcut_to_limitorstructure. - If you drop an outline evidence ID, the reason cell must contain the words
dropped E014(real ID). If you keep an ID, it stays in the manuscript as(Smith, 2020; E014)or, after you convert the style, as the formatted citation plus<!-- E014 -->. - Audit citations:
python3 <suite>/skills/review-section-drafter/scripts/check_citations.py \
--manuscript <project>/10-polish/manuscript.md \
--outline <project>/07-outline/outline.md \
--change-log <project>/10-polish/change_log.csv \
--evidence <project>/evidence/evidence_table.csv- Scan overclaims. Block phrases must be removed or hedged to match the evidence row. Review phrases (
significant,novel,robust, and the rest of that list) stay only with a decision row.
python3 <suite>/skills/manuscript-polishing/scripts/polish_checks.py \
<project>/10-polish/manuscript.md \
--change-log <project>/10-polish/change_log.csv \
--decisions <project>/10-polish/overclaim_decisions.tsvoverclaim_decisions.tsv is tab-separated: line, phrase, decision, reason. decision is kept or removed. A kept reason starts with kept: and names the evidence ID. Do not export while any block hit remains.
- Fill
<project>/10-polish/consistency.mdfromreferences/consistency_checklist.md. One row per term. Define an abbreviation at first use in the abstract and again at first use in the main text. Do not introduce an abbreviation you use fewer than three times. - Apply the locked journal's word limit by cutting, and log each cut. Do not delete the only citation for a sentence you keep. Match heading levels and spelling (US or UK) to the author guidelines. Reference style: convert each key from the evidence row's bibliographic fields. If a volume, page, or DOI is blank in the row, write
[VERIFY]and do not invent it. Numbered styles still keep the<!-- E014 -->marker in the markdown. - Export only after
check_style_fit.pyhas printedOK style fit. Pandoc (https://pandoc.org/MANUAL.html):
pandoc "<project>/10-polish/manuscript.md" \
--from=markdown \
--to=docx \
--output="<project>/10-polish/manuscript_polished.docx"If the user supplied the journal's own reference docx (not a file from an unofficial template site):
pandoc "<project>/10-polish/manuscript.md" \
--from=markdown \
--to=docx \
--reference-doc="<project>/10-polish/reference.docx" \
--output="<project>/10-polish/manuscript_polished.docx"If pandoc is not installed, stop and ask the user to install it from https://pandoc.org/installing.html, or to run the python-docx fallback in references/export_docx.md themselves. Do not pip install.
- After export, confirm the docx text has no
<!--and no bare evidence-ID comments. Append:
YYYY-MM-DD | manuscript-polishing | change log accepted | human
only after the user has read the change log.
- Open Terminal on macOS or PowerShell on Windows, then go to the repository folder with the cd command. Run the script to export your spreadsheet (CSV or TSV) records to BibTeX (a plain text format for references) and CSL-JSON (a structured data format for references) by typing:
python3 skills/manuscript-polishing/scripts/export_refs.py <project>/03-screening/included.tsv --library <project>/02-records/library.csvCheck the terminal output. Any citation key (a short text ID for a paper) listed in the authors_incomplete group will either end with "and others" in its BibTeX entry or have no author at all, and both situations need finishing by hand. Next, download the locked journal's CSL (Citation Style Language) file from https://github.com/citation-style-language/styles and use its saved file path for the --csl flag in the pandoc command below. Do not pass the style file path to the --csl flag in export_refs.py because this sets the JSON output path and will overwrite your downloaded .csl file. You can then use Pandoc (a document converter) to format the citations. If you do not have Pandoc installed, you must first install it from https://pandoc.org/installing.html. Build the polished document by typing:
pandoc "<project>/10-polish/manuscript.md" \
--from=markdown \
--to=docx \
--citeproc \
--bibliography="<project>/03-screening/refs.bib" \
--csl="<path_to_downloaded_journal.csl>" \
--output="<project>/10-polish/manuscript_polished.docx"Human gate(s)
No separate project-level gate. The user accepts the change log before the docx is treated as the submission file. This is not the final submit gate.
Outputs (exact paths + formats)
<project>/10-polish/manuscript.md<project>/10-polish/change_log.csv— columnsid,file,location,change_type,before,after,reason<project>/10-polish/overclaim_decisions.tsv<project>/10-polish/consistency.md<project>/10-polish/manuscript_polished.docx
Quality checklist
- Both checkers print
OK, andcheck_style_fit.pyprintsOK style fit. - Headings, abstract labels, and the figure count follow the refreshed style brief.
- Every change-log
aftercell is free of block phrases. - Every outline evidence ID is still cited, or its drop is logged as
dropped E###. - The manuscript cites no ID that is absent from the outline and the evidence table.
- Word count is within the locked journal's limit, or the limit cell was
[VERIFY]and you stopped. - The docx was produced by the pandoc command above, or by the documented python-docx fallback.
Guardrails
- Do not add a finding, a citation, a sample size, or a mechanism that was not in the drafts.
- Do not strengthen a hedge.
indicatesdoes not becomeshowsduring polishing. - Do not "fix" a reference by guessing page numbers or a DOI.
- Do not describe the prose as professionally copyedited unless a person did that. Language edits are logged as
language.
Next step
figure-permissions if any ledger row is still adapted or reused and not granted. Otherwise submission-package.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

