notebook-ai-agents-skill
npx machina-cli add skill fmschulz/omics-skills/notebook-ai-agents-skill --openclawNotebook AI Agents Skill (Marimo First)
Build narrative-first, reproducible notebooks with strict run-all validation and clean data loading patterns. Prefer Marimo for new notebooks; support Jupyter only when needed for existing .ipynb files.
Instructions
- Prefer Marimo for new work. Create a
.pynotebook and keep cells small and deterministic. - Outline the notebook (purpose, data sources, analysis steps, outputs) before coding.
- Use project-relative paths and DuckDB for data loading (TSV/Parquet preferred).
- Build plots with the shared style rules.
- Validate by running the notebook end-to-end (Marimo:
marimo run; Jupyter: restart kernel + run all).
Quick Reference
| Task | Action |
|---|---|
| Marimo docs | https://docs.marimo.io/ |
| Jupyter (legacy) | See docs/notebook_structure.md |
| Pixi + Jupyter (legacy) | See docs/pixi_jupyter.md |
| Data loading | See docs/data_loading_duckdb.md |
| Plot styling | See docs/plot_style.md |
| Validation | See docs/verification.md |
| Templates (legacy) | templates/kiss_notebook_template.py |
Input Requirements
- Notebook scope and goals
- Data file paths (TSV/Parquet preferred)
- Python environment (Pixi recommended)
- Marimo installed (preferred) or Jupyter available (legacy)
Output
- Reproducible notebook with narrative markdown
- Validated run-all execution
- Plots and tables suitable for reporting
Quality Gates
- Narrative text precedes code for each major step
- All cells run top-to-bottom without hidden state
- Data paths are project-relative and verified
- Plots are labeled, readable, and consistent
Examples
Example 1: Run a Marimo notebook
marimo run notebooks/analysis.py
Example 2: Execute a Jupyter notebook (legacy)
python scripts/execute_notebook.py path/to/notebook.ipynb
Troubleshooting
Issue: Marimo fails to run due to missing dependencies Solution: Install required packages in the Pixi environment and re-run.
Issue: Jupyter notebook fails on restart Solution: Remove hidden state, re-run from a clean kernel, and fix warnings.
Source
git clone https://github.com/fmschulz/omics-skills/blob/main/skills/notebook-ai-agents-skill/SKILL.mdView on GitHub Overview
This skill guides building reproducible, narrative-first analysis notebooks with Marimo as the preferred engine, while supporting Jupyter for legacy files. It emphasizes small, deterministic cells, project-relative data loading, and end-to-end run-all validation to ensure repeatable results and clear storytelling.
How This Skill Works
Create a .py notebook for Marimo-based workflows, outlining purpose, data sources, steps, and outputs before coding. Use project-relative paths and DuckDB for loading TSV/Parquet data, then build plots with a shared style. Validate by running the notebook end-to-end with marimo run (or Jupyter by restarting kernel and running all) to ensure reproducibility.
When to Use It
- Starting a new data analysis notebook where reproducibility and narrative structure are paramount
- Migrating an existing notebook to a Marimo-first workflow with strict run-all validation
- Working with project-relative data paths and DuckDB-based loading for robust data access
- Creating reporting-ready plots and tables with consistent styling
- Validating end-to-end execution to ensure no hidden state affects results
Quick Start
- Step 1: Prefer Marimo for new work and create a .py notebook (small, deterministic cells)
- Step 2: Outline purpose, data sources, analysis steps, and outputs before coding
- Step 3: Use project-relative paths and DuckDB for data loading; run marimo run to validate
Best Practices
- Outline notebook purpose, data sources, analysis steps, and outputs before coding
- Prefer Marimo for new work; keep cells small and deterministic
- Use project-relative paths and DuckDB for data loading (TSV/Parquet preferred)
- Build plots with the shared style rules and label axes clearly
- Validate by running the notebook end-to-end (Marimo: marimo run; Jupyter: restart kernel + run all)
Example Use Cases
- Run a Marimo notebook: marimo run notebooks/analysis.py
- Execute a Jupyter notebook (legacy): python scripts/execute_notebook.py path/to/notebook.ipynb
- Refactor a notebook to use project-relative data paths and DuckDB for loading
- Apply the shared plot styling to ensure consistency across reports
- Perform end-to-end validation to confirm no hidden state affects outputs
