New: 97,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Molecode

by AtomFlow-AI in AtomFlow-AI/MoleCode

A skill your agent uses 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…

MITAuto-check passedResearch & Science

Install Molecode

skills CLI
$ npx skills add AtomFlow-AI/MoleCode --skill molecode -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install AtomFlow-AI/MoleCode molecode --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/AtomFlow-AI/MoleCode.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/molecode .claude/skills/molecode && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
molecode
GitHub stars
305
Token cost
~1.9k tokens
SKILL.md length
852 words
Files
7 (incl. scripts, references)
Skills in repo
1
Repo updated
First seen
Licence
MIT

At a glance

A skill your agent uses 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…

  • Works in 4 steps: Convert the input SMILES (or PSMILES) to… → Read the nodes and edges to understand… → Edit the graph directly (add/remove… → …
  • Deterministic molecule understanding
  • SKILL.md covers MoleCode-first decision rule, The six conversion forms, File-based workflow (preferred… and Authoring guardrails, plus 3 more sections
  • Runs Python scripts from its folder; calls python

What it does

Molecode is an agent skill from AtomFlow-AI/MoleCode. 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…

Its SKILL.md is about 1.9k tokens, which your agent loads only when the skill is triggered. The skill folder holds 9 other files, including scripts and reference files (for example `agents/openai.yaml`, `references/dependencies.md` and `references/molecode-syntax-full.md`).

It sits in Research & Science, covering Drug discovery and cheminformatics and Diagrams. It works with Mermaid. The repository describes itself as: Molecode presents molecules as code and enables LLMs to operate and reason on chemistry directly. The licence is MIT.

When your agent uses it

  • Deterministic molecule understanding
  • Graph-level editing
  • Validation with MoleCode — an explicit Mermaid graph in which every atom and bond is a typed
  • Named node/edge

Example prompts

  • “/molecode”

Requirements

  • Python 3

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

  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.

What it can do on your machine

Read from SKILL.md and the folder at commit a4df3b0. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 1 file in scripts/ (Python), which the agent can run.

    Shell commands in SKILL.md call:

    • python

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • mermaid.js.org

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Molecode loads about 1.9k tokens when it runs, and up to ~5.8k if it reads all its reference files. Until then it costs about 256 tokens; SKILL.md has 852 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~256
When it runs · the whole SKILL.md, loaded when a task matches
~1.9k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~5.8k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from AtomFlow-AI/MoleCode at commit a4df3b0, republished under its MIT licence (© AtomFlow-AI). 852 words, ~1,938 tokens.

Download SKILL.mdSave it as .claude/skills/molecode/SKILL.md (or your agent's skills folder). This skill also uses 6 other files; get the full folder from GitHub.
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 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 inspection plus the script are not enough (unresolved aromaticity choices, ambiguous canonical ranking, subtle stereochemical perception, persistent valence debugging, conformer/geometric reasoning).

The six conversion forms

MoleCode spans three structural domains, each convertible in both directions:

DomainTo MoleCodeFrom MoleCode
Small moleculesmiles-to-molecodemolecode-to-smiles
Polymer (PSMILES, ×n)psmiles-to-molecodemolecode-to-psmiles
Markush ({} R-groups)(author by hand)markush-to-smiles

Plus utilities: validate (formula / atom & ring counts / round-trip), compare (markush-aware graph isomorphism), doctor (environment check), and image-to-molecode (OCSR: read a molecule image with a vision model and emit a MoleCode graph — needs a vision-capable model + API key).

File-based workflow (preferred for nontrivial edits)

Multiline graphs are easier to inspect and patch on disk. When the molecule is large, the change is broad, or you are not confident emitting a complete correct graph in one pass, use the file workflow:

  1. Write source MoleCode to disk: smiles-to-molecode "<smiles>" --output source.mmd
  2. Edit source.mmd into edited.mmd with normal text edits. Keep node ids stable unless a rename is necessary.
  3. Convert back: molecode-to-smiles --input edited.mmd --output product.smi
  4. Round-trip to confirm: smiles-to-molecode --input product.smi

Use task-local names like source.mmd, edited.mmd, product.smi, or a scratch dir such as .molecode-work/. Delete scratch files when the workflow is complete and the user did not ask to keep them — but first record the final SMILES/graph and the validation evidence in your answer. If subagents are available, a supervising agent may delegate the file-based edit to a subagent with a concrete output contract (edited graph path, final SMILES, validation output, list of atom/bond edits) and review the result rather than redo the whole pass.

Show full SKILL.md (332 more words)Show less

Authoring guardrails

When writing or editing a MoleCode graph by hand, read references/molecode-syntax.md first. For polymers, Markush, stereochemistry, multi-subgraph molecules, or full format details, read references/molecode-syntax-full.md. Minimum contract:

  • Each atom node is prefix_Element_N[Label]; the Label states the element plus explicit hydrogen count and charge ([CH3], [OH], [N(+)], [O(2-)]).
  • Hydrogen counts are explicit. When you add a bond to an atom, decrement its H count: bonding onto a [CH3] makes it [CH2].
  • Every bond is an explicit edge between two existing node ids.
  • Aromatic rings are written in Kekulé form (alternating === / ---) for small molecules.
  • Stereochemistry: ===|E| / ===|Z| on double bonds; _R / _S (absolute CIP) suffix on chiral atom ids.
  • Markush abbreviations use curly braces {Boc}, {R1}, {Ar}; each {} is one chemically meaningful group (split NHBoc into [NH] --- {Boc}).
  • Validate every edited graph with the script before reporting a result.

Quick start

bash
python scripts/molecode_convert.py doctor
python scripts/molecode_convert.py smiles-to-molecode "CCO" --name Ethanol
python scripts/molecode_convert.py molecode-to-smiles --input edited.mmd
python scripts/molecode_convert.py validate --input edited.mmd

The script auto-locates the repository's molecode package, so it runs from anywhere inside the repo. It needs rdkit (and networkx for compare); run doctor first if the environment is unknown, and see references/dependencies.md for install options.

Workflow

  1. Run doctor before SMILES work if the environment is unknown.
  2. For atom/element counts, formula checks, connectivity checks, or any edit that starts from SMILES, convert to MoleCode first instead of inspecting the string.
  3. For structural edits (functional-group replacement, atom add/delete/substitute, ring closure/fusion, linker/scaffold change), edit the graph directly.
  4. For larger molecules or broad changes, use the file-based workflow.
  5. Validate edited graphs with validate (formula, counts, round-trip), then export the requested SMILES/PSMILES with the matching *-to-* command.
  6. For polymers, work on the repeat unit (two *); for Markush, author the graph with {} abbreviation nodes and check candidates with compare.
  7. Clean up scratch files when they are not requested outputs.

Resources

  • scripts/molecode_convert.py — stable CLI over the repo's molecode package.
  • references/molecode-syntax.md — compact syntax for manual molecule edits.
  • references/molecode-syntax-full.md — full syntax: polymers, Markush, stereo, multi-subgraph molecules and reactions, edge cases.
  • references/operations.md — command examples and supported conversion paths.
  • references/dependencies.md — dependency policy and install options.

© AtomFlow-AI, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 6 other files (scripts, references) in .claude/skills/molecode of AtomFlow-AI/MoleCode.

  • SKILL.md
  • agents/openai.yaml
  • references/dependencies.md
  • references/molecode-syntax-full.md
  • references/molecode-syntax.md
  • references/operations.md
  • scripts/molecode_convert.py

Open the folder on GitHubat commit a4df3b0

Compare with similar skills

Molecode next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Molecode compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Molecode this skillAtomFlow-AI/MoleCode305—~1.9kAutomated safety check: PassMIT
Paper Analyzerzsyggg/paper-craft-skills1.3k—~1.9kAutomated safety check: PassNone
NSFC Technical Route WriterHuiyuLi-2000/Chinese-Grant-Writer-Skills4281 repos~701Automated safety check: PassMIT
Research Question Knowledge GraphDrchronx/ai-agent-research-starter-kit134—~686Automated safety check: PassCustom licence
Paper Interpreterchujianyun/skills740—~810Automated safety check: PassCustom licence
Scholar Conceptualjoshzyj/open-scholar-skill167—~5.3kAutomated safety check: PassCustom licence

Similar skills

  • Paper Analyzer

    zsyggg/paper-craft-skills

    将学术论文转化为深度HTML长文。6轮强制工作流、代码仓库搜索、公式渲染、Mermaid图表. An agent skill from zsyggg/paper-craft-skills.

    1.3k GitHub stars~1.9k tokensUpdated 4 mo ago
    Research & ScienceAuto-check passed

  • NSFC Technical Route Writer

    HuiyuLi-2000/Chinese-Grant-Writer-Skills

    Polishes the research methods, technical route and innovation sections of an NSFC grant proposal from an idea you already have, without inventing a new research plan.

    428 GitHub starsUsed in 1 repo~701 tokens
    Research & ScienceAuto-check passed

  • Research Question Knowledge Graph

    Drchronx/ai-agent-research-starter-kit

    Build a research question knowledge graph from papers, theories, variables, methods, datasets, authors, venues, and projects.

    134 GitHub stars~686 tokensUpdated 4 mo ago
    Research & ScienceAuto-check passed

  • Paper Interpreter

    chujianyun/skills

    论文解读助手。适用于用户发送 arXiv 论文链接，并希望下载论文、解读论文、生成读书笔记、做论文拆解或输出详细报告时使用。会在工作目录创建论文文件夹、下载 PDF 与 TeX Source（如有）、生成中文 Markdown 报告。默认先交付初稿，不自动复查；如果用户明确同意，再安排后续复查。不适用于只要简短推荐语的情况。

    740 GitHub stars~810 tokensUpdated 12 days ago
    Documents & OfficeAuto-check passed

  • Scholar Conceptual

    joshzyj/open-scholar-skill

    Build original theoretical frameworks and produce publication-quality conceptual diagrams for social science research.

    167 GitHub stars~5.3k tokensUpdated 19 days ago
    DevelopmentAuto-check passed

  • Patent Disclosure Handoff

    Light0305/Light-skills

    Builds an evidence-backed invention disclosure packet from a project or research result for attorney or patent-agent review, without giving legal advice.

    640 GitHub stars~2k tokensUpdated 3 mo ago
    Legal & ComplianceAuto-check passed

Works with

Categories

Questions about Molecode

What does Molecode do?

A skill your agent uses 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…. Molecode is an agent skill from AtomFlow-AI/MoleCode. 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.

When should I use Molecode?

Molecode fits situations like: deterministic molecule understanding; graph-level editing; validation with MoleCode — an explicit Mermaid graph in which every atom and bond is a typed; named node/edge.

How do I install Molecode in Claude Code?

Run `npx skills add AtomFlow-AI/MoleCode --skill molecode -a claude-code`. Or copy the skill folder (.claude/skills/molecode in AtomFlow-AI/MoleCode) into .claude/skills/molecode in your project. Claude Code loads it when a task matches its description.

How do I install Molecode in Codex?

Run `npx skills add AtomFlow-AI/MoleCode --skill molecode -a codex`. Or copy the skill folder (.claude/skills/molecode in AtomFlow-AI/MoleCode) into .agents/skills/molecode in your project. Codex loads it when a task matches its description.

Can I use Molecode in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add AtomFlow-AI/MoleCode --skill molecode -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/molecode, .gemini/skills/molecode, .github/skills/molecode and .opencode/skills/molecode in your project.

What does Molecode need to run?

Going by SKILL.md and its folder, Molecode needs Python for the scripts in its folder and the command-line tools its instructions call (python). Our summary lists: Python 3.

Does Molecode access the network?

SKILL.md names 1 domain. As links in the text: mermaid.js.org. This is read from the text; nothing was executed.

Is Molecode safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Molecode use?

Molecode is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Molecode use?

About 1.9k tokens (SKILL.md is roughly 7.8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 3.9k tokens, read only when the agent opens those files.

What are the alternatives to Molecode?

Skills that share tags, products or a category with Molecode: Paper Analyzer (zsyggg/paper-craft-skills, 1.3k stars), NSFC Technical Route Writer (HuiyuLi-2000/Chinese-Grant-Writer-Skills, 428 stars), Research Question Knowledge Graph (Drchronx/ai-agent-research-starter-kit, 134 stars) and Paper Interpreter (chujianyun/skills, 740 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Molecode?

AtomFlow-AI (a GitHub organization) maintains it in AtomFlow-AI/MoleCode, which has 305 GitHub stars. The repository was last updated on June 4, 2026.

Source: AtomFlow-AI/MoleCode on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.