---

name: molecule-io-core description: "Use for RDKit molecule creation, file/string I/O, validation, sanitization, atom/bond/ring queries, substructure matching, hydrogens, and editable molecule workflows. Route descriptors/fingerprints, conformers/drawing, reactions/standardization, and R-group workflows to their dedicated RDKit sub-skills." disable-model-invocation: true metadata: disco-role: operating license: BSD 3-Clause

RDKit Molecule I/O Core

Use this sub-skill when a task asks an agent to parse, validate, inspect, edit, serialize, or round-trip RDKit molecules from SMILES, SMARTS, MolBlocks, SDF, or delimited SMILES files.

Route here

• Parse strings with Chem.MolFromSmiles, Chem.MolFromSmarts, Chem.MolFromMolBlock, or supplier classes.
• Write canonical/isomeric SMILES, MolBlocks, SDF, or SMILES files with Chem.MolToSmiles, Chem.MolToMolBlock, Chem.SDWriter, or Chem.SmilesWriter.
• Validate invalid SMILES and empty supplier entries without silently passing None molecules downstream.
• Control sanitization, kekulization, aromaticity, valence handling, and explicit/implicit hydrogens.
• Query atoms, bonds, rings, properties, and substructure matches.
• Make small structural edits with Chem.RWMol or Chem.EditableMol and re-sanitize the result.

Route elsewhere

• Descriptors, fingerprints, bit vectors, similarity, and clustering: descriptors-fingerprints.
• 3D conformers, force-field optimization, 2D coordinates, and drawing: conformers-drawing.
• Reaction SMARTS, product sanitization after reactions, molecule standardization, tautomer handling, stereochemistry workflows, and R-groups: reactions-standardization.
• Pandas, database, RDKit data-file location, and CLI integration: data-cli-integration.

Start with these references

• references/molecule-io.md for parsing, suppliers, writers, and round-trip patterns.
• references/sanitization-and-queries.md for sanitization, hydrogens, atom/bond/ring queries, substructure matching, and molecule editing.
• references/troubleshooting.md for common failures and safe recovery patterns.
• scripts/molecule_io_smoke.py for a tiny standalone smoke test that canonicalizes SMILES and round-trips SDF.

Core workflow

1. Parse input and immediately check for None before doing any chemistry.
2. Canonicalize with Chem.MolToSmiles(mol, isomericSmiles=True) when comparing or de-duplicating molecules.
3. Use suppliers defensively: iterate with indexes, skip or report None, and preserve molecule names/properties when writing SDF.
4. If using sanitize=False, run a deliberate Chem.SanitizeMol step before relying on valence, aromaticity, rings, descriptors, or substructure behavior.
5. For structural edits, edit a copy, call GetMol(), update property cache if needed, then sanitize or report the sanitization failure.

Minimal examples

from rdkit import Chem

mol = Chem.MolFromSmiles("CC(=O)O")
if mol is None:
    raise ValueError("invalid SMILES")
canonical = Chem.MolToSmiles(mol, isomericSmiles=True)

query = Chem.MolFromSmarts("[CX3](=O)[OX2H1]")
matches = mol.GetSubstructMatches(query)

edited = Chem.RWMol(mol)
atom_index = edited.AddAtom(Chem.Atom("Cl"))
edited.AddBond(0, atom_index, Chem.BondType.SINGLE)
new_mol = edited.GetMol()
Chem.SanitizeMol(new_mol)

Bundled check

Run the bundled helper in any environment where RDKit is importable:

python scripts/molecule_io_smoke.py --smiles "CCO" "c1ccccc1" --include-invalid

It asserts that valid SMILES parse, invalid SMILES are reported, canonical SMILES are stable after a second parse, and a tiny SDF round-trip preserves molecule count and properties.