idea-to-essay

An Agent Skill that takes a research idea and returns a literature-grounded, tutorial-like standalone HTML essay.

You hand your agent an idea. It digests the idea into a thesis you could disagree with, sweeps the literature and downloads verified full texts, produces numbers and figures from code it writes, and then writes one self-contained HTML page that teaches the idea in conversation with the work around it.

It was distilled from seven finished projects built this way, so its defaults are measured rather than guessed.

What you get

A project folder, with one HTML file at its centre:

your-project/
  idea.md                the founding prompt, verbatim, never edited
  design.md              thesis, chain of argument, what would refute it
  outline.md             the blueprint: parts, sections, claims, figures
  literature/            verified full-text PDFs + an annotated README + NEEDED.md
  analysis/              code that produces every number in the essay
  figures/               generated SVG and PDF
  your-project.html      the deliverable

The HTML is one file with no external requests. Sticky table of contents, numbered sections grouped into parts, inline SVG figures, callout boxes, optional canvas demos with sliders, superscript citations that link to a reference list that links back into literature/, and a light and dark theme.

skills/research-essay/assets/template.html is a working example of the format. Open it in a browser to see the target.

Install

The skill is a folder in the standard Agent Skills layout, so most agents read it directly.

Any skills-compatible agent. Clone, then run the installer. It symlinks the skill into the skills directories your tools read, so git pull updates it everywhere at once.

git clone https://github.com/chemaoxfz/idea-to-essay.git
cd idea-to-essay
./install.sh          # ~/.agents/skills and ~/.claude/skills
./install.sh --all    # also ~/.cursor, ~/.gemini, ~/.codex, ~/.copilot

~/.agents/skills/ is the vendor-neutral location, read by Codex and ChatGPT, Cursor, Gemini CLI, and VS Code with Copilot. Claude Code reads ~/.claude/skills/ only, which is why the default does both. ./install.sh --project . installs into one repository instead, at .agents/skills/, which is the way to give a whole team the same skill by committing it.

Restart your agent afterwards. If your tool is not covered, its skills path is listed at agentskills.io/clients, and a symlink there does the job.

Claude Code, as a plugin. The repository is also a plugin marketplace, so no clone is needed:

/plugin marketplace add chemaoxfz/idea-to-essay
/plugin install idea-to-essay

Claude apps and web. Zip skills/research-essay/ and upload it in the skills settings.

No skills support at all. Point the agent at skills/research-essay/SKILL.md and tell it to follow that file. Everything here is plain Markdown and Python. Nothing depends on a particular vendor.

Use it

Describe the idea, in as much or as little detail as you have:

Develop this idea and write it up. [your idea] Situate it in the literature, dig into the full texts, and give me a standalone HTML tutorial.

Or invoke it by name, which is /research-essay in Claude Code.

Expect it to take a while and to want the network. The literature pass is the expensive phase and the one that makes the difference. It runs at least twice, because the second pass answers the questions the first pass exposed.

The invariants

These are the part that is not negotiable, and they are why the output differs from a literature review an agent writes from memory.

  1. Full text or it does not get cited. Abstracts, search snippets and recollection are not sources. If a claim is load-bearing, the PDF is in literature/ and it has been read. Every download is verified by matching a phrase from page 1, because a guessed identifier resolves to something, just not the right thing.
  2. Corrections are the product. When a full text overturns something believed from memory, that is the most valuable thing the pass produced. It gets logged, and the writeup gets fixed. A pass that corrected nothing probably did not read anything.
  3. The analogy is never the argument. Wherever the idea leans on a correspondence, the shared mathematical object gets named, not the resemblance. Where the correspondence breaks is stated in the text, unprompted.
  4. Numbers come from code in the folder. Every number traces to a script that runs, to a cited paper, or to a documented figure digitization. None are typed from memory.
  5. The tutorial contract. The reader is learning a field they do not already know. Every concept the argument needs is introduced before it is used, with the actual definition or formula rather than a description of one.
  6. Report what came out. Where the founding intuition was too strong, the essay says so and says by how much. A simulation that disagreed with the idea goes in the essay, not in a drawer.

What is in the box

skills/research-essay/
  SKILL.md                    the seven phases, the invariants, calibration numbers
  references/
    conventions.md            prose rules, figure setup, the palette
    literature.md             the fetch ladder, naming, verification, README and NEEDED conventions
    house-style.md            the HTML: CSS vocabulary, boxes, figures, demos, citations
    narrative.md              the four-movement arc and how the tutorial voice works
    build.md                  the src/ parts pipeline for large essays
    exemplars.md              the shapes this has produced, measured
  assets/template.html        a complete working page in the house style
  scripts/
    resolve.py                paper titles -> DOIs via Crossref, with a match score
    fetch.py                  the open-access ladder, with verification. Rejected files are deleted
    pmcget.py                 solves PubMed Central's proof-of-work challenge
    build.py                  src/part*.html -> one HTML, inlining figures and numbering them
    renumber.py               rewrites citation numbers from the order of the reference list
    check.py                  the quality gate on the finished file

check.py is the piece worth stealing on its own. It fails the build on a dangling anchor, a duplicate id, a citation number out of step with the reference list, a linked PDF that is not on disk, or any external resource that would break the standalone guarantee. It warns on em dashes, uncited references, SVG labels anchored outside their viewBox, and a thin section or figure count.

Make it yours

skills/research-essay/references/conventions.md is the file to fork. It holds the prose rules, the matplotlib setup and the colour palette. Replace it with your own and the rest of the skill still works. The template carries GROUP · INSTITUTION placeholders for the same reason.

Two other things are worth localising. references/exemplars.md invites a gitignored references/exemplars.local.md listing your own finished projects and their paths, which becomes more useful than anything shipped here once you have one. And references/house-style.md is the whole visual identity, so a group that wants its own look edits the CSS once and every essay follows.

Requirements

  • Python 3.9 or later, standard library only.
  • pdftotext from poppler, used to verify downloads. brew install poppler or apt install poppler-utils.
  • Network access for the literature pass.
  • LIT_EMAIL set to your email address, or a configured git config user.email. Crossref, Unpaywall and OpenAlex ask for a contact address in their polite pool.
  • Optional: a LaTeX toolchain (latex, dvipng) so figure text matches the document fonts. Without it the scripts fall back to a Computer Modern lookalike.

License

MIT. See LICENSE.