OpenSciFlow Skill

OpenSciFlow Skill teaches AI agents to inspect verified execution capsules, check environment readiness, select reviewed command templates, run smoke tests when available, execute only after approval, and write run records.

中文定位：

OpenSciFlow Skill 让 Agent 学会读取 verified execution capsule，检查环境就绪状态，选择审阅过的命令模板，先运行 smoke test，再在用户确认后执行，并写入 run record。

This repository is an early draft. It is meant for correction, not for claiming a mature agent ecosystem.

Why This Exists

AI for Science already has many strong tools and models, but successful runs are often hard to transfer across agents, users, machines, and workflows. Environment setup, CUDA versions, model weights, file paths, HPC modules, Slurm assumptions, licenses, citations, and known failure modes are rarely captured in one reusable execution unit.

OpenSciFlow Skill does not make scientific tools run everywhere.

It helps agents follow a stricter loop:

inspect capsule
-> check requirements and known failures
-> run smoke test when available
-> render reviewed command template
-> ask for approval
-> execute
-> write run record

Core principle:

OpenSciFlow does not eliminate scientific computing failures. It makes them explicit, checkable, diagnosable, and recordable.

What This Is

• A skill specification for AI agents.
• A safety layer for agentic scientific tool execution.
• A way to use verified execution capsules.
• A check-before-run and record-after-run protocol.
• A set of prompt templates, schemas, refusal rules, and structured examples.

What This Is Not

• Not a universal AI Scientist.
• Not a guarantee that tools run across all environments.
• Not a replacement for Docker, Conda, Apptainer, Slurm, Nextflow, Snakemake, or package managers.
• Not merely a README-to-YAML summarizer.
• Not permission for agents to execute arbitrary shell commands.
• Not a mature ecosystem or standard body.
• Not a claim of partnership with any listed project.

Safety Rules

• Never execute arbitrary shell commands generated by the LLM.
• Only render reviewed command templates declared in the capsule.
• Always check environment requirements before execution.
• Always run smoke tests when available.
• Always write a run record.
• Always report known failure cases.
• Always fail closed when required metadata is missing.
• Do not claim reproducibility beyond the verified environment matrix.

Repository Contents

• skill.md: agent-readable skill instructions.
• skill.json: machine-readable skill metadata.
• docs/: design notes, adoption guides, safety policy, evaluation plan.
• schemas/: JSON Schemas for skill inputs, outputs, workflow plans, execution requests, and run records.
• prompts/: prompt templates for planner, capsule reader, workflow matcher, safety checker, command renderer, and run-record writer.
• examples/: mock but structured examples for GROMACS RMSD, Slurm/GROMACS RMSD, Slurm/MACE evaluation, DiffDock docking, and Boltz structure prediction.
• scripts/: minimal schema validators.
• tests/: schema validation and refusal-case tests.

Key Drafts

• docs/schema-mapping.md: how skill input, workflow planning, execution requests, and run records connect.
• docs/run-record-alignment.md: how BioPilot run manifests project into Skill run records.
• docs/coding-agent-behavior-review.md: review of skill.md against realistic coding-agent behavior.
• docs/slurm-workflow-alignment.md: cross-checks for Slurm workflow, execution request, wrapper, and run-record examples.
• docs/wrapper-review-checklist.md: when wrapper scripts are allowed and when they must be refused.
• docs/hpc-slurm-notes.md: site-specific questions an agent must not invent.
• docs/refusal-policy.md: normal fail-closed outcomes.

Related OpenSciFlow Repositories

• Verified capsules: https://github.com/OpenSciFlow/verified-capsules
• Plugin manifests: https://github.com/OpenSciFlow/plugin-manifest
• Workflow templates: https://github.com/OpenSciFlow/workflow-templates
• Landscape map: https://github.com/OpenSciFlow/awesome-ai4s-workflows
• BioPilot prototype: https://github.com/OpenSciFlow/biopilot-prototype
• Community: https://github.com/OpenSciFlow/community
• White paper: https://github.com/OpenSciFlow/whitepaper
• Documentation: https://github.com/OpenSciFlow/docs

Validation

Install the small validation dependencies:

python -m pip install jsonschema pyyaml pytest

Validate example fixtures:

python scripts/validate_skill_input.py tests/fixtures/valid_skill_input.json
python scripts/validate_skill_output.py examples/gromacs-rmsd/skill-output.example.json
python scripts/validate_execution_request.py examples/slurm-gromacs-rmsd/execution-request.json
python scripts/validate_run_record.py tests/fixtures/valid_run_record.json
python scripts/validate_run_record_crosswalk.py
python scripts/validate_slurm_workflow_alignment.py

Run tests:

python -m pytest

How To Contribute

Good first contributions:

• Review capsule fields.
• Review skill behavior.
• Add refusal cases.
• Add HPC / Slurm missing cases.
• Add examples for scientific tools.
• Correct citations or licenses.
• Report unsafe execution assumptions.

Keep changes small, sourced, and correction-first.