MoleCode: a skill for editing molecules as a graph
MoleCode
A skill that turns SMILES into a Mermaid graph of named atoms, so the agent edits molecules without hand-writing SMILES
- 309 ★ on the repository
- Last commit
- MIT
Minimal access
Why this level
- The skill runs a local Python conversion script and edits graph files; by its instructions it calls no external service for conversion
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/molecodeDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- The skill runs a local Python conversion script and edits graph files; by its instructions it calls no external service for conversion
This is third-party code. Review the repository files before installing.
What it does
The molecode skill gives an agent a working routine for chemistry tasks: convert the molecule to a graph, read nodes and edges, patch the graph with ordinary file-editing tools and validate the result. Every atom in the graph is a named node with its element, hydrogen count and charge. Every bond is a separate edge: single `---`, double `===`, triple `-.-`. All operations go through one script, `molecode_convert.py`. It converts SMILES, PSMILES for polymers and Markush structures to the graph and back. It also checks the formula, atom counts and the round trip, and compares two structures. For large molecules the skill describes an edit routine through a file. The same functions are available as a Python library: the molecode package installs from PyPI together with RDKit and NetworkX. The skill helps where a model otherwise slips on SMILES: swapping a functional group, closing or fusing rings, counting atoms, checking valence.
Who it is for. For chemists, bioinformaticians and scientific-tool developers who ask Claude Code or Codex to analyze and modify molecular structures.
Good fit when
- You need to swap a functional group or add a substituent and confirm the formula still holds
- You must close or fuse rings, or change a linker or scaffold
- You want atom counts per element and a valence check after an edit
- The work involves polymers in PSMILES or Markush structures with variable groups
- You need to compare two structures that may be written differently
Not a fit when
- You need quantum-chemistry calculations, protein-ligand docking or dynamics: the skill only handles structure representation
- The edit is trivial and the SMILES is unambiguous: the skill itself allows editing SMILES directly in that case
- You need domain consensus on reactions or properties: the skill is no replacement for a reference
- RDKit cannot be installed in the environment
Example request
Take aspirin as SMILES CC(=O)Oc1ccccc1C(=O)O, convert it to MoleCode, replace the acetyl group with propionyl and check the formula.Limitations
The skill lives inside the repository under .claude/skills/molecode, and it needs Python 3.9 or newer, RDKit and NetworkX. There is no separate command to install it into a global skills directory: the agent finds the skill when you open the cloned repository in it.
The examples that call a language model need a key and a provider URL, set through MOLECODE_API_KEY, MOLECODE_BASE_URL and MOLECODE_MODEL. Conversion itself runs locally: the skill's instructions forbid calling external services. The project comes with a paper, but its accuracy findings come from the authors' own tests and may differ on your task.
How to disable. Delete the cloned MoleCode directory or open the agent in another folder. Remove the library with pip uninstall molecode.
FAQ
How do I install MoleCode for Claude Code?
Run git clone https://github.com/AtomFlow-AI/MoleCode.git and then pip install -e . inside the cloned folder. Claude Code finds the skill in .claude/skills/molecode when you open that folder as a project. For Codex, AGENTS.md in the root describes the same script.
What does the doctor command do?
It checks that the environment is ready: RDKit and dependencies are installed and the script runs. Run it first, before any conversion.
Which formats does the conversion script support?
Six conversion forms between SMILES, PSMILES and Markush notation on one side and MoleCode on the other. It also offers validate for formula and atom counts, compare for structure comparison including Markush, and doctor.
Does the skill need an MCP server?
No. The skill works without MCP: the agent calls the script from the shell.
What is MoleCode in plain terms?
A way to write a molecule as a Mermaid graph: every atom gets a name and every bond its own line. The graph converts to SMILES and back deterministically and losslessly through RDKit. The agent edits nodes and edges of the graph and never has to touch a long SMILES string.
Discussion
No questions or reviews yet.
Related
SkillsA Google DeepMind skill collection for science tasks: access to biology and chemistry databases, literature search and structural biology
A Claude Code plugin and MCP server: over 1000 scientific tools for biology, chemistry and medicine, data-check commands and routing skills
166 skills for scientific work: bioinformatics, cheminformatics, clinical data, geospatial analysis and 100+ databases
A library of agent skills for medical research: literature search and appraisal, study design, data analysis and academic writing
A skill that teaches an agent to search tables, trace lineage and read the glossary in your Marmot catalog via CLI, REST and MCP.
A plugin for Claude Code, Codex and Copilot that maps ML training code into a diagram linked to source lines
README in short
The project accompanies an arXiv paper on how an explicit graph notation helps language models work with molecular structure. The repository contains a library for small molecules, polymers and Markush structures, examples of understanding, generation, editing and reasoning tasks, and a grammar reference by topic.
README badge
Original SKILL.md
--- name: molecode description: >- Use for deterministic molecule understanding, graph-level editing, generation, and validation with MoleCode — an explicit Mermaid graph in which every atom and bond is a typed, named node/edge. Converting SMILES to MoleCode exposes the molecule as explicit atoms, hydrogen counts, bonds, bond orders, stereochemistry (R/S, E/Z), aromatic/ring systems, functional groups, and linkers, so an agent can locate substructures and plan edits far more reliably than from linear SMILES. Trigger when the task is to understand or edit a molecular structure, replace a functional group, add/delete/substitute atoms, close or fuse rings, change a linker or scaffold, count atoms/elements, check formula/connectivity/ valence, design a molecule under constraints, or convert between SMILES and MoleCode. Also covers polymers (PSMILES repeat units) and Markush structures (variable R-groups). Prefer MoleCode graph inspection and editing before hand-writing SMILES; the bundled script provides the conversion and validation API. --- # MoleCode Use the bundled script first. Do not call an external service for conversion. MoleCode is the preferred working representation when an LLM needs to understand or edit a molecule. Converting SMILES to MoleCode exposes the molecule as an explicit [Mermaid](https://mermaid.js.org/) graph: every atom is a named node `prefix_Element_N[Label]` carrying its element, hydrogen count and charge, and every bond is an explicit edge (`---` single, `===` double, `-.-` triple). This graph form is usually strong enough for the model to locate substructures, reason about aromatic systems, identify fused rings, follow linkers, and plan edits directly. Reconstruct the whole molecular topology from the explicit nodes and edges before making any edit. Treat MoleCode as a **code-like molecular data structure**: inspect it, add concise `%%` comments when useful, patch it with normal file-editing tools, and validate it with the bundled script. Directly editing the graph is usually simpler and safer than generating a new SMILES by hand — adding a methyl is one new node plus one new edge, not a whole-string rewrite. ## MoleCode-first decision rule For any molecule understanding or editing request, work at the explicit graph level first: 1. Convert the input SMILES (or PSMILES) to MoleCode with the bundled script. 2. Read the nodes and edges to understand the structure and the requested change. 3. Edit the graph directly (add/remove nodes and edges; relabel hydrogen counts). 4. Validate and convert back to the requested representation with the script. Use direct SMILES editing only when the change is trivial and the structure is already unambiguous. Reach for specialized cheminformatics code only when graph