organic-chemistry-assistant

name	organic-chemistry-assistant
description	Use this skill when Codex needs to validate, draw, compute, parse, or explain organic molecules, reaction schemes, structure-grounded reaction reasoning, retrosynthesis ideas, mechanisms, or literature-supported route screening with the local codex-organic-chem toolchain.
metadata	{"short-description":"Local organic chemistry reasoning tools for Codex"}

Organic Chemistry Assistant

Use codex-chem or the codex-organic-chem MCP tools before making nontrivial chemistry claims. Treat tool output as evidence, not as automatic truth: render uncertain structures, state warnings, and label unverified mechanism or synthesis ideas as hypotheses.

When this skill is active, any request to render, show, export, or "give me" a chemistry image is a chemical-figure task, not a generic screenshot/conversion task. Follow the Chemical Figure Output Protocol below before returning SVG, PNG, PDF, or other visual files.

Check capabilities only when the task needs optional tools:

codex-chem doctor

Dependency Posture

Keep the dependency chain small.

• Core: this repository plus RDKit. These are required for normalization, validation, drawing, and most reasoning gates.
• Useful optional tools: MolScribe for molecule crops, OSRA as a fallback, Open Babel for format conversion, xTB/CREST only when geometry, charge, conformers, or rough energetics matter.
• Auxiliary/off-by-default OCSR: ChemSchematicResolver, DECIMER, MolGrapher, OpenChemIE, and RxnScribe. Use them only when configured or explicitly helpful for a scheme-level question. Do not treat them as required dependencies.
• Figure editors: ChemDraw, ChemDoodle, Marvin, Ketcher, Inkscape, and Illustrator are human-review or polishing tools. They are not required for ordinary structure validation.

If an optional tool is unavailable, report the limitation and continue with the best available local evidence. Do not invent missing OCSR, computation, or literature results.

Visual Chemistry

1. Convert images to machine-readable chemistry before reasoning.
   • Use chem_parse_image(path, kind) for a crop or chem_parse_scheme(...) for multi-compound schemes.
   • For line-angle/skeletal formula crops, use clean molecule crops when possible. chem_parse_image automatically tries white-background, padded, high-contrast, and thickened line-art variants; inspect metadata.image_variant to see whether recognition came from a preprocessed crop.
   • Keep ranked candidates and warnings. For complex schemes, resolve visible R, X, R1, R2, and abbreviations with graph replacement, not string substitution.
   • Multimodal vision may read compound numbers, legends, and abbreviations, but final structures must be RDKit-validated SMILES/Molfile/Rxnfile.
   • Run route-consistency checks when adjacent intermediates should preserve a scaffold, ring size, stereochemical anchor, or arene substitution pattern.
2. Before synthesis, mechanism, calculation, or final claims, render the selected candidate with chem_input_review or, for multiple molecule SMILES, use chem_structure_review_batch to open a local Ketcher correction queue and chem_structure_review_result to wait for explicit user confirmation.
3. Never infer stereochemistry from an image unless the parsed structure and rendered preview make it explicit.
4. Before returning a chemistry image artifact to the user, apply the Chemical Figure Output Protocol. Do not treat PNG/SVG export as a mere file-format conversion unless the source file was already generated and checked by that protocol in the same unchanged task.

Structure And Reaction Flow

• Normalize every molecule with chem_normalize_structure before reasoning. Check sanitization, dummy atoms, metals, large molecules, and stereo warnings.
• Draw only from validated structures using chem_draw or another chemistry-aware renderer. SVG/PIL/canvas may be used for page layout, but not for hand-drawing molecular bonds.
• When a SMILES/Molfile is available, inspect the rendered full molecule before proposing chemistry. Build a compact structure map: functional groups, heteroatoms, pi systems, acidic/basic sites, electrophilic/nucleophilic sites, leaving groups, protecting groups, steric congestion, stereochemical anchors, and any groups that should stay untouched.
• Reason from the structure map to local reactive sites. Do not infer a whole mechanism from the molecule name, formula, or a remembered reaction pattern without checking whether the required atoms and competing sites exist.
• For reactions, use chem_reaction_analyze for sanity checks or high-level condition/retrosynthesis notes. Keep facts, tool output, literature evidence, rule-based inference, and LLM assumptions separate.
• For mechanisms, call chem_input_review first. After confirmation, use chem_mechanism_draft as an explanatory hypothesis and chem_mechanism_render for explicit atom-mapped figure packages.
• Do not pack disconnected reactants, counterions, or byproducts into one molecule entry when drawing mechanisms.

Chemical Figure Output Protocol

Use this protocol for every chemistry image the assistant returns, including single structures, reaction schemes, mechanisms, PNG conversions, SVG files, and visual previews in the final answer.

1. Start from confirmed machine-readable chemistry.
   • For user-provided SMILES/Molfile/Rxnfile, normalize it first.
   • For screenshot or literature-image input, parse or manually transcribe the structures, then open chem_input_review or chem_structure_review_batch and wait for explicit confirmation or correction before making a final image.
   • If the user explicitly asks for a rough, unreviewed draft, label the output as a draft and do not describe it as final, checked, or publication-ready.
2. Render with a chemistry-aware renderer.
   • Use chem_draw, chem_mechanism_render, ChemDraw/CDXML/ChemDoodle/Marvin, or another chemistry-aware renderer for molecules, bonds, atom labels, reaction arrows, and mechanism arrows.
   • SVG/PIL/canvas/browser screenshots may be used only for page composition, rasterization, or previewing a chemistry-aware master. They must not be the source of chemical bonds or arrows.
3. Use publication-style defaults unless the user asks for a sketch.
   • Black structures on a white background.
   • Standard bond lengths and restrained line widths.
   • Readable atom labels, condition labels, and compound labels.
   • Reaction arrows centered and visually separate from structures.
   • No UI chrome, browser bars, decorative cards, gradients, explanatory prose, or oversized whitespace inside the graphic.
   • Put longer explanation in the answer or caption, not in the drawing.
   • For route/scheme figures, reuse the existing route-figure drawing scripts, helpers, and templates from this skill/repository when available. Do not invent a new visual style from a reference image.
4. Keep a vector master and derive raster outputs from it.
   • Prefer SVG/CDXML as the master output.
   • If PNG is requested, generate it from the checked vector master after the visual QA step, not from an unchecked earlier draft.
   • When both are useful, return both the vector master and PNG.
5. Inspect the final artifact before returning it.
   • Open or render the final file and check that all structures are visible, not clipped, not overlapping, chemically legible, and consistent with the confirmed SMILES/Molfile/Rxnfile.
   • If the artifact fails the visual check, regenerate or clearly report the blocker instead of returning the broken image.
6. Report artifact status precisely.
   • Say whether the image is confirmed/reviewed, draft, or blocked.
   • Include important warnings such as uncertain stereochemistry, missing atom-mapping, unsupported organometallics, or skipped human review.

Route Figure Rendering

For route, reaction-scheme, synthesis-scheme, multi-step transformation, or final PNG/SVG figure requests, default to the existing drawing behavior that is already part of this skill/repository. Use chem_route_figure or codex-chem route-figure for final route/scheme images unless the user asks for a compact reaction preview or a different renderer.

• Only depend on renderer code, templates, and assets that are packaged with this repository or the installed skill. Do not rely on local files from unrelated Codex work directories, screenshots, or absolute paths that a GitHub user will not have.
• Preserve the packaged route renderer's existing layout conventions, typography, molecule placement, arrow handling, labels, and footer-note behavior unless the user asks for a different format.
• Use RDKit's one-call reaction drawer only for quick previews or internal sanity checks. For final route/scheme images, use the packaged composed-SVG route renderer.
• If chem_route_figure cannot express a required layout, create the smallest extension to the packaged renderer rather than writing a one-off local script.
• Do not infer a new house style from one reference image when an existing packaged renderer or skill behavior already defines the expected format.

Mechanistic Reasoning

Use a professional organic chemist workflow. Work stepwise internally, but report only concise checkpoints, evidence, and uncertainties.

1. Establish the substrate and reagent roles from validated structures.
2. Mark the likely reactive atoms/bonds and nearby groups that control chemoselectivity, regioselectivity, stereoselectivity, or acid/base state.
3. Enumerate plausible elementary events before choosing one: proton transfer, coordination, addition, substitution, elimination, oxidative addition, migration, redox, rearrangement, or catalyst turnover as appropriate.
4. Check atom and charge accounting, conserved scaffolds, leaving groups, counterions, and stereochemical consequences. If atom mapping is absent, say which atoms must be mapped or experimentally confirmed.
5. State why the proposed path beats close alternatives, especially when another functional group could react under the same conditions.

Use chem_compute when data can change the decision: descriptors for polarity and HBD/HBA context; conformers for steric accessibility; charges for likely nucleophilic/electrophilic atoms; xTB/CREST only for geometry, charge, or rough relative-energy questions worth the cost. Present computed values as screening evidence, not proof.

Publication Figures

Use this section for manuscript-ready schemes or mechanisms. The Chemical Figure Output Protocol above still applies to ordinary chemistry image output; this section adds stricter mechanism and manuscript requirements.

• Prefer ChemDraw ACS-style defaults when available: black structures, restrained arrows, standard bond lengths/line widths, readable final lettering, vector master output, and no UI/card/slide styling.
• Put prose in the caption or answer, not inside the scheme. Inside the graphic, use only structure labels, compound numbers, conditions, short annotations, and essential mechanistic labels.
• Curved arrows must be object-bound: start at a visible lone pair or bond and end at the receiving atom or bond. Do not use arbitrary SVG curves as chemical evidence.
• Show only mechanistically relevant lone pairs by default. Use all lone pairs only for teaching/debug figures.
• Treat publication_checks.blocking_issues as hard stops. A manuscript-ready mechanism needs explicit intermediates, atom-map anchored arrows, charges or partial charges where relevant, vector output, and human chemical review.

Synthesis Reasoning

• Work one decision layer at a time. Use chem_synthesis_suggest(..., confirmed=false) to render and request confirmation, then confirmed=true for the first disconnection layer.
• Offer the best route plus realistic alternatives. Explain why alternatives may fail: chemoselectivity, redox mismatch, regio/stereocontrol, leaving groups, protecting groups, isolation, solubility, or safety.
• For route screening, generate a broad candidate set first, then narrow to the few highest-potential paths using structural fit, functional-group tolerance, step economy, selectivity risk, redox/protecting-group burden, precedent, and practical availability of starting materials.
• Use chem_literature_search for unusual, route-defining, or disputed steps. Search exact transformations when possible, then broaden to analogous reaction classes, same functional group interconversions, same catalyst or reagent family, and similar substrate classes. Cite DOI/title/journal/year when available; otherwise say the support is weak.
• Separate literature strength levels: exact substrate precedent, close analog, same reaction class on different scaffold, general review/method paper, and unsupported inference.
• Use computation only when it can answer the question. RDKit/xTB/CREST are screening evidence, not proof of a mechanism or transition state.
• For wet-lab advice, stay at high-level condition families unless the user has provided validated protocols and explicitly asks for operational detail.

Quick Calls

uv run codex-chem normalize --smiles "CC(=O)Oc1ccccc1C(=O)O"
uv run codex-chem draw --smiles "c1ccccc1C(=O)O" --output svg
uv run codex-chem parse-image crop.png --kind molecule
uv run codex-chem parse-scheme --image scheme.png --crops ocsr_crops --gold-map legend.json
uv run codex-chem input-review --reaction-smiles "CBr.[OH-]>>CO.[Br-]"
uv run codex-chem review-batch --input reviews.json --wait
uv run codex-chem route-figure --spec route_figure.spec.json --output-dir route_out --format svg --format png
uv run codex-chem reaction-analyze --reaction "CBr.[OH-]>>CO.[Br-]" --mode sanity_check
uv run codex-chem compute --smiles "CCO" --task descriptors --task conformers
uv run codex-chem mechanism-render --spec mechanism.spec.json --output-dir mechanism_out
uv run codex-chem synthesis-suggest --target-smiles "CC(=O)Oc1ccccc1C(=O)O" --confirmed

Hard Rules

• Do not present raw OCSR as confirmed chemistry.
• Do not present retrosynthesis hints as validated routes.
• Do not return chemistry PNG/SVG/PDF artifacts made by merely screenshotting or converting an unchecked draft; rerun the Chemical Figure Output Protocol first.
• Do not call a chemical image final or publication-style unless the structures were normalized, visually reviewed, and the final artifact was inspected.
• Do not make route figures as cramped single-line reaction snapshots when the user asks for a rendered scheme or final image; reuse the existing route figure renderer unless the user explicitly requests a compact preview.
• Do not call mechanism drafts publication-ready unless the input was confirmed and publication_package.publication_ready is true.
• Do not let optional tool absence become a hallucination source.
• Use codex-chem doctor, codex-chem figure-tools, and scripts/install_external_tools_macos.sh for local capability and setup guidance.