Guide · Agent skill
How to use the Paper Illustration agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The paper-illustration skill is a set of instructions that lets an AI coding agent create publication-style diagrams and method illustrations for academic papers. It is aimed at researchers, students and developers who need a figure drafted quickly and are willing to check it themselves. After reading this guide you will know what the skill does, how to install it, how to trigger it, and what it needs before you start.
Paper Illustrationwanshuiyin/Auto-claude-code-research-in-sleep · MIT Download the skill Quick start
- 1Get a Gemini API key. Obtain a Gemini API key and confirm your account can access gemini-3-pro-image-preview and gemini-3-pro-preview.
- 2Set the environment variable. Export your key as GEMINI_API_KEY in the shell or environment where the agent runs.
- 3Download the skill ZIP. Download the paper-illustration ZIP from this page.
- 4Install the skill. Unzip it into ~/.claude/skills/ for personal use, into the project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 5Make a request. Ask in plain language for a diagram or method illustration, naming the components and data flow.
- 6Review the output. Check the generated figure in figures/ai_generated/ against your paper text, label by label and arrow by arrow.
What is an agent skill and what does paper-illustration make the agent do?
An agent skill is a folder containing a SKILL.md file that tells an AI agent how to carry out a specific task. When the skill is installed and your request matches its description, the agent follows the workflow written in that file.
The paper-illustration skill generates publication-quality illustrations for academic papers, such as architecture diagrams and method illustrations. Claude plans the layout, Gemini image models render the figure, and Claude then reviews the result and scores it from 1 to 10. If the score is below 9, the agent writes specific feedback and loops back to refine the figure, for up to 5 rounds.
- Planner step: Claude parses your request and creates the initial prompt.
- Layout and style steps: Gemini refines component positioning, spacing and style conventions.
- Render step: a Gemini image model produces the figure.
- Review step: Claude checks every arrow direction and block content and gives a strict score.
Install the paper-illustration skill
Download the skill ZIP from this page and unzip it. You can install it for yourself across all projects or for a single project.
For a personal install, unzip it into ~/.claude/skills/. For a project-only install, unzip it into the project's .claude/skills/ folder. Alternatively, in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.
- Personal: ~/.claude/skills/
- Single project: .claude/skills/ inside your project folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Set up the requirements before first use
The skill will not run without a Gemini API key. Store it in the GEMINI_API_KEY environment variable. The workflow also calls the Codex MCP server (mcp__codex__codex) for its tool calls, so that server must be available to your agent.
The agent environment needs Bash and git. The workflow uses gemini-3-pro-image-preview for rendering and gemini-3-pro-preview for layout and style checks, so your account must have access to both models. Python 3 and the extract_paper_style.py helper are needed only if you use the optional style-reference flag.
- GEMINI_API_KEY environment variable set to your Gemini API key
- Access to gemini-3-pro-image-preview and gemini-3-pro-preview
- Codex MCP server (mcp__codex__codex) available to the agent
- Bash and git in the agent environment
- Python 3 plus extract_paper_style.py, only for --style-ref
export GEMINI_API_KEY=your_key_hereHow do you trigger the skill with a natural request?
You do not need a special command. The skill's description lists phrases that activate it, so you can describe the figure in plain language. The description includes Chinese triggers such as 生成图表 and 画架构图 and English triggers such as paper illustration and generate diagram. You can also ask for visual figures for a paper in general terms.
Be specific about the method or architecture you want drawn. The more concrete the description, the more useful the first draft will be. You can also point the agent at a file that describes your method.
- "Generate a diagram of the encoder-decoder architecture from method.md"
- "Draw an architecture figure for my method section showing the three training stages"
- "paper illustration: a pipeline with data preprocessing, a transformer backbone and a classification head"
- "Make a method illustration for the figures I need in the introduction"
Use the optional style-reference flag
You can add — style-ref: <source> to steer structural conventions, such as caption length, panel-count distribution or figure-to-table ratio, toward a reference paper. It is off by default. The source can be a local TeX directory or file, a local PDF, an arXiv id, or an http(s) URL. Overleaf URLs and IDs are rejected; clone the project first and pass the local path.
The flag only affects structure and density. The skill states that the visual design comes from your prompt, not from the reference paper, and the reference is not passed to the review step.
- Default is off; without the flag, nothing changes.
- Accepted sources: local TeX dir or file, local PDF, arXiv id, http(s) URL.
- Overleaf URLs or IDs are not accepted directly.
Safety notes: scripts and network use
This skill runs scripts and uses the network. Prompts and generated content are sent to external models, specifically Google's Gemini image service and Gemini reasoning models, and to the Codex MCP server. Do not use it with unpublished method descriptions unless you accept that data leaves your machine.
Because the skill allows Bash and other tools, review the commands the agent proposes before approving them, especially when the skill runs its helper script.
- Prompts and generated images go to external model services.
- Do not send confidential or unpublished methods if your policy forbids it.
- The skill runs shell scripts and a Python helper for the optional style flag.
- Output is saved under figures/ai_generated/ by default.
Tips for better figures and realistic expectations
Treat each output as a draft. The skill's own review is the only automatic check, and generated diagrams can contain wrong labels, arrows or content. A human must verify every figure against the method before it goes into a paper.
Give the agent the exact components, their names and the direction of data flow. Ask for fewer, clearly named blocks rather than dense diagrams, since the loop works from specific feedback and simpler layouts converge more reliably.
- Verify every label, arrow and block against your paper text.
- List components and data-flow direction explicitly in your request.
- Use a method file for long descriptions instead of pasting them inline.
- Keep scientifically critical figures under your own manual control.
What people use it for
- Drafting an architecture diagram for the method section of a research paper.
- Creating a method illustration showing training stages for a thesis chapter.
- Producing a first-pass pipeline figure for a course report.
- Adding a figure step to an automated paper-writing pipeline built by a developer.
Frequently asked questions
How do I install the paper-illustration skill?
Download the skill ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps you can instead upload it under Settings → Capabilities → Skills.
What do I need to use paper-illustration?
You need a Gemini API key in the GEMINI_API_KEY environment variable, access to the gemini-3-pro-image-preview and gemini-3-pro-preview models, the Codex MCP server, and Bash and git in the agent environment. Python 3 is needed only for the optional style-reference flag.
Is paper-illustration free to use?
The skill is published under the MIT licence. Gemini API access and any usage costs depend on your own Google account and are not stated in the source, so check Google's current terms.
Can the skill make scientifically accurate diagrams?
Not reliably. Generated diagrams can contain wrong labels, arrows or content, and the skill's review step is not a substitute for checking. A human must verify every figure before publication.
Is my unpublished paper safe to use with this skill?
Prompts and generated content are sent to external models, including Google's Gemini image service. If you cannot send unpublished method descriptions to an external service, do not use this skill.
Why does the agent keep looping on my figure?
The skill refines the figure until Claude's strict score reaches 9 or 5 rounds have run. Simpler layouts with explicitly named components and clear data-flow direction usually reach a higher score sooner.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use paper-illustration if you need a fast first draft of an architecture or method diagram and you already have a Gemini API key and are comfortable sending your method descriptions to external services. Pick a different tool, or draw the figure by hand, if the figure must be scientifically exact or your method text cannot leave your machine.
Download the skill