See what people are saying
README
scientific-paper-craft
A skill for Claude Code that drafts and revises research and software-tool papers. Each technique comes from a published source, listed under References. Run anti-ai-writing-tropes afterward to catch generated-prose habits.
Disclaimer: this guide itself is generated by Claude. See footnotes also
Big ideas
The numbers and tools in the examples are placeholders.
Focus on one contribution and list it as claims
Mensh & Kording say to focus the paper on one contribution and communicate it in the title, because "papers that simultaneously focus on multiple contributions tend to be less convincing about each." Peyton Jones suggests writing the key idea in one sentence before drafting and stating it plainly in the Introduction. Then list the contributions as claims, and point each claim to the section that supports it:
The main idea of this paper is to index alignments by region. We make three contributions: a file format (Section 3), a query algorithm (Section 4) and a benchmark against a full scan (Section 5).
Medvedev adds that every claim in the Introduction has to be supported by the rest of the paper.
Give every paragraph context, content and conclusion
A paragraph that opens on a result with no context reads as a list of facts (Mensh & Kording). Open with the problem or what is known, give what you did or found, and close with what it means. The arc nests: the abstract holds all three parts, the Introduction narrows from the field to the gap, and each Results paragraph opens with the question it answers.
| Before | After |
|---|---|
| We tested 20 regions, and queries took 12 ms. Browsers need region queries that return before the user scrolls on. The index is fast enough for interactive browsing. | Browsers need region queries that return before the user scrolls on. We tested 20 regions, and queries took 12 ms, which is fast enough for interactive browsing. |
Put the new fact at the end of the sentence
Gopen & Swan: "Put in the topic position the old information that links backward; put in the stress position the new information you want the reader to emphasize." Open a sentence on something the reader has just read, and end it on the new fact.
| Before | After |
|---|---|
| We built the index with compressed offsets. Memory use fell by 40% because of them. | We built the index with compressed offsets. The offsets cut memory use by 40%. |
Replace a hype word with its evidence
Positive words in PubMed abstracts rose 880% between 1974 and 2014 (Vinkers et al.), and the J. Org. Chem. guidelines tell authors not to use novel, unique or unprecedented. Delete the adjective. If the sentence makes the same claim without it, the adjective was rhetoric, and a number or a figure lets the reader reach the judgment.
| Before | After |
|---|---|
| The index answers region queries efficiently. | The index answers a region query in 12 ms, against 3 s for a full scan. |
Make each figure readable from its caption
AJE's guide says a caption lets the reader interpret the figure without the main text. Open with a title that says what the figure shows, add only the methods needed to read it, state the result, then define the features. Label axes and encodings in the figure, so no reader opens Methods to decode them.
| Before | After |
|---|---|
| Figure 3: Benchmark results. | Figure 3: Query time against region size. Each point is the median of 20 runs; blue is the index and grey a full scan. Query time grows with region size for the scan and stays flat for the index. |
Back every tool claim with an evaluation
Medvedev asks for a strong theoretical contribution or an experimental evaluation, and a comparison against other work: "the authors sometimes find it obvious that their method should work much better than anything else out there. They may be right, but it is important to demonstrate this." Romano & Moore add that evaluations should use well-characterized data, and that the paper should cite the software release it describes with its own DOI.
A clause that explains why you rejected an alternative is a justification, not a method. Move it to the Discussion with evidence, or cut it.
Order the Discussion: findings, prior work, limitations, speculation
Mensh & Kording have the Discussion say how the gap was filled, state the limitations, and describe the relevance to the field. Order it as findings, prior work, limitations, then speculation, so that the speculation reads as informed by the limitations. The Discussion introduces no new data or citations.
Attribute each visualization claim to one level
Munzner's nested model puts a contribution at one of four levels: the domain situation, the data and task abstraction, the encoding and interaction idiom, or the algorithm. A rendering benchmark is a level-4 result, and it does not justify a level-3 design choice. A mistake at a higher level carries down to the levels below it.
Cut words that carry no information
Strunk & White: "Vigorous writing is concise." The same rule goes on to say that this "requires not that the writer make all his sentences short ... but that every word tell." Cut filler, and keep the connectives that join the ideas. Chopping a sentence into fragments makes it shorter but harder to read.
| Before | After | Too far |
|---|---|---|
| It should be noted that the index was found to be smaller than the scan output, which means that it is able to fit in memory. | The index was smaller than the scan output, so it fits in memory. | Index smaller than scan output. Fits in memory. |
Revise in a fixed order
Check structure first, then sentence flow, then a hype sweep, then captions, then evidence, then the Discussion, then ask someone outside the project where they stopped understanding. Fixing sentences before structure polishes paragraphs the paper may cut.
Install
As a plugin:
/plugin marketplace add cmdcolin/scientific-paper-craft
/plugin install scientific-paper-craft@scientific-paper-craft
Or copy the skill into your personal skills directory:
git clone https://github.com/cmdcolin/scientific-paper-craft
cp -r scientific-paper-craft/skills/scientific-paper-craft ~/.claude/skills/
Claude loads the skill when its description matches the task, or when you ask for it by name, e.g. "revise this manuscript with the scientific-paper-craft skill".
References
- Gopen & Swan, "The Science of Scientific Writing," American Scientist 78(6):550-558, 1990: topic and stress position.
- Mensh & Kording, "Ten Simple Rules for Structuring Papers," PLOS Comput Biol 13(9):e1005619, 2017: the central contribution and the context-content-conclusion arc.
- Romano & Moore, "Ten Simple Rules for Writing a Paper About Scientific Software," PLOS Comput Biol 16(11):e1008390, 2020: evaluation data and release DOIs.
- Medvedev, "Ten Simple Rules for Writing Algorithmic Bioinformatics Conference Papers," PLOS Comput Biol 16(4):e1007742, 2020: stating contributions, comparing against other work and evaluating.
- Annesley, "The Discussion Section: Your Closing Argument," Clin Chem 56(11):1671, 2010: limitations in the Discussion.
- Vinkers, Tijdink & Otte, "Use of positive and negative words in scientific PubMed abstracts between 1974 and 2014," BMJ 351:h6467, 2015: growth in positive words.
- J. Org. Chem. author guidelines, American Chemical Society: the list of words to avoid.
- Munzner, "A Nested Model for Visualization Design and Validation," IEEE TVCG 15(6):921-928, 2009: the four levels.
- AJE, "Writing an Effective Figure Legend,": caption structure.
- Peyton Jones, "How to write a great research paper," Microsoft Research: the key idea, the contribution list and related work.
- Strunk & White, The Elements of Style: active voice and concision.
Footnote
I have always been somewhat of a poor writer since grade school. I struggle really hard. But, I also believe that writing by hand is a good exercise. Don't turn your entire essay over to claude. Continue to hand write. Print it out on paper. Use text-to-speech to read it. This guide will not fix everything, you need to still go to battle with your paper!
Why the heck is AI so bad at helping me write papers anyways?
I can't prove it but my pet hypothesis is that there are not entire git repos for rough drafts of papers like there are entire git repo histories. This makes Claude significantly less capable at 'patching up' papers...it just doesn't have that 'commit history' ability to make targetted fixes in the right direction.
Similar repos
See what people are saying
README
scientific-paper-craft
A skill for Claude Code that drafts and revises research and software-tool papers. Each technique comes from a published source, listed under References. Run anti-ai-writing-tropes afterward to catch generated-prose habits.
Disclaimer: this guide itself is generated by Claude. See footnotes also
Big ideas
The numbers and tools in the examples are placeholders.
Focus on one contribution and list it as claims
Mensh & Kording say to focus the paper on one contribution and communicate it in the title, because "papers that simultaneously focus on multiple contributions tend to be less convincing about each." Peyton Jones suggests writing the key idea in one sentence before drafting and stating it plainly in the Introduction. Then list the contributions as claims, and point each claim to the section that supports it:
The main idea of this paper is to index alignments by region. We make three contributions: a file format (Section 3), a query algorithm (Section 4) and a benchmark against a full scan (Section 5).
Medvedev adds that every claim in the Introduction has to be supported by the rest of the paper.
Give every paragraph context, content and conclusion
A paragraph that opens on a result with no context reads as a list of facts (Mensh & Kording). Open with the problem or what is known, give what you did or found, and close with what it means. The arc nests: the abstract holds all three parts, the Introduction narrows from the field to the gap, and each Results paragraph opens with the question it answers.
| Before | After |
|---|---|
| We tested 20 regions, and queries took 12 ms. Browsers need region queries that return before the user scrolls on. The index is fast enough for interactive browsing. | Browsers need region queries that return before the user scrolls on. We tested 20 regions, and queries took 12 ms, which is fast enough for interactive browsing. |
Put the new fact at the end of the sentence
Gopen & Swan: "Put in the topic position the old information that links backward; put in the stress position the new information you want the reader to emphasize." Open a sentence on something the reader has just read, and end it on the new fact.
| Before | After |
|---|---|
| We built the index with compressed offsets. Memory use fell by 40% because of them. | We built the index with compressed offsets. The offsets cut memory use by 40%. |
Replace a hype word with its evidence
Positive words in PubMed abstracts rose 880% between 1974 and 2014 (Vinkers et al.), and the J. Org. Chem. guidelines tell authors not to use novel, unique or unprecedented. Delete the adjective. If the sentence makes the same claim without it, the adjective was rhetoric, and a number or a figure lets the reader reach the judgment.
| Before | After |
|---|---|
| The index answers region queries efficiently. | The index answers a region query in 12 ms, against 3 s for a full scan. |
Make each figure readable from its caption
AJE's guide says a caption lets the reader interpret the figure without the main text. Open with a title that says what the figure shows, add only the methods needed to read it, state the result, then define the features. Label axes and encodings in the figure, so no reader opens Methods to decode them.
| Before | After |
|---|---|
| Figure 3: Benchmark results. | Figure 3: Query time against region size. Each point is the median of 20 runs; blue is the index and grey a full scan. Query time grows with region size for the scan and stays flat for the index. |
Back every tool claim with an evaluation
Medvedev asks for a strong theoretical contribution or an experimental evaluation, and a comparison against other work: "the authors sometimes find it obvious that their method should work much better than anything else out there. They may be right, but it is important to demonstrate this." Romano & Moore add that evaluations should use well-characterized data, and that the paper should cite the software release it describes with its own DOI.
A clause that explains why you rejected an alternative is a justification, not a method. Move it to the Discussion with evidence, or cut it.
Order the Discussion: findings, prior work, limitations, speculation
Mensh & Kording have the Discussion say how the gap was filled, state the limitations, and describe the relevance to the field. Order it as findings, prior work, limitations, then speculation, so that the speculation reads as informed by the limitations. The Discussion introduces no new data or citations.
Attribute each visualization claim to one level
Munzner's nested model puts a contribution at one of four levels: the domain situation, the data and task abstraction, the encoding and interaction idiom, or the algorithm. A rendering benchmark is a level-4 result, and it does not justify a level-3 design choice. A mistake at a higher level carries down to the levels below it.
Cut words that carry no information
Strunk & White: "Vigorous writing is concise." The same rule goes on to say that this "requires not that the writer make all his sentences short ... but that every word tell." Cut filler, and keep the connectives that join the ideas. Chopping a sentence into fragments makes it shorter but harder to read.
| Before | After | Too far |
|---|---|---|
| It should be noted that the index was found to be smaller than the scan output, which means that it is able to fit in memory. | The index was smaller than the scan output, so it fits in memory. | Index smaller than scan output. Fits in memory. |
Revise in a fixed order
Check structure first, then sentence flow, then a hype sweep, then captions, then evidence, then the Discussion, then ask someone outside the project where they stopped understanding. Fixing sentences before structure polishes paragraphs the paper may cut.
Install
As a plugin:
/plugin marketplace add cmdcolin/scientific-paper-craft
/plugin install scientific-paper-craft@scientific-paper-craft
Or copy the skill into your personal skills directory:
git clone https://github.com/cmdcolin/scientific-paper-craft
cp -r scientific-paper-craft/skills/scientific-paper-craft ~/.claude/skills/
Claude loads the skill when its description matches the task, or when you ask for it by name, e.g. "revise this manuscript with the scientific-paper-craft skill".
References
- Gopen & Swan, "The Science of Scientific Writing," American Scientist 78(6):550-558, 1990: topic and stress position.
- Mensh & Kording, "Ten Simple Rules for Structuring Papers," PLOS Comput Biol 13(9):e1005619, 2017: the central contribution and the context-content-conclusion arc.
- Romano & Moore, "Ten Simple Rules for Writing a Paper About Scientific Software," PLOS Comput Biol 16(11):e1008390, 2020: evaluation data and release DOIs.
- Medvedev, "Ten Simple Rules for Writing Algorithmic Bioinformatics Conference Papers," PLOS Comput Biol 16(4):e1007742, 2020: stating contributions, comparing against other work and evaluating.
- Annesley, "The Discussion Section: Your Closing Argument," Clin Chem 56(11):1671, 2010: limitations in the Discussion.
- Vinkers, Tijdink & Otte, "Use of positive and negative words in scientific PubMed abstracts between 1974 and 2014," BMJ 351:h6467, 2015: growth in positive words.
- J. Org. Chem. author guidelines, American Chemical Society: the list of words to avoid.
- Munzner, "A Nested Model for Visualization Design and Validation," IEEE TVCG 15(6):921-928, 2009: the four levels.
- AJE, "Writing an Effective Figure Legend,": caption structure.
- Peyton Jones, "How to write a great research paper," Microsoft Research: the key idea, the contribution list and related work.
- Strunk & White, The Elements of Style: active voice and concision.
Footnote
I have always been somewhat of a poor writer since grade school. I struggle really hard. But, I also believe that writing by hand is a good exercise. Don't turn your entire essay over to claude. Continue to hand write. Print it out on paper. Use text-to-speech to read it. This guide will not fix everything, you need to still go to battle with your paper!
Why the heck is AI so bad at helping me write papers anyways?
I can't prove it but my pet hypothesis is that there are not entire git repos for rough drafts of papers like there are entire git repo histories. This makes Claude significantly less capable at 'patching up' papers...it just doesn't have that 'commit history' ability to make targetted fixes in the right direction.