PyMOL
Prerequisites
uv: Read the uv skill and follow its Setup instructions to ensure
uv is installed and on PATH.
- User Notification: If .licenses/pymol_LICENSE.txt does not already exist
in the workspace root directory then (1) prominently notify the user to
check the license at https://www.pymol.org/, then (2) create the file
recording the notification text and timestamp.
Overview
All PyMOL commands run on the host via uv with OSMesa software rendering — no
GPU, display, or X server is needed. Structure files must be downloaded to the
host before running PyMOL.
Do NOT use when:
- The user wants to run AlphaFold predictions.
- The user wants docking or molecular dynamics simulations.
- The user only has a sequence and no structure file — fetch the structure
first. Check if any other installed skills can retrieve structures from the
PDB or AlphaFold Database before proceeding.
Setup (Agent Instructions)
Ensure that uv is installed on the host system. The PyMOL scripts use PEP 0723
headers to declare their dependencies, and uv run will automatically handle
installing them (including pymol-open-source-whl) when the script is executed.
Core Rules
- Output paths must be absolute or relative to the user's project root.
Always run PyMOL scripts from the user's project directory.
- Software rendering only. Use
cmd.png() for output. Never use
cmd.draw() or cmd.ray() with hardware acceleration — OSMesa does not
support it. Set environment variable PYOPENGL_PLATFORM=osmesa for headless
rendering.
- Always save a
.pse session file alongside any PNG output. This lets
the user open the session in their local PyMOL for further inspection.
- Always call
cmd.quit() at the end of every PyMOL script. Omitting it
causes the process to stop responding.
- Init boilerplate is mandatory. Every PyMOL script must begin with the
initialization sequence.
from pymol import cmd must come after
finish_launching(), not before.
- See references/PYMOL_REFERENCE.md for
selection syntax, common commands, and gotchas.
- Pre-Flight File Check: Before writing the PyMOL script or running it,
you MUST verify that the requested structure file actually exists on the
host machine.
- Verify Structure Load: After loading a structure with
cmd.load(),
always verify it succeeded by checking cmd.count_atoms("all"). If the
result is 0, print an error to stdout and call cmd.quit() immediately.
- Auto-detect Alpha-Carbon Trace: For a cartoon representation your
PyMOL scripts should automatically detect if the structure is an
alpha-carbon trace (
cmd.count_atoms("name CA") == cmd.count_atoms("all")),
then you MUST follow the Alpha carbon trace cartoon recipe.
- Notification: If this skill is used, ensure this is mentioned in the
output.
Quick Start
- Ensure structure files are downloaded to a directory in the user's project.
- Write a PyMOL Python script (e.g.,
render.py) with the required init
boilerplate and PEP 0723 header.
- Run it via
uv run: bash uv run render.py
Minimal example script (render.py)
# /// script
# requires-python = ">=3.10, <3.13"
# dependencies = [
# "pymol-open-source-whl",
# ]
# ///
import os
import sys
# Set environment variable for headless rendering
os.environ["PYOPENGL_PLATFORM"] = "osmesa"
import pymol # pytype: disable=import-error
pymol.pymol_argv = ["pymol", "-cq"]
pymol.finish_launching()
from pymol import cmd # pytype: disable=import-error
cmd.load("AF-P00520-F1-model_v4.cif", "structure")
cmd.show("cartoon")
cmd.color("green", "ss h")
cmd.color("yellow", "ss s")
cmd.color("gray", "ss l+''")
cmd.orient()
cmd.set("ray_opaque_background", 1)
cmd.png("output/render.png", width=1200, height=900, dpi=150)
cmd.save("output/session.pse")
cmd.quit()
Common Recipes
See references/RECIPES.md for complete, copy-paste
ready recipes. Available recipes:
- Cartoon with secondary structure coloring — basic helix/sheet/loop
coloring
- Alpha carbon trace cartoon — force cartoon representation for CA-only
structures
- B-factor (pLDDT) coloring — continuous spectrum coloring by B-factor
- AlphaFold pLDDT coloring — canonical threshold-based confidence colors
- Highlight specific residues — show active site or key residues as sticks
- Surface rendering — transparent surface over cartoon
- Electrostatic surface rendering — vacuum electrostatics (qualitative)
- Multi-chain complex colors — automatic per-chain coloring
- B-factor putty analysis — tube width proportional to flexibility
- Cavity and pocket visualization — surface cavity detection with ligand
focus
- Multi-structure batch rendering — render a directory of structures
- Measure distance between residues — CA–CA distance with labels
- Zoom into binding pocket — simple pocket focus
- Protein-ligand interaction — ligand isolation, styled rendering, polar
contacts
- Two-structure superposition with RMSD — align/cealign with auto-fallback
- In silico mutagenesis — mutate residues with the mutagenesis wizard
- Load and modify an existing session — re-open a
.pse file
Interpreting Output
- The
output/ directory contains PNG images and a .pse session file.
- Any measurements or metrics (distances, RMSD, atom counts) are printed to
stdout by the PyMOL script. Report these values to the user.
- Present PNG images to the user and describe the visualization.
- Tell the user they can open the
.pse file in their local PyMOL to further
explore, rotate, or modify the visualization.
- If the user wants modifications, load the saved
.pse in a new script and
re-run.
- Large sessions with surfaces can exceed the
--max_output_mb limit (default
500 MB). Increase it with --max_output_mb=1000 if needed.
1---
2name: pymol
3description: >
4 Visualize, analyze, and render protein and molecular structures using PyMOL.
5 Use when the user wants to create images of protein structures, perform
6 structural alignments or superposition, measure distances or contacts,
7 highlight binding sites or active site residues, color by B-factor/pLDDT,
8 or analyze protein-ligand interactions. Do not use for docking,
9 molecular dynamics, or sequence-only analysis.
10metadata:
11 source: https://skillmd.com/skills/google-deepmind/pymol
12---
13
14# PyMOL
15
16## Prerequisites
17
181. **`uv`**: Read the `uv` skill and follow its Setup instructions to ensure
19 `uv` is installed and on PATH.
202. **User Notification**: If .licenses/pymol_LICENSE.txt does not already exist
21 in the workspace root directory then (1) prominently notify the user to
22 check the license at https://www.pymol.org/, then (2) create the file
23 recording the notification text and timestamp.
24
25## Overview
26
27All PyMOL commands run on the host via `uv` with OSMesa software rendering — no
28GPU, display, or X server is needed. Structure files must be downloaded to the
29host before running PyMOL.
30
31**Do NOT use when:**
32
33- The user wants to run AlphaFold predictions.
34- The user wants docking or molecular dynamics simulations.
35- The user only has a sequence and no structure file — fetch the structure
36 first. Check if any other installed skills can retrieve structures from the
37 PDB or AlphaFold Database before proceeding.
38
39## Setup (Agent Instructions)
40
41Ensure that `uv` is installed on the host system. The PyMOL scripts use PEP 0723
42headers to declare their dependencies, and `uv run` will automatically handle
43installing them (including `pymol-open-source-whl`) when the script is executed.
44
45## Core Rules
46
47- **Output paths must be absolute or relative to the user's project root.**
48 Always run PyMOL scripts from the user's project directory.
49- **Software rendering only.** Use `cmd.png()` for output. Never use
50 `cmd.draw()` or `cmd.ray()` with hardware acceleration — OSMesa does not
51 support it. Set environment variable `PYOPENGL_PLATFORM=osmesa` for headless
52 rendering.
53- **Always save a `.pse` session file** alongside any PNG output. This lets
54 the user open the session in their local PyMOL for further inspection.
55- **Always call `cmd.quit()`** at the end of every PyMOL script. Omitting it
56 causes the process to stop responding.
57- **Init boilerplate is mandatory.** Every PyMOL script must begin with the
58 initialization sequence. `from pymol import cmd` must come after
59 `finish_launching()`, not before.
60- See [references/PYMOL_REFERENCE.md](references/PYMOL_REFERENCE.md) for
61 selection syntax, common commands, and gotchas.
62- **Pre-Flight File Check**: Before writing the PyMOL script or running it,
63 you MUST verify that the requested structure file actually exists on the
64 host machine.
65- **Verify Structure Load**: After loading a structure with `cmd.load()`,
66 always verify it succeeded by checking `cmd.count_atoms("all")`. If the
67 result is 0, print an error to stdout and call `cmd.quit()` immediately.
68- **Auto-detect Alpha-Carbon Trace**: For a **cartoon** representation your
69 PyMOL scripts should automatically detect if the structure is an
70 alpha-carbon trace (`cmd.count_atoms("name CA") == cmd.count_atoms("all")`),
71 then you MUST follow the **Alpha carbon trace cartoon** recipe.
72- **Notification**: If this skill is used, ensure this is mentioned in the
73 output.
74
75## Quick Start
76
77* Ensure structure files are downloaded to a directory in the user's project.
78* Write a PyMOL Python script (e.g., `render.py`) with the required init
79 boilerplate and PEP 0723 header.
80* Run it via `uv run`: `bash uv run render.py`
81
82### Minimal example script (`render.py`)
83
84```python
85# /// script
86# requires-python = ">=3.10, <3.13"
87# dependencies = [
88# "pymol-open-source-whl",
89# ]
90# ///
91
92import os
93import sys
94
95# Set environment variable for headless rendering
96os.environ["PYOPENGL_PLATFORM"] = "osmesa"
97
98import pymol # pytype: disable=import-error
99pymol.pymol_argv = ["pymol", "-cq"]
100pymol.finish_launching()
101
102from pymol import cmd # pytype: disable=import-error
103
104cmd.load("AF-P00520-F1-model_v4.cif", "structure")
105cmd.show("cartoon")
106cmd.color("green", "ss h")
107cmd.color("yellow", "ss s")
108cmd.color("gray", "ss l+''")
109cmd.orient()
110cmd.set("ray_opaque_background", 1)
111cmd.png("output/render.png", width=1200, height=900, dpi=150)
112cmd.save("output/session.pse")
113cmd.quit()
114```
115
116## Common Recipes
117
118See [references/RECIPES.md](references/RECIPES.md) for complete, copy-paste
119ready recipes. Available recipes:
120
121- **Cartoon with secondary structure coloring** — basic helix/sheet/loop
122 coloring
123- **Alpha carbon trace cartoon** — force cartoon representation for CA-only
124 structures
125- **B-factor (pLDDT) coloring** — continuous spectrum coloring by B-factor
126- **AlphaFold pLDDT coloring** — canonical threshold-based confidence colors
127- **Highlight specific residues** — show active site or key residues as sticks
128- **Surface rendering** — transparent surface over cartoon
129- **Electrostatic surface rendering** — vacuum electrostatics (qualitative)
130- **Multi-chain complex colors** — automatic per-chain coloring
131- **B-factor putty analysis** — tube width proportional to flexibility
132- **Cavity and pocket visualization** — surface cavity detection with ligand
133 focus
134- **Multi-structure batch rendering** — render a directory of structures
135- **Measure distance between residues** — CA–CA distance with labels
136- **Zoom into binding pocket** — simple pocket focus
137- **Protein-ligand interaction** — ligand isolation, styled rendering, polar
138 contacts
139- **Two-structure superposition with RMSD** — align/cealign with auto-fallback
140- **In silico mutagenesis** — mutate residues with the mutagenesis wizard
141- **Load and modify an existing session** — re-open a `.pse` file
142
143## Interpreting Output
144
145- The `output/` directory contains PNG images and a `.pse` session file.
146- Any measurements or metrics (distances, RMSD, atom counts) are printed to
147 stdout by the PyMOL script. Report these values to the user.
148- Present PNG images to the user and describe the visualization.
149- Tell the user they can open the `.pse` file in their local PyMOL to further
150 explore, rotate, or modify the visualization.
151- If the user wants modifications, load the saved `.pse` in a new script and
152 re-run.
153- Large sessions with surfaces can exceed the `--max_output_mb` limit (default
154 500 MB). Increase it with `--max_output_mb=1000` if needed.