Author, run, and convert reproducible marimo and Jupyter notebooks with embedded figures and validated environments.
- GitHub stars
- 11
- Files
- 13
- Last commit
- Nov 11, 2026
- License
- MIT
- Allowed tools
- —
What does the notebooks skill do?
notebooks is an agent skill. Author, run, and convert reproducible marimo and Jupyter notebooks with embedded figures and validated environments.
Summary generated from the skill's SKILL.md.
About the notebooks skill
Creating and delivering reproducible data analysis notebooks is the primary function of this skill. It allows developers to author, validate, and execute notebooks in either marimo or Jupyter formats, ensuring that every figure is embedded and the environment is fully reproducible. When an agent needs to provide a completed analysis, it uses this skill to run notebooks end-to-end on fresh kernels, producing either a pre-executed .ipynb file or a standalone HTML artifact.
The skill manages environment dependencies through PEP 723 headers for marimo users via uvx or through pixi environments for Jupyter users. It includes specialized tools for converting between formats using a dedicated conversion script and provides strict quality gates to check for malformed markdown or empty cells. By enforcing project-relative data paths and specific kernel pinning, it prevents the common issue of notebooks failing when moved to different machines.
What an agent can do with it
- 1Generate reproducible HTML reportsExport a marimo notebook into a deterministic HTML file that includes all embedded figures.
- 2Validate notebook execution qualityRun a strict check on a marimo notebook to ensure there are no empty cells or malformed markdown strings.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the notebooks skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the notebooks skill in Plugin
/plugin marketplace add fmschulz/omics-skills /plugin install omics-skills@omics-skills
Install the notebooks skill in Claude Code
~/.claude/skills/notebooks/SKILL.md
$ npx degit fmschulz/omics-skills/skills/notebooks ~/.claude/skills/notebooksInstall the notebooks skill in Claude Code (project)
.claude/skills/notebooks/SKILL.md
$ npx degit fmschulz/omics-skills/skills/notebooks .claude/skills/notebooksInstall the notebooks skill in Codex
~/.agents/skills/notebooks/SKILL.md
$ npx degit fmschulz/omics-skills/skills/notebooks ~/.agents/skills/notebooksInstall the notebooks skill in Gemini CLI
~/.gemini/skills/notebooks/SKILL.md
$ npx degit fmschulz/omics-skills/skills/notebooks ~/.gemini/skills/notebooksInstall the notebooks skill in Claude.ai
npx degit fmschulz/omics-skills/skills/notebooks notebooks && zip -r notebooks.zip notebooks # claude.ai → Customize → Skills → + → Create skill → Upload a skill → notebooks.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablefmschulz/omics-skills/skills/notebooks is public and reachablegithub.com/fmschulz/omics-skills/tree/HEAD/skills/notebooks ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-11github.com/fmschulz/omics-skills/commits ↗Pass
- No download-and-run or credential theft in scripts3 scripts read; no download-and-run, remote eval, base64 execution or credential uploadPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/fmschulz/omics-skills/blob/HEAD/skills/notebooks/ ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/fmschulz/omics-skills/blob/HEAD/skills/notebooks/ ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 116 linesgithub.com/fmschulz/omics-skills/blob/HEAD/skills/notebooks/ ↗Pass
SKILL.md
View on GitHubNotebooks
Author, validate and deliver reproducible analysis notebooks in marimo or Jupyter, and convert between the two. Installed at ~/.agents/skills/notebooks; set NOTEBOOKS_SKILL="${NOTEBOOKS_SKILL:-$HOME/.agents/skills/notebooks}" for the helper scripts.
A notebook is not "done" until it has been executed end to end on a fresh kernel and every figure is embedded in the delivered file.
Instructions
-
Pick the format. Marimo is the default for a new standalone notebook. Use Jupyter when the project's record format is Jupyter (for example a bester project record) or the project already uses
.ipynb; keep an existing.ipynbas Jupyter unless the user asks to convert.- Marimo layout: one concept per cell, final expression renders, no
ifguards around outputs, notry/exceptfor control flow.
- Marimo layout: one concept per cell, final expression renders, no
-
Outline before coding. Write the notebook plan (purpose, data sources, analysis steps, expected outputs/plots) as the first markdown cell, then implement against that plan.
-
Keep marimo cells clean. These are hard rules for every
.pynotebook:- Markdown cells use one plain triple-quoted string:
mo.md(r"""...""")ormo.md(f"""...""")only when interpolation is required. Put the prose directly inside the string; never paste quoted string fragments such as" ... "lines inside the markdown body. - Do not leave empty generated cells, whitespace-only cells, or
@app.cell def _(): returnplaceholders. Remove them before final verification. - Do not accept a marimo "fix" prompt blindly. If one is accepted during interactive editing, inspect the diff immediately and remove unintended PEP 723/header/cell churn.
- Markdown cells use one plain triple-quoted string:
-
Set up the kernel and dependencies.
- Marimo. Pin dependencies in the PEP 723 script header at the top of the
.pyfile:
Run with# /// script # requires-python = ">=3.12" # dependencies = [ # "marimo", # "polars", # "duckdb", # "matplotlib", # # ... add every import used in the notebook # ] # ///uvx marimo run --sandbox <notebook.py>or edit interactively withuvx marimo edit --sandbox <notebook.py>. The sandbox reads the header and resolves the notebook environment. - Jupyter. Register a named ipykernel for the project's pixi env before the first execution and pin the kernel in the notebook metadata. The kernel name is mandatory: the generic
python3kernel leaks the system interpreter.
Then inpixi run python -m ipykernel install --user --name <project> --display-name "<project> (pixi)"<notebook>.ipynbconfirm:
Add every import used in the notebook to"kernelspec": {"name": "<project>", "display_name": "<project> (pixi)"}pixi.tomlso the kernel can resolve it from a clean install.
- Marimo. Pin dependencies in the PEP 723 script header at the top of the
-
Load data with project-relative paths. Prefer DuckDB for TSV/Parquet (
duckdb.read_csv,duckdb.read_parquet). Avoid absolute paths and~. Avoid hidden state from the runtime working directory. -
Run checks and all cells to generate plots. Execute the notebook headlessly on a fresh kernel before delivery:
- Marimo: run
uvx marimo check --strict <notebook.py>before export. Then runuvx marimo export ipynb <notebook.py> -o <notebook.executed.ipynb> --include-outputs --sandbox -f. For a deterministic HTML artifact, useuvx marimo export html <notebook.py> -o <notebook.html> --sandbox -f. Run the strict check again after the final edit/export cycle. - Jupyter: run the self-provisioning helper:
The helper writesuv run --script "$NOTEBOOKS_SKILL/scripts/execute_notebook.py" \ <notebook.ipynb> --kernel <project><notebook>.executed.ipynband sets its kernelspec name to the--kernelvalue. Without--kernelit uses the notebook's own kernelspec, elsepython3.pixi run jupyter nbconvert --to notebook --execute --inplace <notebook.ipynb>is also valid when Jupyter is declared in the project environment.
- Marimo: run
-
Evaluate the plots, then refine. This step is required. Figures follow
/beautiful-data-viz; references/plot_style.md has the notebook style cell. After the run-all execution:- Open the executed notebook (or exported HTML) and inspect every figure.
- Check for: empty axes, mis-scaled axes (log versus linear), missing labels or legends, overlapping ticks, illegible fonts at target size, colour that encodes nothing, colourbars without units, NaN-driven gaps, ranges that clip data, broken layouts.
- If a figure is wrong or unclear, edit the source cell and re-run end to end. Record revisions in a brief "Figure revision log" markdown cell or in the run log.
-
Deliver pre-executed notebooks. The delivered artifact has every cell executed against the registered kernel, every figure embedded (PNG or SVG cell outputs in the
.ipynb, or the marimo HTML export), re-run instructions in the header or README, and seeds set where results are random. It must reproduce end to end from a clean clone: a new environment built from the PEP 723 header (marimo) orpixi installplusjupyter nbconvert --to notebook --execute(Jupyter). No delivered notebook keeps the literal<PIXI_PROJECT_KERNEL>placeholder. -
Convert between marimo and Jupyter when the user asks for it:
- Use
scripts/convert_notebook.pyfor a pinned conversion path. The fixtures underfixtures/exercise both directions. Replace<PROJECT_NAME>and<PIXI_PROJECT_KERNEL>in copied Jupyter templates with the actual Pixi kernel before execution. .ipynb→ marimo.py:uvx marimo convert <notebook.ipynb> -o <notebook.py>, thenuvx marimo check --strict <notebook.py>, then clean up Jupyter artifacts (display()calls,%magics, indented final expressions, ipywidget usage). Seereferences/widgets.mdandreferences/latex.mdfor ipywidget→marimo and MathJax→KaTeX mappings.- marimo
.py→.ipynb:uvx marimo export ipynb <notebook.py> -o <notebook.ipynb> --include-outputs --sandbox -f. - After conversion, re-run step 6 (check/execute), step 7 (inspect plots), and step 8 (deliver pre-executed).
- Use
-
References. Marimo:
references/notebook_structure.md,UI.md,STATE.md,EXPORTS.md. For testing, SQL cells, top-level imports and deployment, see the marimo documentation at https://docs.marimo.io/. Conversion:references/widgets.md,references/latex.md. Pixi and Jupyter:references/pixi_jupyter.md. DuckDB loading:references/data_loading_duckdb.md. Templates (start a new notebook from one):templates/marimo_notebook_template.py,templates/jupyter_kiss_template.py. Jupyter structure linter:uv run --script "$NOTEBOOKS_SKILL/scripts/lint_notebook_structure.py" <notebook.ipynb>.
Input Requirements
Notebook scope (question, data, outputs) and data paths (TSV or Parquet preferred). Marimo needs uv; Jupyter needs pixi and a pixi.toml.
Output
A notebook (.py for marimo, .ipynb for Jupyter) with narrative cells, code and embedded figures, plus a pre-executed copy (<notebook>.executed.ipynb or an .html export).
Quality Gates
uvx marimo check --strict <notebook.py>passes before and after export, and no malformed markdown cells, quoted-string fragments insidemo.md(...), orreturn-only placeholder cells remain.- Every import is declared in the PEP 723 header or
pixi.toml; template dependencies use bounded versions. - Data paths are project-relative and verified to exist.
- Both conversion directions pass the fixture gate.
Troubleshooting
Issue: Jupyter notebook executes locally but fails on a teammate's machine.
Solution: The kernel was unpinned (python3) or used a packaged interpreter outside the project's pixi env. Re-register a named kernel and pin it in the notebook kernelspec.
Issue: Marimo cell does not render a figure.
Solution: The figure must be the final expression of the cell. Indented expressions inside if blocks or expressions buried before other statements will not render.
Issue: Figures look correct interactively but the executed file shows empty plots.
Solution: Code is mutating shared state across cells (e.g. plt.gcf() reuse). Build a fresh figure per cell (in marimo _fig, _ax = plt.subplots(...), because a global fig defined in two cells is an error) and make the figure the final expression.
Issue: Converted notebook fails marimo check.
Solution: Remove leftover display(...) calls, drop %magic lines that have no marimo equivalent, and rewrite ipywidget usage using mo.ui.* per references/widgets.md.
Issue: Every matplotlib figure appears twice in the executed Jupyter notebook.
Solution: The inline backend's flush_figures post-execute hook auto-displays every open figure (display_data), and the cell's fig return value produces a second copy (execute_result). Unregister the hook in the preamble cell:
plt.ioff()
try:
from matplotlib_inline.backend_inline import flush_figures
get_ipython().events.unregister("post_execute", flush_figures)
except Exception:
pass
With this fix, only the cell's final fig expression renders. For figures inside if/else blocks (where fig is not a top-level expression and therefore not captured as execute_result), use display(fig) explicitly instead of bare fig. Do not use mpl.use("agg") as a workaround; it disables _repr_png_() entirely and produces zero images.
Files in this skill
13notebooks skill questions
How do I install the notebooks skill in Claude Code?
Run npx degit fmschulz/omics-skills/skills/notebooks ~/.claude/skills/notebooks. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the notebooks skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What should I do if Jupyter notebooks fail on other machines?
This usually happens because the kernel was not pinned. You should register a named ipykernel for the project's environment and pin that kernel name in the notebook metadata.