add skill for pymol

- [ChatMol](#chatmol)

- [ChatMol](#chatmol)

  - [Overview](#overview)

  - [Overview](#overview)

  - [PyMOL Skill](#pymol-skill)

  - [PyMOL Plugin](#pymol-plugin)

  - [PyMOL Plugin](#pymol-plugin)

    - [v2 (Recommended)](#v2-recommended)

  - [ChatMol + Streamlit](#chatmol--streamlit)

  - [ChatMol + Streamlit](#chatmol--streamlit)

  - [ChatMol python package](#chatmol-python-package)

  - [ChatMol python package](#chatmol-python-package)

  - [Copilot](#copilot)

  - [Copilot](#copilot)

  - [ChatMol Website](#chatmol-website)

  - [ChatMol Website](#chatmol-website)

  - [Acknowledgements](#acknowledgements)

  - [License](#license)

  - [License](#license)

</details>

</details>

Through these tools, we strive to empower scientists to better utilize large language models in solving scientific problems. Our goal is to bridge the gap between advanced AI capabilities and practical scientific research needs in molecular biology and related fields.

Through these tools, we strive to empower scientists to better utilize large language models in solving scientific problems. Our goal is to bridge the gap between advanced AI capabilities and practical scientific research needs in molecular biology and related fields.

## PyMOL Skill

A skill that lets agents generate publication-quality molecular structure figures using PyMOL. You describe what you want to see, a binding site for example, and the LLM writes a `.pml` script, runs it headlessly, and hands you the rendered PNG, the script, and a `.pse` session file you can open in PyMOL to keep tweaking.

**How to Install?**

The easiest way to use the PyMOL skill is through **coding agent** or **openclaw**. Simply ask it to `Install the PyMOL skill from https://github.com/ChatMol/ChatMol/tree/main/pymol_skill` and it will automatically set it up for you.

If you prefer to do it manually, drop the `pymol_skill/` folder into your skills directory:

- **Claude Code:** place in `.claude/skills/` in your project root, or in `~/.claude/skills/` for global access

- **Codex / other agents:** point the skill config to the folder so the agent reads `SKILL.md` on trigger

<!-- a table of figures -->

| Protein overview                          | Binding site                        | Protein-protein interface       |

| ----------------------------------------- | ----------------------------------- | ------------------------------- |

| ![](./assets/5xh3_vs_4eb0_comparison.png) | ![](./assets/5xh3_binding_site.png) | ![](./assets/6m0j_overview.png) |

| compare 4eb0 and 5xh3                     | show ligand interactions in 5xh3    | show PPI interface in 6m0j      |

## PyMOL Plugin

## PyMOL Plugin

**Installation**  

An LLM-powered plugin for PyMOL that translates natural language into molecular visualization workflows.

Simply run the following command in PyMOL command line to install the plugin:

**Versions**

| Directory          | Description                                                                              |

| ------------------ | ---------------------------------------------------------------------------------------- |

| `pymol_plugin/v2/` | Agentic plugin with tool-calling loop, session inspection, vision feedback, and Qt5 GUI. |

| `pymol_plugin/v1/` | Original plugin with direct LLM-to-command translation.                                  |

### v2 (Recommended)

**Installation**

```python

```python

load https://raw.githubusercontent.com/ChatMol/ChatMol/main/chatmol.py

run /path/to/pymol_plugin/v2/chatmol.py

```

```

For permanent installation, go to `Plugin` -> `Plugin Manager` -> `Install New Plugin` and enter the URL `https://raw.githubusercontent.com/ChatMol/ChatMol/main/chatmol.py`.

**Quick start**

**Usage**  

The simplest way to get started is to use the `chatlite` command in PyMOL. 

```pymol

```pymol

chatlite download 1ake and color it by secondary structures

set_api_key sk-or-xxxx

chat fetch 1ubq and show as cartoon

chat fetch 3wzm, show enzyme-substrate interactions in chain A with publication quality

```

```

![img](./assets/img_ss.png)

Supported providers include OpenRouter, DeepSeek, Kimi (Moonshot), and GLM via OpenAI-compatible APIs.

Refer to the [doc](./pymol_plugin/README.md) for more details.

<details>

<summary>v1 (Legacy)</summary>

**miniGUI**  

**Installation**

We also provide a miniGUI for ChatMol-Lite, which can be used as a task execution agent or Q&A chatbot. It retains your entire conversation history with ChatMol, and you have the flexibility to modify the execution plan suggested by ChatMol. For example, you can delete certain commands or add additional commands before sending them to PyMOL. You can launch the miniGUI from a terminal.

```python

load https://chatmol.com/pymol_plugins/chatmol-latest.py

```

```bash

**Quick start**

cd miniGUI

```pymol

python miniGUI.py

chatlite show me a protein

set_api_key openai, sk-proj-xxxx

chat show me a protein

```

```

Here is a screenshot of the miniGUI:

![img](./assets/chatmol_lite.png)

For self-hosted models via Ollama:

```pymol

update_model phi-4@ollama

```

</details>

![](./pymol_plugin/demo.png)

See the full plugin documentation in [pymol_plugin/README.md](./pymol_plugin/README.md).

## ChatMol + Streamlit

## ChatMol + Streamlit

---

name: pymol-visualization

description: >

  Generate publication-quality molecular visualization images using PyMOL.

  Use this skill whenever the user mentions PyMOL, molecular visualization,

  protein rendering, structure figures, PDB visualization, ray tracing

  molecules, or wants to create images of proteins, ligands, binding sites,

  protein-protein interactions, or any biomolecular structure. Also trigger

  when the user wants to: make a figure of a crystal structure for a paper

  or presentation; render a protein surface; show binding pockets; visualize

  protein-ligand interactions; create Goodsell-style illustrations; produce

  cartoon representations with highlighted residues; compare multiple

  structures side by side; or generate any molecular graphics output —

  even if they don't mention "PyMOL" by name. Trigger for any request

  involving PDB files, molecular surfaces, cartoon ribbons, stick models,

  electron density, or structural biology figures.

---

# PyMOL Visualization Skill

Generate publication-quality molecular structure images using PyMOL.

## Prerequisites

PyMOL must be installed. Check with:

```bash

pymol -c -q -e "print('ok')" 2>/dev/null && echo "PyMOL available" || echo "PyMOL not found"

```

If missing: `conda install -c conda-forge pymol-open-source`.

## Workflow

### 1. Ask the User

Before writing any script, clarify:

- **Structure**: PDB ID, uploaded file path, or AlphaFold model?

- **Goal**: What does the figure show? (e.g. protein overview, binding site, PPI interface, active site, mutation, surface, alignment)

- **Style preference**: Any preferred colors or theme? Journal figure vs. presentation vs. artistic?

### 2. Write a .pml Script and Run It

```bash

pymol -c -q script.pml

```

`-c` = no GUI (headless), `-q` = quiet. For Python API logic, use `pymol -c -q -r script.py`.

### 3. Read the Reference Before Writing

Read `references/recipes.md` before writing — it contains scene-specific recipes and

essential PyMOL commands organized by visualization goal.

### 4. Deliver Output

Always deliver **three files**:

1. **PNG image** — the rendered figure

2. **PML script** — so the user can reproduce or tweak

3. **PSE session** — so the user can open in PyMOL GUI and adjust interactively

Save all to user's desktop and use `present_files`.

## Script Template

Every script should follow this structure:

```pml

reinitialize

# --- Load ---

fetch 4HHB, async=0

# or: load /path/to/structure.pdb, myprotein

# --- Clean ---

remove solvent

remove elem H

set valence, 0

# --- Base look ---

bg_color white

space cmyk

set ray_shadow, 0

set ray_trace_mode, 1

set antialias, 3

set ambient, 0.5

set spec_count, 5

set shininess, 50

set specular, 1

set reflect, 0.1

set orthoscopic, on

set opaque_background, off

set cartoon_oval_length, 1

set cartoon_rect_length, 1

set cartoon_discrete_colors, on

dss

# --- Representation (scene-specific) ---

hide everything

show cartoon

# ...

# --- Color ---

util.color_chains("(all) and elem C", _self=cmd)

util.cnc("all", _self=cmd)

# --- Camera ---

orient

# zoom sele, 8

# --- Save session BEFORE ray tracing ---

save /mnt/user-data/outputs/structure.pse

# --- Render ---

ray 2400, 1800

png /mnt/user-data/outputs/structure.png, dpi=150

quit

```

## Essential Patterns

**Show sidechains cleanly:**

```pml

cmd.show("sticks", "((byres (sele)) & (sc. | (n. CA) | (n. N & r. PRO)))")

```

**Molecule-agnostic coloring:**

```pml

util.color_chains("(sele) and elem C", _self=cmd)

util.cnc("sele", _self=cmd)

```

**Surface + cartoon as separate objects:**

```pml

create surf_obj, sele, zoom=0

show surface, surf_obj

set transparency, 0.5, surf_obj

cmd.color_deep("white", "surf_obj", 0)

```

**Ball-and-stick for ligands:**

```pml

show sticks, ligand

show spheres, ligand

set sphere_scale, 0.25, ligand

set stick_radius, 0.15, ligand

```

**Goodsell style (flat, illustrative):**

```pml

set ray_trace_mode, 3

set ray_trace_color, black

unset specular

set ray_trace_gain, 0

unset depth_cue

set ambient, 1.0

set direct, 0.0

set reflect, 0.0

```

## Key Rules

1. **Always `space cmyk`** for print colors

2. **Always `remove elem H`** unless user needs hydrogens

3. **Always save `.pse`** before ray tracing — this is the user's editable session

4. **`set valence, 0`** unless showing ligand bond orders

5. **Create separate objects** for surface overlays (transparency is per-object)

6. **Use `async=0`** with `fetch` — otherwise structure isn't loaded when next command runs

7. **End script with `quit`** — otherwise PyMOL hangs in batch mode

8. **Render large** (1200x900+) — downscale later for quality