idea-to-essay

An Agent Skill for developing a research idea into a literature-grounded,
tutorial-like standalone HTML essay.

The workflow connects verified full texts, reproducible analysis, and a readable argument.
It also supports historical and comparative essays, an explicitly requested LaTeX variant, and
focused revisions after new evidence or reader feedback.

What you get

A project with one central deliverable and the evidence needed to inspect it:

your-project/
  idea.md                original prompt, preserved
  design.md              thesis, argument, assumptions, project state
  outline.md             section blueprint and revision addenda
  literature/            full texts, annotated INDEX.md, NEEDED.md
  analysis/ or sim/       reproducible calculations and figure generators
  figures/               generated SVG and PDF
  your-project.html      standalone deliverable

Use only the scaffolding the project needs. Large essays can build from HTML parts; small ones can
stay in a single source file.

The HTML has inline CSS, SVG, and JavaScript, a table of contents, citations, and light and dark themes.
Interactive demos are optional. Open the template in a
browser to see the format. Local reference links point into literature/; a separate web conversion
removes private archive links without changing the local original.

What the skill insists on

• Inspect the full text behind important claims and record provenance, checksums, and access gaps.
• Let evidence correct the idea. Separate measurement, assumption, model implication, and speculation.
• Make numbers reproducible and analogies precise.
• Introduce context before using it. Give every section a question, supported takeaway, and consequence.
• Make the visual sequence communicate the argument, with essential conditions visible.
• Check mechanics, reproducibility, browser behavior, and the reader's path separately.

The skill entry point is the authoritative workflow.
Detailed guidance lives in focused references, so follow-up edits do not need to restart every phase.
The original seven projects provide calibration, not quotas for length, papers, or figures.

Install

Clone and run the installer:

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

The default is a symlink, so updating this checkout updates linked installations.
Existing real directories are deliberately left untouched. If you have a copied or locally customized
skill, compare and merge it before replacing anything. Restart the agent to load the revised skill.

For a project-local installation:

./install.sh --project /path/to/project

This links the skill into that project's .agents/skills/ and .claude/skills/.
Add --copy for a self-contained installation that does not depend on this checkout.

Claude Code plugin

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

The repository also carries plugin and marketplace manifests. Plugin installations have their own
cached copies; updating a separate clone does not update that cache.

Other clients

Upload a zip of skills/research-essay/ in clients that accept skill uploads.
For other skill-aware tools, use the documented skills directory listed at
Agent Skills clients.
Without skill support, ask the agent to read skills/research-essay/SKILL.md and follow it.

Use

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

Invoke $research-essay in Codex or /research-essay in Claude Code. For a revision, provide the
existing project and the evidence or feedback to address.

A full new essay normally includes a second literature pass after outlining. A focused revision
targets the changed claims and their dependencies. The skill does not publish files or contact
others merely because an essay might benefit from that action.

Inside the skill

The Python helpers are resolve.py, fetch.py, pmcget.py, renumber.py, build.py, and check.py.
Copy them into project tools/ when used. The checker catches common source-level failures, but its
warnings and limitations still need review; it cannot establish scientific support or narrative clarity.

Customize

Edit references/conventions.md for house preferences and references/house-style.md plus the
template for visual identity. Explicit user and project instructions take precedence over defaults.

Optional references/exemplars.local.md can list private project paths and notes. It is gitignored.
Keep that file and research full-text archives out of public skill updates.

Requirements

• Python 3.9+ for the bundled helpers, standard library only.
• Poppler's pdftotext for PDF verification and pdffonts for checking generated PDF fonts.
• Network access for searching and fetching, and LIT_EMAIL or a configured git config user.email
  for lookup services that request a contact address.
• Optional LaTeX (latex, dvipng) for figure fonts. The conventions guide includes a fallback.
• Additional analysis dependencies, if needed, are documented in the generated project.

License

MIT. See LICENSE.