SLURM Job Script Generator
Goal
Generate a correct, copy-pasteable SLURM job script (.sbatch) for running a simulation, and surface common configuration mistakes (bad walltime format, conflicting memory flags, oversubscription hints).
Requirements
- Python 3.10+
- No external dependencies (Python standard library only)
- Works on Linux, macOS, and Windows (script generation only)
Inputs to Gather
| Input |
Description |
Example |
| Job name |
Short identifier for the job |
phasefield-strong-scaling |
| Walltime |
SLURM time limit |
00:30:00 |
| Partition |
Cluster partition/queue (if required) |
compute |
| Account |
Project/account (if required) |
matsim |
| Nodes |
Number of nodes to allocate |
2 |
| MPI tasks |
Total tasks, or tasks per node |
128 or 64 per node |
| Threads |
CPUs per task (OpenMP threads) |
2 |
| Memory |
--mem or --mem-per-cpu (cluster policy dependent) |
32G |
| GPUs |
GPUs per node (optional) |
4 |
| Working directory |
Where the run should execute |
$SLURM_SUBMIT_DIR |
| Modules |
Environment modules to load (optional) |
gcc/12, openmpi/4.1 |
| Run command |
The command to launch under SLURM |
./simulate --config cfg.json |
Decision Guidance
MPI vs MPI+OpenMP layout
Does the code use OpenMP / threading?
├── NO → Use MPI-only: cpus-per-task=1
└── YES → Use hybrid: set cpus-per-task = threads per MPI rank
and export OMP_NUM_THREADS = cpus-per-task
Rule of thumb: if you see diminishing strong-scaling efficiency at high MPI ranks, try fewer ranks with more threads per rank (and measure).
Memory flag selection
- Use either
--mem (per node) or --mem-per-cpu (per CPU), not both.
- Follow your cluster’s documentation; some sites enforce one style.
- SLURM
--mem units are integer MB by default, or an integer with suffix K/M/G/T (and --mem=0 commonly means “all memory on node”).
Script Outputs (JSON Fields)
| Script |
Key Outputs |
scripts/slurm_script_generator.py |
results.script, results.directives, results.derived, results.warnings |
Workflow
- Gather cluster constraints (partition/account, GPU policy, memory policy).
- Choose a process layout (MPI-only vs hybrid MPI+OpenMP).
- Generate the script with
slurm_script_generator.py.
- Inspect warnings (conflicts, suspicious layouts).
- Save the generated script as
job.sbatch.
- Submit with
sbatch job.sbatch and monitor with squeue.
CLI Examples
# Preview a job script (prints to stdout)
python3 skills/hpc-deployment/slurm-job-script-generator/scripts/slurm_script_generator.py \
--job-name phasefield \
--time 00:10:00 \
--partition compute \
--nodes 1 \
--ntasks-per-node 8 \
--cpus-per-task 2 \
--mem 16G \
--module gcc/12 \
--module openmpi/4.1 \
-- \
./simulate --config config.json
# Write to a file and also emit structured JSON
python3 skills/hpc-deployment/slurm-job-script-generator/scripts/slurm_script_generator.py \
--job-name phasefield \
--time 00:10:00 \
--nodes 1 \
--ntasks 16 \
--cpus-per-task 1 \
--out job.sbatch \
--json \
-- \
/bin/echo hello
Conversational Workflow Example
User: I need an sbatch script for my MPI simulation. I want 2 nodes, 64 ranks per node, 2 OpenMP threads per rank, and 2 hours.
Agent workflow:
- Confirm partition/account and whether GPUs are needed.
- Generate a hybrid job script:
python3 scripts/slurm_script_generator.py --job-name run --time 02:00:00 --nodes 2 --ntasks-per-node 64 --cpus-per-task 2 -- -- ./simulate
- Explain the mapping:
- Total ranks = 128
- Threads per rank = 2 (
OMP_NUM_THREADS=2)
- If the user provides node core counts, sanity-check oversubscription using
--cores-per-node.
Error Handling
| Error |
Cause |
Resolution |
time must be HH:MM:SS or D-HH:MM:SS |
Bad walltime format |
Use 00:30:00 or 1-00:00:00 |
nodes must be positive |
Non-positive nodes |
Provide --nodes >= 1 |
Provide either --mem or --mem-per-cpu, not both |
Conflicting memory directives |
Choose one memory style |
Provide a run command after -- |
Missing launch command |
Add -- ./simulate ... |
Security
Input Validation
--time is validated against strict HH:MM:SS or D-HH:MM:SS format via regex
--nodes, --ntasks, --ntasks-per-node, --cpus-per-task, --gpus are validated as positive integers with upper bounds
--mem and --mem-per-cpu are validated against SLURM's accepted format (<int>[K|M|G|T]); providing both simultaneously is rejected
--job-name is validated against [a-zA-Z0-9_.-]+ (no shell metacharacters)
--partition and --account are validated against safe-character allowlists
--module values are validated to prevent shell injection (no ;, |, &, backticks, or $)
File Access
- The script reads no external files; all inputs are provided via CLI arguments
--out writes the generated sbatch script to a single specified file path
- The generated script is a plain-text shell script with
#SBATCH directives; it contains no dynamically generated code
Tool Restrictions
- Read: Used to inspect script source, references, and existing job scripts
- Bash: Used to execute
slurm_script_generator.py with explicit argument lists; the generated script itself is NOT executed by the agent
- Write: Used to save the generated
.sbatch file; writes are scoped to the user's working directory
- Grep/Glob: Used to locate existing scripts, configs, and cluster documentation
Safety Measures
- No
eval(), exec(), or dynamic code generation
- All subprocess calls use explicit argument lists (no
shell=True)
- The run command (after
--) is included verbatim in the generated script but is never executed by the skill itself
- Module names are sanitized to prevent injection into
module load directives
- Generated scripts use
set -euo pipefail for safe shell execution on the cluster
Limitations
- Does not query cluster hardware or site policies; it can only validate internal consistency.
- SLURM installations vary (GPU directives, QoS rules, partitions). Adjust directives for your site.
References
references/slurm_directives.md - Common #SBATCH directives and mapping tips
Version History
- v1.0.0 (2026-02-25): Initial SLURM job script generator
1---2name: slurm-job-script-generator3description: >4 Generate correct, copy-pasteable SLURM sbatch job scripts and sanity-check5 HPC resource requests — configure nodes, MPI tasks, OpenMP threads, memory6 (per-node or per-cpu), GPUs, walltime, partitions, modules, and environment7 variables, with automatic detection of conflicting directives and8 oversubscription. Use when preparing a SLURM submission script, deciding9 between pure MPI and hybrid MPI+OpenMP layouts, standardizing #SBATCH10 directives across a team, debugging why a job won't launch or gets killed,11 or setting up GPU-accelerated simulation jobs, even if the user only says12 "I need to run this on the cluster" or "my job keeps getting killed."13allowed-tools: Read, Bash, Write, Grep, Glob14metadata:15 source: https://skillmd.com/skills/zuoguyoupan2023/slurm-job-script-generator16 author: HeshamFS17 version: "1.1.0"18 security_tier: high19 security_reviewed: true20 tested_with:21 - claude-code22 - gemini-cli23 - vs-code-copilot24 eval_cases: 525 last_reviewed: "2026-03-26"26---2728# SLURM Job Script Generator2930## Goal3132Generate a correct, copy-pasteable SLURM job script (`.sbatch`) for running a simulation, and surface common configuration mistakes (bad walltime format, conflicting memory flags, oversubscription hints).3334## Requirements3536- Python 3.10+37- No external dependencies (Python standard library only)38- Works on Linux, macOS, and Windows (script generation only)3940## Inputs to Gather4142| Input | Description | Example |43|-------|-------------|---------|44| Job name | Short identifier for the job | `phasefield-strong-scaling` |45| Walltime | SLURM time limit | `00:30:00` |46| Partition | Cluster partition/queue (if required) | `compute` |47| Account | Project/account (if required) | `matsim` |48| Nodes | Number of nodes to allocate | `2` |49| MPI tasks | Total tasks, or tasks per node | `128` or `64` per node |50| Threads | CPUs per task (OpenMP threads) | `2` |51| Memory | `--mem` or `--mem-per-cpu` (cluster policy dependent) | `32G` |52| GPUs | GPUs per node (optional) | `4` |53| Working directory | Where the run should execute | `$SLURM_SUBMIT_DIR` |54| Modules | Environment modules to load (optional) | `gcc/12`, `openmpi/4.1` |55| Run command | The command to launch under SLURM | `./simulate --config cfg.json` |5657## Decision Guidance5859### MPI vs MPI+OpenMP layout6061```62Does the code use OpenMP / threading?63├── NO → Use MPI-only: cpus-per-task=164└── YES → Use hybrid: set cpus-per-task = threads per MPI rank65 and export OMP_NUM_THREADS = cpus-per-task66```6768**Rule of thumb:** if you see diminishing strong-scaling efficiency at high MPI ranks, try fewer ranks with more threads per rank (and measure).6970### Memory flag selection7172- Use **either** `--mem` (per node) **or** `--mem-per-cpu` (per CPU), not both.73- Follow your cluster’s documentation; some sites enforce one style.74- SLURM `--mem` units are integer MB by default, or an integer with suffix `K/M/G/T` (and `--mem=0` commonly means “all memory on node”).7576## Script Outputs (JSON Fields)7778| Script | Key Outputs |79|--------|-------------|80| `scripts/slurm_script_generator.py` | `results.script`, `results.directives`, `results.derived`, `results.warnings` |8182## Workflow83841. Gather cluster constraints (partition/account, GPU policy, memory policy).852. Choose a process layout (MPI-only vs hybrid MPI+OpenMP).863. Generate the script with `slurm_script_generator.py`.874. Inspect warnings (conflicts, suspicious layouts).885. Save the generated script as `job.sbatch`.896. Submit with `sbatch job.sbatch` and monitor with `squeue`.9091## CLI Examples9293```bash94# Preview a job script (prints to stdout)95python3 skills/hpc-deployment/slurm-job-script-generator/scripts/slurm_script_generator.py \96 --job-name phasefield \97 --time 00:10:00 \98 --partition compute \99 --nodes 1 \100 --ntasks-per-node 8 \101 --cpus-per-task 2 \102 --mem 16G \103 --module gcc/12 \104 --module openmpi/4.1 \105 -- \106 ./simulate --config config.json107108# Write to a file and also emit structured JSON109python3 skills/hpc-deployment/slurm-job-script-generator/scripts/slurm_script_generator.py \110 --job-name phasefield \111 --time 00:10:00 \112 --nodes 1 \113 --ntasks 16 \114 --cpus-per-task 1 \115 --out job.sbatch \116 --json \117 -- \118 /bin/echo hello119```120121## Conversational Workflow Example122123**User**: I need an `sbatch` script for my MPI simulation. I want 2 nodes, 64 ranks per node, 2 OpenMP threads per rank, and 2 hours.124125**Agent workflow**:1261. Confirm partition/account and whether GPUs are needed.1272. Generate a hybrid job script:128 ```bash129 python3 scripts/slurm_script_generator.py --job-name run --time 02:00:00 --nodes 2 --ntasks-per-node 64 --cpus-per-task 2 -- -- ./simulate130 ```1313. Explain the mapping:132 - Total ranks = 128133 - Threads per rank = 2 (`OMP_NUM_THREADS=2`)1344. If the user provides node core counts, sanity-check oversubscription using `--cores-per-node`.135136## Error Handling137138| Error | Cause | Resolution |139|-------|-------|------------|140| `time must be HH:MM:SS or D-HH:MM:SS` | Bad walltime format | Use `00:30:00` or `1-00:00:00` |141| `nodes must be positive` | Non-positive nodes | Provide `--nodes >= 1` |142| `Provide either --mem or --mem-per-cpu, not both` | Conflicting memory directives | Choose one memory style |143| `Provide a run command after --` | Missing launch command | Add `-- ./simulate ...` |144145## Security146147### Input Validation148- `--time` is validated against strict `HH:MM:SS` or `D-HH:MM:SS` format via regex149- `--nodes`, `--ntasks`, `--ntasks-per-node`, `--cpus-per-task`, `--gpus` are validated as positive integers with upper bounds150- `--mem` and `--mem-per-cpu` are validated against SLURM's accepted format (`<int>[K|M|G|T]`); providing both simultaneously is rejected151- `--job-name` is validated against `[a-zA-Z0-9_.-]+` (no shell metacharacters)152- `--partition` and `--account` are validated against safe-character allowlists153- `--module` values are validated to prevent shell injection (no `;`, `|`, `&`, backticks, or `$`)154155### File Access156- The script reads no external files; all inputs are provided via CLI arguments157- `--out` writes the generated sbatch script to a single specified file path158- The generated script is a plain-text shell script with `#SBATCH` directives; it contains no dynamically generated code159160### Tool Restrictions161- **Read**: Used to inspect script source, references, and existing job scripts162- **Bash**: Used to execute `slurm_script_generator.py` with explicit argument lists; the generated script itself is NOT executed by the agent163- **Write**: Used to save the generated `.sbatch` file; writes are scoped to the user's working directory164- **Grep/Glob**: Used to locate existing scripts, configs, and cluster documentation165166### Safety Measures167- No `eval()`, `exec()`, or dynamic code generation168- All subprocess calls use explicit argument lists (no `shell=True`)169- The run command (after `--`) is included verbatim in the generated script but is never executed by the skill itself170- Module names are sanitized to prevent injection into `module load` directives171- Generated scripts use `set -euo pipefail` for safe shell execution on the cluster172173## Limitations174175- Does not query cluster hardware or site policies; it can only validate internal consistency.176- SLURM installations vary (GPU directives, QoS rules, partitions). Adjust directives for your site.177178## References179180- `references/slurm_directives.md` - Common `#SBATCH` directives and mapping tips181182## Version History183184- **v1.0.0** (2026-02-25): Initial SLURM job script generator