Agent skill

Marimo Notebook

by cosanlab in cosanlab/nltools

Write a marimo notebook in a Python file in the right format.

MITAuto-check passedData & Analytics

Install Marimo Notebook

skills CLI
$ npx skills add cosanlab/nltools --skill marimo-notebook -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install cosanlab/nltools marimo-notebook --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/cosanlab/nltools.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/marimo-notebook .claude/skills/marimo-notebook && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
marimo-notebook
GitHub stars
131
Used in
4 other repos
Token cost
~2.1k tokens
SKILL.md length
589 words
Files
13 (incl. references)
Skills in repo
3
Repo updated
First seen
Licence
MIT

At a glance

Write a marimo notebook in a Python file in the right format.

  • Tasks that involve Jupyter notebooks
  • SKILL.md covers Running Marimo Notebooks, Script Mode Detection, Key Principle: Keep It Simple and State and Reactivity, plus 8 more sections
  • Calls uv, uvx and pytest

What it does

Marimo Notebook is an agent skill from cosanlab/nltools. Write a marimo notebook in a Python file in the right format.

Its SKILL.md is about 2.1k tokens, which your agent loads only when the skill is triggered. The skill folder holds 13 other files, including reference files (for example `references/ANYWIDGET.md`, `references/CONFIGURATION.md` and `references/DEPLOYMENT.md`).

It sits in Data & Analytics, covering Jupyter notebooks. It works with marimo and Python. The repository describes itself as: Python toolbox for analyzing imaging data. The licence is MIT.

When your agent uses it

  • Tasks that involve Jupyter notebooks

Example prompts

  • “/marimo-notebook”

Requirements

  • Python 3

What it can do on your machine

Read from SKILL.md and the folder at commit cf366c2. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • uv
    • uvx
    • pytest

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use uv and uvx, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Marimo Notebook loads about 2.1k tokens when it runs, and up to ~9.3k if it reads all its reference files. Until then it costs about 19 tokens; SKILL.md has 589 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~19
When it runs · the whole SKILL.md, loaded when a task matches
~2.1k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~9.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from cosanlab/nltools at commit cf366c2, republished under its MIT licence (© cosanlab). 589 words, ~2,065 tokens.

Download SKILL.mdSave it as .claude/skills/marimo-notebook/SKILL.md (or your agent's skills folder). This skill also uses 12 other files; get the full folder from GitHub.
name
marimo-notebook
description
Write a marimo notebook in a Python file in the right format.

Notes for marimo Notebooks

marimo uses Python to create notebooks, unlike Jupyter which uses JSON. Here's an example notebook:

python
# /// script
# dependencies = [
#     "marimo",
#     "numpy==2.4.3",
# ]
# requires-python = ">=3.14"
# ///

import marimo

__generated_with = "0.20.4"
app = marimo.App(width="medium")


@app.cell
def _():
    import marimo as mo
    import numpy as np

    return mo, np


@app.cell
def _():
    print("hello world")
    return


@app.cell
def _(np, slider):
    np.array([1,2,3]) + slider.value
    return


@app.cell
def _(mo):
    slider = mo.ui.slider(1, 10, 1, label="number to add")
    slider
    return (slider,)


@app.cell
def _():
    return


if __name__ == "__main__":
    app.run()

Notice how the notebook is structured with functions can represent cell contents. Each cell is defined with the @app.cell decorator and the inputs/outputs of the function are the inputs/outputs of the cell. marimo usually takes care of the dependencies between cells automatically.

Running Marimo Notebooks

bash
# Run as script (non-interactive, for testing)
uv run <notebook.py>

# Run interactively in browser
uv run marimo run <notebook.py>

# Edit interactively
uv run marimo edit <notebook.py>

Script Mode Detection

Use mo.app_meta().mode == "script" to detect CLI vs interactive:

python
@app.cell
def _(mo):
    is_script_mode = mo.app_meta().mode == "script"
    return (is_script_mode,)

Key Principle: Keep It Simple

Show all UI elements always. Only change the data source in script mode.

  • Sliders, buttons, widgets should always be created and displayed
  • In script mode, just use synthetic/default data instead of waiting for user input
  • Don't wrap everything in if not is_script_mode conditionals
  • Don't use try/except for normal control flow
Good Pattern
python
# Always show the widget
@app.cell
def _(ScatterWidget, mo):
    scatter_widget = mo.ui.anywidget(ScatterWidget())
    scatter_widget
    return (scatter_widget,)

# Only change data source based on mode
@app.cell
def _(is_script_mode, make_moons, scatter_widget, np, torch):
    if is_script_mode:
        # Use synthetic data for testing
        X, y = make_moons(n_samples=200, noise=0.2)
        X_data = torch.tensor(X, dtype=torch.float32)
        y_data = torch.tensor(y)
        data_error = None
    else:
        # Use widget data in interactive mode
        X, y = scatter_widget.widget.data_as_X_y
        # ... process data ...
    return X_data, y_data, data_error

# Always show sliders - use their .value in both modes
@app.cell
def _(mo):
    lr_slider = mo.ui.slider(start=0.001, stop=0.1, value=0.01)
    lr_slider
    return (lr_slider,)

# Auto-run in script mode, wait for button in interactive
@app.cell
def _(is_script_mode, train_button, lr_slider, run_training, X_data, y_data):
    if is_script_mode:
        # Auto-run with slider defaults
        results = run_training(X_data, y_data, lr=lr_slider.value)
    else:
        # Wait for button click
        if train_button.value:
            results = run_training(X_data, y_data, lr=lr_slider.value)
    return (results,)

State and Reactivity

Variables between cells define the reactivity of the notebook for 99% of the use-cases out there. No special state management needed. Don't mutate objects across cells (e.g., my_list.append()); create new objects instead. Avoid mo.state() unless you need bidirectional UI sync or accumulated callback state. See STATE.md for details.

Don't Guard Cells with if Statements

Marimo's reactivity means cells only run when their dependencies are ready. Don't add unnecessary guards:

python
# BAD - the if statement prevents the chart from showing
@app.cell
def _(plt, training_results):
    if training_results:  # WRONG - don't do this
        fig, ax = plt.subplots()
        ax.plot(training_results['losses'])
        fig
    return

# GOOD - let marimo handle the dependency
@app.cell
def _(plt, training_results):
    fig, ax = plt.subplots()
    ax.plot(training_results['losses'])
    fig
    return

The cell won't run until training_results has a value anyway.

Don't Use try/except for Control Flow

Don't wrap code in try/except blocks unless you're handling a specific, expected exception. Let errors surface naturally.

python
# BAD - hiding errors behind try/except
@app.cell
def _(scatter_widget, np, torch):
    try:
        X, y = scatter_widget.widget.data_as_X_y
        X = np.array(X, dtype=np.float32)
        # ...
    except Exception as e:
        return None, None, f"Error: {e}"

# GOOD - let it fail if something is wrong
@app.cell
def _(scatter_widget, np, torch):
    X, y = scatter_widget.widget.data_as_X_y
    X = np.array(X, dtype=np.float32)
    # ...

Only use try/except when:

  • You're handling a specific, known exception type
  • The exception is expected in normal operation (e.g., file not found)
  • You have a meaningful recovery action

Cell Output Rendering

Marimo only renders the final expression of a cell. Indented or conditional expressions won't render:

python
# BAD - indented expression won't render
@app.cell
def _(mo, condition):
    if condition:
        mo.md("This won't show!")  # WRONG - indented
    return

# GOOD - final expression renders
@app.cell
def _(mo, condition):
    result = mo.md("Shown!") if condition else mo.md("Also shown!")
    result  # This renders because it's the final expression
    return

PEP 723 Dependencies

Notebooks created via marimo edit --sandbox have these dependencies added to the top of the file automatically but it is a good practice to make sure these exist when creating a notebook too:

python
# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "marimo",
#     "torch>=2.0.0",
# ]
# ///
Show full SKILL.md (270 more words)Show less

marimo check

When working on a notebook it is important to check if the notebook can run. That's why marimo provides a check command that acts as a linter to find common mistakes.

bash
uvx marimo check <notebook.py>

Make sure these are checked before handing a notebook back to the user.

Important: you have a tendency to over-do variables with an underscore prefix. You should only apply this to one or two variables at most. Consider creating a new variable instead of prefixing entire cells in marimo.

api docs

If the user specifically wants you to use a marimo function, you can locally check the docs via:

uv --with marimo run python -c "import marimo as mo; help(mo.ui.form)"

tests

By default, marimo discovers and executes tests inside your notebook. When the optional pytest dependency is present, marimo runs pytest on cells that consist exclusively of test code - i.e. functions whose names start with test_. If the user asks you to add tests, make sure to add the pytest dependency is added and that there is a cell that contains only test code.

For more information on testing with pytest see PYTEST.md

Once tests are added, you can run pytest from the commandline on the notebook to run pytest.

pytest <notebook.py>

Additional resources

© cosanlab, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 12 other files (references) in .claude/skills/marimo-notebook of cosanlab/nltools.

  • SKILL.md
  • references/ANYWIDGET.md
  • references/CONFIGURATION.md
  • references/DEPLOYMENT.md
  • references/EXPENSIVE.md
  • references/EXPORTS.md
  • references/PYTEST.md
  • references/REACTIVITY.md
  • references/SQL.md
  • references/STATE.md
  • references/TOP-LEVEL-IMPORTS.md
  • references/UI.md
  • references/WATCHING.md

Open the folder on GitHubat commit cf366c2

Used in 4 other repositories

We found 4 copies of this SKILL.md (exact, near-identical or edited) in other folders, from 4 other GitHub owners. This page covers the copy in cosanlab/nltools, which our catalogue first saw on October 7, 2026.

Compare with similar skills

Marimo Notebook next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Marimo Notebook compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Marimo Notebook this skillcosanlab/nltools1314 repos~2.1kAutomated safety check: PassMIT
Wasm Compatibilityericmjl/llamabot1822 repos~1.6kAutomated safety check: PassNone
Marimo PairPhySpace/SimpleCADAPI140—~3kAutomated safety check: PassApache-2.0
Marimo Pair Vscodemarimo-team/marimo-lsp130—~2.7kAutomated safety check: PassApache-2.0
Marimobrycewang-stanford/Auto-Empirical-Research-Skills4.5k—~2.8kAutomated safety check: PassCustom licence
Marimo Notebookminicoohei/ai-agent-camp347—~1.5kAutomated safety check: PassNone

Similar skills

  • Wasm Compatibility

    ericmjl/llamabot

    Check if a marimo notebook is compatible with WebAssembly (WASM) and report any issues.

    182 GitHub starsUsed in 2 repos~1.6k tokens
    Data & AnalyticsAuto-check passed
  • Marimo Pair

    PhySpace/SimpleCADAPI

    Drive a live marimo notebook as a workspace: run Python in the same kernel the user does, inspect live notebook state, and commit durable notebook changes.

    140 GitHub stars~3k tokensUpdated 5 days ago
    Data & AnalyticsAuto-check passed
  • Marimo Pair Vscode

    marimo-team/marimo-lsp

    Drive a live marimo notebook in VS Code as a workspace: run Python in the same kernel the user does, inspect and explore live notebook state and data, prototype and debug code, and commit durable…

    130 GitHub stars~2.7k tokensUpdated yesterday
    Data & AnalyticsAuto-check passed
  • Marimo

    brycewang-stanford/Auto-Empirical-Research-Skills

    Reactive Python notebook system. An agent skill from brycewang-stanford/Auto-Empirical-Research-Skills.

    4.5k GitHub stars~2.8k tokensUpdated 2 days ago
    Data & AnalyticsAuto-check passed
  • Marimo Notebook

    minicoohei/ai-agent-camp

    marimo ノートブックを正しいフォーマットでPythonファイルに作成するスキル. An agent skill from minicoohei/ai-agent-camp.

    347 GitHub stars~1.5k tokensUpdated today
    Data & AnalyticsAuto-check passed
  • Marimo Development

    aiskillstore/marketplace

    Expert guidance for creating and working with marimo notebooks - reactive Python notebooks that can be executed as scripts and deployed as apps.

    430 GitHub stars~1.5k tokensUpdated today
    Data & AnalyticsAuto-check passed

More from cosanlab/nltools

  • Marimo Pair

    cosanlab/nltools

    Work inside a running marimo notebook's kernel — execute code, create cells, and build a notebook as an artifact.

    131 GitHub starsUsed in 1 repo~3k tokens
    Auto-check passed
  • Nilearn

    cosanlab/nltools

    Comprehensive nilearn (neuroimaging) API reference and best practices.

    131 GitHub stars~3.3k tokensUpdated 5 days ago
    Auto-check passed

Works with

Questions about Marimo Notebook

What does Marimo Notebook do?

Write a marimo notebook in a Python file in the right format. Marimo Notebook is an agent skill from cosanlab/nltools. Write a marimo notebook in a Python file in the right format.

When should I use Marimo Notebook?

Marimo Notebook fits situations like: tasks that involve Jupyter notebooks.

How do I install Marimo Notebook in Claude Code?

Run `npx skills add cosanlab/nltools --skill marimo-notebook -a claude-code`. Or copy the skill folder (.claude/skills/marimo-notebook in cosanlab/nltools) into .claude/skills/marimo-notebook in your project. Claude Code loads it when a task matches its description.

How do I install Marimo Notebook in Codex?

Run `npx skills add cosanlab/nltools --skill marimo-notebook -a codex`. Or copy the skill folder (.claude/skills/marimo-notebook in cosanlab/nltools) into .agents/skills/marimo-notebook in your project. Codex loads it when a task matches its description.

Can I use Marimo Notebook in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add cosanlab/nltools --skill marimo-notebook -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/marimo-notebook, .gemini/skills/marimo-notebook, .github/skills/marimo-notebook and .opencode/skills/marimo-notebook in your project.

What does Marimo Notebook need to run?

Going by SKILL.md and its folder, Marimo Notebook needs the command-line tools its instructions call (uv, uvx and pytest). Our summary lists: Python 3.

Does Marimo Notebook access the network?

SKILL.md contains no URLs. Its commands use uv and uvx, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Marimo Notebook safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Marimo Notebook use?

Marimo Notebook is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Marimo Notebook use?

About 2.1k tokens (SKILL.md is roughly 8.3k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 7.2k tokens, read only when the agent opens those files.

What are the alternatives to Marimo Notebook?

Skills that share tags, products or a category with Marimo Notebook: Wasm Compatibility (ericmjl/llamabot, 182 stars), Marimo Pair (PhySpace/SimpleCADAPI, 140 stars), Marimo Pair Vscode (marimo-team/marimo-lsp, 130 stars) and Marimo (brycewang-stanford/Auto-Empirical-Research-Skills, 4.5k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Marimo Notebook?

cosanlab (a GitHub organization) maintains it in cosanlab/nltools, which has 131 GitHub stars. The repository holds 3 skills in this directory. The repository was last updated on October 1, 2026.

Source: cosanlab/nltools on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.