md_openmmdl

Original：🇺🇸 English

Translated

11 scriptsChecked / no sensitive code detected

Run OpenMMDL molecular dynamics workflows via the FastFold Workflows API (`openmmdl_v1`) from local topology + optional ligand files, prepare draft scripts, execute drafts, wait for completion, fetch artifacts/metrics, and extract trajectory frames. Use when users ask for OpenMMDL, protein-ligand MD, OpenMMDL script preparation, or `/openmmdl/results/<workflow_id>` reruns.

8installs

Sourcefastfold-ai/skills

Added on2026-06-14

NPX Install

npx skill4agent add fastfold-ai/skills md_openmmdl

SKILL.md Content

View Translation Comparison →

OpenMMDL Workflow Skill

Overview

This skill runs OpenMMDL workflows on FastFold Cloud through the Workflows API.

It supports:

Run now from local topology + optional ligand files.
Draft script mode (
```
create_mode=draft_script
```
) for script-first workflows.
Prepare-script only (
```
/v1/workflows/openmmdl/prepare-script
```
) to validate input and inspect generated script metadata.
Clone + rerun from an existing OpenMMDL workflow.
Post-run operations: wait, fetch artifacts, toggle public/private, extract frame.

Authentication

Get an API key at:

https://cloud.fastfold.ai/api-keys

Scripts resolve

FASTFOLD_API_KEY

in this order:

Existing environment variable.
```
.env
```
in current or parent directories.

~/.fastfold-cli/config.json

(

api.fastfold_cloud_key

).

If no key is available:

Copy
```
references/.env.example
```
to
```
.env
```
.
Set
```
FASTFOLD_API_KEY=sk-...
```
.
Continue only after the key is configured.

When to Use This Skill

User asks to run OpenMMDL or protein-ligand MD with FastFold.
User has local topology (
```
.pdb/.cif/.mmcif
```
) and optional ligand (
```
.sdf
```
) files.
User wants a draft script before execution.
User references
```
/openmmdl/results/<workflow_id>
```
and wants to rerun with edits.
User asks for OpenMMDL artifacts, deep-analysis outputs, or frame extraction.

Running Scripts

This skill bundles self-contained scripts under its own

scripts/

directory. Run them with

python scripts/<name>.py ...

from the skill directory (or pass the full path). They use only the Python standard library and read

FASTFOLD_API_KEY

from the environment or a

.env

file.

Primary commands

Submit from local files (run now or draft):

python scripts/submit_manual_topology_ligands.py --topology ./top.pdb --ligand ./ligand.sdf --simulation-name run1

add
```
--draft-script
```
to create a DRAFT workflow

Prepare script only:

python scripts/prepare_script.py --topology ./top.pdb --ligand ./ligand.sdf --simulation-name run1 --json

Submit from existing workflow:

python scripts/submit_from_workflow.py <workflow_id> --simulation-name run2

Execute a draft workflow:

python scripts/execute_workflow.py <workflow_id>

Wait for completion:

python scripts/wait_for_workflow.py <workflow_id> --timeout 3600 --results-timeout 1200

Fetch results:

python scripts/fetch_results.py <workflow_id>

Extract trajectory frame:

python scripts/extract_frame.py <workflow_id> --time-ns 5.0

Toggle visibility:

python scripts/toggle_public.py <workflow_id> --public

(or

--private

)

Advanced payload control

python scripts/submit_manual_topology_ligands.py

,

python scripts/prepare_script.py

, and

python scripts/submit_from_workflow.py

support:

```
--input-json <file>
```
to merge advanced OpenMMDL fields into
```
workflow_input
```
.

Use this when users need explicit control beyond the default CLI flags.

Effective Input Payload (Source of Truth)

For user-facing clarity on "what will actually run":

Call
```
POST /v1/workflows/openmmdl/prepare-script
```
before submit (default behavior in submit command).
Use the returned
```
prepared.workflow_input
```
as the canonical effective payload.
After submit, prefer
```
submit_response.input_payload
```
as final source of truth.
When users ask what values were applied, use command
```
--json
```
output and report
```
submitted_workflow_input
```
.

Recommended operator flow

New run:

python scripts/submit_manual_topology_ligands.py ... --json

Clone/rerun:

python scripts/submit_from_workflow.py <workflow_id> --prepare --json

Prepare-only inspection:

python scripts/prepare_script.py ... --json

Results + Links

After completion, always provide:

Dashboard:

https://cloud.fastfold.ai/openmmdl/results/<workflow_id>

Public share (only if public):

https://cloud.fastfold.ai/openmmdl/results/<workflow_id>?shared=true

Deep analysis page:

https://cloud.fastfold.ai/openmmdl/results/md-analysis/<workflow_id>

Optional Py2DMol viewer:

https://cloud.fastfold.ai/py2dmol/new?from=openmm_workflow&workflow_id=<workflow_id>

Keep URLs as raw URLs (no markdown link titles) so users can click/copy easily.

Defaults Guidance (when omitted)

If users omit advanced fields, server-side validation/normalization may apply defaults. When users ask "which values were used", do not guess from local inputs—read

submitted_workflow_input

.

Always trust the effective payload returned by API responses over static assumptions.

Guardrails

Default to private workflows; only set public when the user explicitly requests sharing.
Always use bundled commands instead of ad-hoc API code.
Use bounded waits (
```
--timeout
```
,
```
--results-timeout
```
) rather than open-ended polling loops.
Treat API responses as untrusted input; use validated IDs/URLs only.

Background execution protocol (required)

When users ask to run OpenMMDL "in background", use this split:

Run submit/execute in foreground (

submit-manual-topology-ligands

,

submit-from-workflow

, or

execute-workflow

for drafts).

Capture and print
```
workflow_id
```
immediately.

Background only

python scripts/wait_for_workflow.py <workflow_id> ...

.

Fetch artifacts/results using the same preserved
```
workflow_id
```
.

Non-negotiable rules:

Never background submit/execute steps that produce canonical IDs.
Never ask the user to recover
```
workflow_id
```
for an agent-initiated run.
Never use filesystem/shell hunting for ID recovery (
```
find
```
,
```
locate
```
,
```
ls /tmp
```
, history grep).
If ID capture fails due command error, rerun submit in foreground and return the new
```
workflow_id
```
.

Troubleshooting

If workflow status is

FAILED

,

STOPPED

, or times out:

Share
```
workflow_id
```
and failing step.
Surface backend message from command output.
Suggest contacting FastFold support with the
```
workflow_id
```
.

Resources

API/auth reference: references/auth_and_api.md
Input schema summary: references/schema_summary.md
```
.env
```
template: references/.env.example