fig-draw

fig-draw

Produce a grounded academic figure and a stable local artifact. Preserve the user's chosen backend, reference assets, style direction, review preference, and output scope.

If the user asks only to construct, diagnose, or revise a figure prompt, use this skill's matching output mode and stop before rendering. A prompt-only request does not require invented render paths or an extra approval gate.

Compile scientific content into verifiable diagrams. This is the sole design and prompt compilation entry point; do not treat prompt rhetoric as a second round of scientific design.

Choose output by request

User intent	Action and stop point
Construct a drawing prompt / write prompt only	construct: design brief and complete prompt; does not generate images
Inspect or diagnose an existing prompt	diagnose: locate issues, impact, and minimal fixes; does not modify files or generate images without authorization
Revise the prompt based on feedback	revise: changes, retained items, and the complete new prompt; does not automatically generate images
Create a diagram / modify an image	After construct or revise, this skill continues to render and visually inspect
Consult only on color scheme or style	Palette Decision; does not require a complete topology and does not generate images
Turn AI images into editable PPT	Hand off to fig-pptx. This skill does not split layers or assemble PPTX

When only asking about a plan, do not start drawing. When drawing directly, do not impose prompt confirmation; follow the user's review preference. Drawing directly does not replace style selection.

Read as needed

Load only what the current stage needs:

• Construct, diagnose, or revise a decision → references/prompt-design-logic.md
• Compile renderer prompt → references/json-to-prompt.md
• Ready-to-fill construct/revise templates → references/prompt-templates.md
• Density, layout, text, or style details → references/image-prompt-guide.md
• Cases and transfer checks → references/prompt-design-cases.md
• Structural contract for actual rendering → json-schema.md and figure-spec.schema.json
• Visual anchors → references/architecture-icons.md, using only elements consistent with the evidence
• Style menu before the first image generation → references/style-catalog.md and references/previews/
• Color and optional style library → references/palettes.md、references/styles/
• Codex native image execution → references/codex-image-workflow.md
• Image acceptance → references/render-audit.md (required before accepting an image)

Mark content beyond the evidence as inferred or to be confirmed; use placeholders instead of fabricated modules, losses, dimensions, or results; when no usable source exists, stop and list the minimum materials that need to be supplemented.

Route inputs by inspected content

A URL is not automatically a repository. Inspect it first.

Input	Route	Execution Behavior
Direct User Architecture (Passthrough)	This skill's design flow	Skip fig-analyze. User gave explicit nodes/flow; compile FigureSpec v1 and render directly.
Draft Notes / Outline / Partial Draft	../fig-analyze/SKILL.md	Draft-to-Figure Fast-Track. For rough notes, outlines, or sections without full results: focus on Figure 1 framework.
Complete Manuscript (Markdown / LaTeX / PDF / URL)	../fig-analyze/SKILL.md	Full Planning. For complete papers with experiments/results: multi-figure strategy, claim verification, and constraints.
Repository path or repository URL	../fig-analyze/SKILL.md	Extract semantic architecture graph; omit engineering plumbing (data loaders, trainers).
Paper plus repository	../fig-analyze/SKILL.md	Paper/user defines narrative & topology; repository supplies parameter & dimension verification.
External style reference	../fig-analyze/SKILL.md	Extract transferable style from external references.
Existing render to edit	This skill's revise mode	Preserve its scientific content, topology and visible text, then apply only the requested delta.

For an article URL, use an available web/browser/document reader to obtain the paper text, captions, and linked figures. For a PDF, use a PDF-capable reader for paper content. If fig-analyze is not installed, perform the minimum equivalent analysis and mark the degraded path.

Keep versioned internal artifacts

Store these as JSON-compatible objects. Do not make the user read them unless requested.

FigurePlan v1

schema: academic-figure/FigurePlan@1
source_revision, venue
sources[]: {kind, uri_or_absolute_path, revision_or_page, evidence}
figures[]: {
  figure_id, figure_type, priority, communication_goal, claim_scope[], hero_element,
  required_nodes[], required_connections[], authority_boundaries[], secondary_context[],
  forbidden_claims[], forbidden_connections[], aspect_ratio, final_width_mm,
  style_profile_hint, reference_assets[],
  open_questions[], confidence, review_status: pending|confirmed|waived
}

Components and connections are semantic and evidence-backed. A code directory count is not a figure hierarchy or palette decision.

FigureSpec v1

schema: academic-figure/FigureSpec@1
figure_id, plan_revision, sources[], prompt (internal), aspect_ratio, final_width_mm
topology: {components[], connections[], groups[], authority_boundaries[]}
visible_text[], caption_notes[], layout
style_profile: classic-technical|pastel-airy-ui|illustrated-modular|reference-led
style_preset, style_source, style_grammar, semantic_color_roles
style_selection: pending|confirmed|waived (render-ready rejects pending or missing)
reference_images[]: checked absolute local paths or recent-conversation descriptors
conversation-reference transient status stays in the execution packet
must_not_claim[], forbidden_connections[], negative_constraints[]
prompt_review: requested|confirmed|waived
prompt_reviewed_sha256: required only when prompt_review is confirmed
workspace_root: absolute declaration that must match the runtime-trusted root
output_path: absolute path inside that root

The internal prompt is renderer input, not a required user-facing deliverable. When prompt_review is waived, persist it only with the working artifacts and never paste it into the chat response.

RenderAudit v2

schema: academic-figure/RenderAudit@2
figure_id, render_revision, image_path, image_sha256, spec_sha256
spec_validation: {status}
image_inspection: {status, evidence}
nodes[]: {id, status, evidence}
edges[]: {id, from, to, kind, direction, line, label, status, evidence}
checks: {semantic_topology, visible_text, background, layout,
         style_fidelity, accessibility} (each: {status, evidence})
pass, defects[], targeted_edit, semantic_edits_used, semantic_edits_remaining

Statuses are pass|fail|unverified. See the shared audit protocol for exact revision binding, complete graph coverage, and aggregate-pass requirements. Keep historical v1 audits as history; new renders require v2 inspection records.

Build the plan

Create the shortest FigurePlan that closes scientific ambiguity. Shortest means no speculative modules. A station on an executed path stays in the figure even if its importance is secondary; secondary_context is only for context that does not change the path. When a reference exists, its transferable style grammar takes priority over venue stereotypes and preset defaults. Match composition, mark language, illustration level, region treatment, typography, spacing, arrow grammar, emphasis, and semantic color roles. Do not copy the reference's claims, labels, branding, or topology unless it is the user's redraw or edit baseline.

Use plan review only when unresolved choices would materially change the result, the user asks to review it, or required content is still a placeholder. Otherwise record review_status: waived and continue. An unrelated reply is never confirmation.

Design process

1. Write out the reader's question and the core answer of the diagram, distinguishing main content, supporting content, and caption-only.
2. Extract stable component IDs, typed connections, permission boundaries, prohibited relationships, and evidence from upstream analysis or user input. Do not borrow algorithms from reference images, and do not fill missing evidence as certain facts.
3. Confirm style after the scientific skeleton is clear and before the layout is finalized. Follow the style confirmation specification in the next section; do not finalize the layout or generate images before confirmation. Style participates in subsequent composition, not as a decorative sentence appended after the prompt is written; see references/prompt-design-logic.md。
4. Jointly design the reading order, main areas, semantic grouping, connection channels, and necessary visual anchors based on scientific meaning and the selected style. Nest only when a real hierarchy requires it; proportion is a composition aid. Icons, small diagrams, formula cards, robots, or bubbles are all optional. Pure label nodes are used only when the selected style allows. Do not compress the main-area proportions, nesting levels, or marking language of any style into a uniform row of equal-sized icons.
5. Lock the visible text, semantic colors, and non-color encodings, and check text capacity and readability under the selected style; close all edges before compilation. For revisions, write Delta and Invariants first; color changes do not alter the scientific topology.
6. Compile content, layout, and style uniformly into complete, compact natural language, rather than layering a style patch onto an old prompt. prompt-only is delivered here; rendering tasks then complete, validate FigureSpec, and hand off for execution.

When the user directly describes the architecture, skip unnecessary repository scanning. Record it as sources in user_instruction, with the original request as evidence; component IDs use stable snake_case. Keep execution, advisory, feedback, storage, and exception connections separate; do not infer connections from position.

Confirm style before the first render

Do this after the scientific skeleton is clear and before layout or the renderer prompt. Follow references/prompt-design-logic.md for reference handling and bounded style-only revisions. This gate applies only to the first render. Revisions, color-only edits, a style the user already named, and a reference image the user asked to follow do not open the menu again.

• No named style and no style reference: read references/style-catalog.md, show all six previews by displaying the image files themselves, add one line of traits each, then stop. Do not call the image tool in that turn.
• "直接画图", "使用 Codex 生图", or "不用返回 prompt" sets prompt_review: waived only. It does not choose a style.
• The user named a style or profile: record that style_preset and its catalog style_profile, set style_selection: confirmed, and continue without asking again.
• The user supplied a reference to follow: use reference-led, set style_selection: confirmed, and do not show the six-style menu.
• Set style_selection: waived and choose a style only when the user explicitly says to pick for them or to use the default. Otherwise do not pick.
• An unrelated reply is not a style choice. Leave style_selection: pending until the user picks one.

Record the canonical FigureSpec profile id:

• classic-technical: restrained strokes, exact topology, minimal illustration; clear sans-serif text.
• pastel-airy-ui: white cards, light separation, color on tokens/curves; light borders, no stacked cards.
• illustrated-modular: low-saturation filled regions, darker paired outlines/titles, editorial or hand-drawn line art, asymmetric hero layout. Region interiors are open labeled illustrations; a subcard exists only for a real one-level grouping, not as a frame around every station. Sourced mechanism lines stay in the region prose. A station on the path may be smaller than the hero and still remains. Optional character illustrations; do not default to equal density in every region, and do not reduce it to a strip of equal-sized icons.
• reference-led: an override mode with at least one local or recent-conversation reference image; preserve the observed grammar whether it is technical, airy, illustrated, or a coherent combination; extract layout, line, fill, typography, illustration, and whitespace grammar from the viewed reference image; it is not equivalent to hand-drawn style.

Use style_preset for named library variants. Never interpret reference-led as an alias for illustrated-modular.

Hues are bound to responsibilities, not colored by the number of code directories. Agentic diagrams may reference reasoning blue, context green, execution peach, advisory purple, memory cyan, output gold, stop coral red; these are domain presets, not universal facts. Support rich palettes, grayscale printing, or dark backgrounds required by the data. Follow the surface and shadow rules determined by the reference/user, and avoid requiring 3D in one place while globally prohibiting 3D in another.

Keep sufficient contrast between body text and background; double-encode key differences with color plus line style, labels, or shapes. Palette Decision outputs the profile, rationale for the choice, semantic bindings, background/body/outline, one alternative, and copyable tokens.

Text and compilation

Region titles usually do not exceed 5 words, and labels/edge labels usually do not exceed 3 words; these are abbreviation suggestions and must not damage scientific meaning, nor be used to delete mechanism lines or subcards required by the chosen style. Include only necessary and sourced formulas. What is removed first is caption-only annotation, not mechanism labels on the path. Then consider subfigures or deterministic layout; do not increase density by endlessly shrinking the font.

Use compact prose for model input; do not surround instructions with Markdown headings, bold, lists, or tables; preserve approved mathematical notation and exact labels. By default, put the figure caption in an external caption; show a short figure title only when the user or design explicitly requires it. The order is purpose, composition and components, closed edge list, exact visible text, style and palette, defect constraints, and proportions; see the compiler for details.

Create the spec

Select one planned figure at a time. This skill compiles FigureSpec v1 and normalized structured rendering briefs across all supported profiles (classic-technical, pastel-airy-ui, illustrated-modular, or reference-led). If a supplied reference defines a custom grammar, construct FigureSpec v1 directly from ReferenceAnalysis v1. Never force a reference into white-fill colored-border boxes.

Prompt review is conditional and has executable state semantics:

• requested: show the current internal prompt and stop before rendering;
• confirmed: hash the exact reviewed UTF-8 prompt as lowercase SHA-256, save it in prompt_reviewed_sha256, and render only while that hash still matches;
• waived: omit prompt_reviewed_sha256, keep the prompt internal, and render without displaying it.

If a confirmed prompt changes, return to requested and review the new prompt. Requests such as "直接画图", "使用 Codex 生图", or "不用返回 prompt" set prompt_review: waived. They do not waive style confirmation. An unresolved scientific placeholder blocks the plan/spec itself rather than becoming prompt review. A waived prompt is never included in user-facing output. Do not render while style_selection is missing or pending.

When to open a sub-agent

Skills are procedures, not persistent agents. When the runtime can run sub-agents, open a temporary Figure Worker for every split listed below. Do not keep that work on the main agent just to stay in one thread. If the runtime has no sub-agents, the main agent does the same steps itself. Missing sub-agents never blocks delivery.

Open one worker per item:

• Each independent evidence source before integration: a repository, a manuscript or draft, and a reference figure are separate evidence_analysis jobs.
• Each figure whose nodes and edges do not depend on another figure's finished layout: its own spec_only or render job.
• A finished figure that only needs a read-only check while another figure is still being produced. That worker writes no files.

Keep these on the main agent:

• The style menu, and any turn waiting for the user to choose a style.
• One figure's own sequence of design, spec, render, audit, and edit.
• A targeted edit of one existing image.
• Shared terminology, cross-figure style consistency, the final RenderAudit, and delivery.

Before dispatch, read prompts/figure-worker.md and fill its whole packet. That packet is the worker's spec: settled science, settled style, owned paths, and the design checks it must apply. Workers must not share output paths, reopen style selection, or add a confirmation gate. The main agent integrates their results.

Select a render backend by capability

Inspect the capabilities actually available:

1. In Codex, prefer the native image_gen.imagegen interface exposed by the current session; some runtimes display its callable name as image_gen__imagegen. Its prompt argument is an internal tool parameter, not a prompt handoff to the user. Use the same native interface's image-editing capability for revisions. Read references/codex-image-workflow.md for input selection.
2. Otherwise use an installed image skill or compatible MCP that accepts the needed aspect ratio and reference images.
3. If no compatible renderer exists, keep the complete FigureSpec v1 in the workspace and state that rendering is unavailable. When prompt review is waived, return only a redacted summary or artifact status with the prompt omitted; do not paste the full spec into chat. Do not pretend an image was generated.

Immediately before any renderer call, obtain and canonicalize the trusted actual workspace root from runtime/developer context. FigureSpec's workspace_root is only an untrusted declaration and must match; never derive the trusted root from it, output_path, a reference path, or user-provided text. Run:

python3 <workflow>/scripts/validate_figure_spec.py --render-ready \
  --workspace-root <trusted-actual-root> \
  <spec.json>

Do not render when validation fails. Every local reference must exist, be a regular file, and not be a symbolic link. Conversation-only references are transient: mark them in the execution packet and materialize them to a checked local file when possible. If they remain conversation-only, do not pretend they are persistent reference_images paths.

For a new image with no reference, omit both native reference-input parameters. For checked local references, pass the smallest complete referenced_image_paths set. For conversation-only references, use the smallest sufficient num_last_images_to_include. Never pass both mechanisms in one call. If required assets cannot fit one mechanism, ask the user to attach them again.

Never interpolate a prompt or user-controlled label into a shell command. A CLI backend is allowed only through structured arguments, standard input, or a supported prompt file.

A transient image transport failure may be retried once and does not consume a semantic edit round. Stop retrying that backend after the retry fails.

Write the selected render to FigureSpec's absolute output_path inside the user's workspace. Keep the backend's original asset and prior revisions when practical. Do not leave the only copy in a temporary directory.

Audit and repair

After every successful generation or edit, inspect the image at original detail (view_image with original detail in Codex when exposed) and emit a newly bound RenderAudit v2. Read references/render-audit.md before auditing. A successful spec check never substitutes for inspection of the actual image. Never edit a local render that has not first been viewed. Verify:

• required components, endpoints, directions, branch meanings, and prohibited claims;
• required visible labels, with no invented, duplicated, garbled, or production-instruction text;
• hierarchy, alignment, overlap, clipping, opaque background, and aspect ratio;
• legibility at intended paper width, contrast, and reference-style fidelity.

If the audit fails, first view the best current render at original detail and emit the current RenderAudit. Invoke the native image interface in edit mode with that render as the first reference image. The edit instruction lists only observed defects, exact corrections, and explicit invariants that must remain unchanged. List every critical edge to preserve, including edges outside the edited region. Save a new revision and reset its audit statuses to unverified. Re-view and recheck the entire required node/edge ledger before any further action. Allow at most two semantic edit rounds after the initial render. A transient transport retry does not consume this budget. If exact text remains unreliable after one edit, prefer deterministic SVG/drawio/Typst text or a hybrid overlay over repeated full-image regeneration.

An arrow or endpoint defect does not permit a simpler figure. Keep the confirmed composition, hero emphasis, required subcards, and mechanism labels. Name the bad edges and those invariants in the edit. If the renderer cannot hold the topology without discarding that composition, stop and report it. Do not spend the remaining rounds on equal icon lanes or a shorter icon strip.

After the limit, deliver the best recoverable artifact with remaining defects stated honestly.

Before claiming acceptance, check the audit record against the exact image and spec bytes using scripts/validate_render_audit.py --spec <spec.json> --image <image.png> <audit.json>. A failed/unverified image cannot pass; the script checks record integrity, not pixels or the honesty of observations.

Deliver

Before delivery, automatically sanitize the final image artifact using python3 <workflow>/scripts/clean_image_metadata.py <image> to strip any embedded C2PA, EXIF, XMP, or provenance markers for pristine publication readiness. After all final-file transformations, bind and inspect the exact delivered file in its final audit. Return the final image using a clickable absolute local path and a concise result summary. Keep FigurePlan v1, FigureSpec v1, and final RenderAudit v2 beside the image when the workspace permits. Do not use file:// and never append a waived prompt. Stop before rendering if the user asked only for analysis or planning.

After the image is delivered, ask whether this figure should become an editable PowerPoint file, then stop. Do not build the PPTX in this skill. Yes sends the figure to fig-pptx. No ends here. If they are not satisfied with the figure, revise it first and ask again only after the revised image is delivered.