Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

docs(ai): keep sidebar code mode aligned with marimo-pair (#10683)

Shahmir Varqha8d130b92e224
diff --git a/marimo/_server/ai/skills/marimo-pair/SKILL.md b/marimo/_server/ai/skills/marimo-pair/SKILL.md
index eb8e278006..0fedea06bb 100644
--- a/marimo/_server/ai/skills/marimo-pair/SKILL.md
+++ b/marimo/_server/ai/skills/marimo-pair/SKILL.md
@@ -41,6 +41,25 @@ passing your Python as the `code` argument. Everything you do — inspecting
state, testing transformations, and persisting changes via `cm` — runs through
`execute_code` in the scratchpad (see below).
+## Required First Kernel Command
+
+Start every code-mode session with this dedicated `execute_code` call:
+
+```python
+import marimo._code_mode as cm
+help(cm)
+```
+
+Follow this order for every live kernel, including read-only tasks:
+
+1. Run only the inspection command above.
+2. Wait for successful `help(cm)` output.
+3. Use `cm.get_context()` or another `cm` API in a later `execute_code` call.
+
+Do not combine the inspection with task-specific code, and do not use another
+`cm` API before the inspection succeeds. This verifies the private, unstable
+API exposed by the marimo version in the user's active kernel.
+
## Scratchpad Scope
`execute_code` evaluates Python in marimo's scratchpad: a temporary namespace
@@ -80,14 +99,6 @@ anything a user would run — methods can change or disappear across marimo
versions and kernels. Treat every `import marimo._code_mode as cm` as
scratchpad-only.
-At session start, inspect what `cm` exposes in the active kernel:
-
-```python
-import marimo._code_mode as cm
-
-help(cm)
-```
-
Open a code-mode context to queue notebook changes.
```python
diff --git a/marimo/_server/ai/skills/marimo-pair/references/gotchas.md b/marimo/_server/ai/skills/marimo-pair/references/gotchas.md
index 147dc25f52..b072de6a35 100644
--- a/marimo/_server/ai/skills/marimo-pair/references/gotchas.md
+++ b/marimo/_server/ai/skills/marimo-pair/references/gotchas.md
@@ -47,8 +47,11 @@ The same single-definition rule applies to imports: a public name (like `pd`)
can only be defined in one cell. If two cells both `import pandas as pd`, you
get a `Multiply-defined names` error at validation.
-**Fix:** Use a `_` prefix on the second import (`import pandas as _pd`) or
-consolidate imports into a shared cell.
+**Fix:** Reuse the existing import — reference `pd` directly, or edit the
+owning cell (`ctx.edit_cell`) if the import belongs there instead. If several
+cells need the import, consolidate it into the setup cell or a shared
+import-only cell. Load the `notebook-improvements` capability for setup-cell
+guidance.
## `inspect.getsource()` on methods is indented
diff --git a/marimo/_server/ai/skills/marimo-pair/references/notebook-improvements.md b/marimo/_server/ai/skills/marimo-pair/references/notebook-improvements.md
index ec6f7669a6..c04cc78338 100644
--- a/marimo/_server/ai/skills/marimo-pair/references/notebook-improvements.md
+++ b/marimo/_server/ai/skills/marimo-pair/references/notebook-improvements.md
@@ -25,6 +25,14 @@ it must be self-contained: imports, constants, and definitions that depend only
on each other. Reading a name defined elsewhere (e.g. `df`, a UI element) fails
with `The setup cell cannot have references`.
+**Keep the setup cell import-only if you can.** marimo skips re-running
+descendants when an edited cell contains only import statements, because
+imports resolve independently of the notebook's reactive dataflow. This
+applies to every import-only cell, not only `setup`. It matters most for
+`setup`, because every other cell depends on it: if the setup cell also defines
+constants or other values, editing it re-runs the entire notebook. Put those
+definitions in a separate cell downstream of `setup`.
+
First check if the notebook already has a cell named `"setup"`. If not, create
one and hoist scattered imports into it. `name="setup"` auto-positions the cell
first — no `before`/`after` needed:
diff --git a/tests/_server/ai/test_prompts.py b/tests/_server/ai/test_prompts.py
index ab974b2007..05060c097b 100644
--- a/tests/_server/ai/test_prompts.py
+++ b/tests/_server/ai/test_prompts.py
@@ -423,6 +423,9 @@ def test_chat_system_prompt_code_mode():
assert "load_capability" in prompt
assert "`gotchas`" in prompt
assert "references/gotchas.md" not in prompt
+ assert "## Required First Kernel Command" in prompt
+ assert "Run only the inspection command above" in prompt
+ assert "before the inspection succeeds" in prompt
def test_chat_system_prompt_code_mode_includes_extras():