| name | examples-auto-run |
| description | Run Qubex examples in non-interactive auto mode, capture logs, and provide exact rerun commands. Use when validating notebooks or tutorial examples after code, docs, or dependency changes, especially for simulator and other offline examples; use the bundled script for execution, logging, and rerun-file generation instead of rebuilding the shell recipe by hand. |
Examples Auto Run
Overview
Execute example notebooks non-interactively when safe, keep logs, and avoid
hardware-backed notebooks unless the user explicitly wants them and the
environment is ready. Let the script handle notebook execution, per-notebook
logs, and rerun-file generation.
Workflow
- Classify examples before execution.
- Safe by default:
docs/examples/core/**, docs/examples/analysis/**,
docs/examples/pulse/**, docs/examples/simulator/**
- Conditional:
docs/examples/system/** only if required config files and
extras are present
- Do not auto-run by default: hardware-backed
docs/examples/experiment/**
and measurement or backend flows that require live instruments, backend
services, or private config
- Prepare a log directory.
- Store outputs under
.tmp/examples-auto-run/<timestamp>/
- Execute notebooks through the bundled script.
uv run python .agents/skills/examples-auto-run/scripts/run_notebooks_auto.py <selected-notebooks-or-directories> --logs-dir <log-dir> --write-rerun- Add
--timeout 600 or another explicit timeout when needed.
- If notebook execution tooling is unavailable, report the missing dependency instead of guessing.
- Capture failures usefully.
- Preserve stdout and stderr per notebook.
- Note the first failing cell and the exception summary.
- Report rerun helpers.
- Give the exact rerun command or rerun-file path written by the script for each failed notebook.
- Separate environment failures from real example regressions.
- Keep execution conservative.
- Prefer a representative set over every notebook if the change is narrow.
- Do not mutate checked-in notebooks unless the user explicitly asks for
output updates.
Bundled script
scripts/run_notebooks_auto.py
Use this script for deterministic execution mechanics:
- notebook discovery from file or directory inputs
- per-notebook stdout and stderr logs
- a main summary log
- a rerun shell script for failures
Keep model work focused on notebook selection and interpreting the resulting logs.
