fig1-draw

fig1-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 acceptable diagrams. This is the sole entry point for design and prompt compilation; do not treat prompt rhetoric as a second round of scientific design.

Choose output by request

User intent	Action and stopping point
Construct a drawing prompt / write only the prompt	construct: design brief and full prompt; do not generate an image
Check or diagnose an existing prompt	diagnose: locate the problem, its impact, and the minimal fix; do not alter files or generate images on your own
Revise the prompt based on feedback	revise: changes, retained items, and the full new prompt; do not generate images automatically
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 full topology, does not generate images
Turn text in an AI image into editable PPT	According to references/editable-pptx.md , write the checklist and assemble the PPTX; do not modify the source PNG, do not open another skill

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 on demand

Load only what the current stage needs:

• Construct, diagnose, or revise 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)
• Editable PPT text → references/editable-pptx.md. When delivering a raster image, only mention that it can be done; read and assemble only after the user accepts this image and requests editable text

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

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 fig1-analyze. User gave explicit nodes/flow; compile FigureSpec v1 and render directly.
Draft Notes / Outline / Partial Draft	../fig1-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)	../fig1-analyze/SKILL.md	Full Planning. For complete papers with experiments/results: multi-figure strategy, claim verification, and constraints.
Repository path or repository URL	../fig1-analyze/SKILL.md	Extract semantic architecture graph; omit engineering plumbing (data loaders, trainers).
Paper plus repository	../fig1-analyze/SKILL.md	Paper/user defines narrative & topology; repository supplies parameter & dimension verification.
External style reference	../fig1-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 fig1-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 diagram's core answer, distinguishing main content, supporting content, and caption-only.
2. Extract stable component IDs, typed connections, permission boundaries, forbidden relationships, and evidence from upstream analysis or user input. Do not borrow algorithms from reference images, and do not fill missing evidence in as certain fact.
3. Confirm the 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 and is not a decorative sentence appended after the prompt is written; see references/prompt-design-logic.md。
4. Design the reading order, main area, semantic grouping, connection channels, and necessary visual anchors by combining scientific meaning with the chosen style. Nest only when a real hierarchy requires it; proportion is a compositional aid. Icons, small diagrams, formula cards, robots, or bubbles are all optional. Pure label nodes are used only when the chosen style allows it. For any style, do not reduce the main area's proportions, nesting levels, and notation language into a row of equally sized icons.
5. Lock visible text, semantic colors, and non-color encodings, and check text capacity and readability under the chosen style; close all edges before compilation. For revisions, write the Delta and Invariants first; color changes must not alter the scientific topology.
6. Compile content, layout, and style uniformly into complete compact natural language, rather than layering style patches onto an old prompt. prompt-only is delivered here; rendering tasks then complete and validate the FigureSpec and hand it 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. Separate execution, advice, feedback, storage, and exception connections; do not infer connections by 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 viewed reference images; 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.

Hue is bound to responsibility, 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 general facts. Support rich color schemes, grayscale printing, or dark backgrounds required by the data. Follow the surface and shadow rules determined by the reference/user; avoid requiring 3D in one place while globally prohibiting 3D in another.

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

Text and compilation

Region titles usually no more than 5 words, labels/edge labels usually no more than 3 words; this is an abbreviation recommendation, must not damage scientific meaning, and must not 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 panel splitting or deterministic typesetting; do not increase density by endlessly shrinking fonts.

Use compact prose for model input, not Markdown headings, bold, lists, or tables surrounding instructions; preserve approved mathematical notation and precise labels. By default, place the figure title in an external caption; show a short figure title only when explicitly required by the user or the design. Order is purpose, composition and components, closed edge list, exact visible text, style color scheme, 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, tell the user that its visible text can be replaced with editable PowerPoint text boxes. Do not build the PPTX in that turn. Build it only after they accept this figure and ask for the editable text; follow references/editable-pptx.md, keep the sanitized PNG, and replace only text that is already visible. If they are not satisfied with the figure, revise the figure first. Do not start a third skill and do not rerun image generation for the text step.