docs: consolidate AI guides and route readers to marimo pair#10293
Merged
Conversation
The AI docs had grown page-by-page as features shipped: four different ways to use an agent with marimo documented across four pages that didn't reference each other, skills explained in three places, the anywidget prompt duplicated verbatim on two pages, and marimo pair — the recommended path — not prominently documented. This PR merges `prompts.md`, `skills.md`, and `using_claude_code.md` into a single "Customize your agent" guide (skills, slash commands, hooks). It also rewrites the Generate with AI index as an orientation page that lays out the three paths: pair an agent CLI (recommended), use the editor's built-in assistant, or generate from scratch with `marimo new`. The nav now names marimo pair, and `ai_completion.md` has a single nav home instead of appearing under two sections. Old URLs redirect via vercel.json. The merged guide drops the AGENTS.md/CLAUDE.md section: the marimo-notebook skill covers the same ground and is loaded on demand and centrally updated, while the curl'd snippet injected 370 stale lines into every conversation. (docs.marimo.io/CLAUDE.md itself still exists for current consumers.) The guide also recommends the cross-agent `.agents/skills/` convention over `.claude/skills/`, and scopes the slash-command and hook examples to Claude Code explicitly. Pages that overlap with pair (`agents.md`, `mcp.md`, `ai_completion.md`, `text_to_notebook.md`) each get one pointer with a distinct job — disambiguation, steering away from heavier integrations, or iterating on a generated notebook — rather than scattered mentions. Other drive-by fixes: Also fixes the broken thumbnail links on the examples index (raw HTML hrefs aren't rewritten by mkdocs, so `.md` paths and a wrong-case anchor 404'd), swaps the tip admonition icon from Material's default flame to a lightbulb outline, and fixes a few typos.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
All reported issues were addressed across 15 files
Architecture diagram
sequenceDiagram
participant User
participant Browser
participant Vercel as Vercel CDN
participant Docs as Docs Site (Static)
participant Index as Generate with AI Index
participant Customize as Customize Your Agent Guide
participant OldURL as Old URLs (/prompts, /skills, /using_claude_code)
participant Pair as marimo pair Guide
participant EditorAI as Editor AI Assistant Guide
Note over User,EditorAI: New documentation flow after consolidation
User->>Browser: Clicks "Generate with AI" nav link
Browser->>Docs: GET /guides/generate_with_ai/
Docs-->>Browser: Returns index page
Note over Browser,Index: Index now presents three paths
alt User chooses "Customize your agent"
User->>Browser: Clicks "Customize your agent"
Browser->>Docs: GET /guides/generate_with_ai/customize_your_agent/
Docs-->>Browser: Returns merged guide (skills, slash commands, hooks)
Browser-->>User: Shows merged content
Note over User,Customize: Guide recommends `marimo pair` and `--watch` flag
else User chooses "Pair with agents"
User->>Browser: Clicks "Pair with agents via marimo pair"
Browser->>Docs: GET /guides/generate_with_ai/marimo_pair/
Docs-->>Browser: Returns pair guide
Browser-->>User: Shows how to install and use marimo pair
else User chooses "Editor AI assistant"
User->>Browser: Clicks "The editor's AI assistant"
Browser->>Docs: GET /guides/editor_features/ai_completion/
Docs-->>Browser: Returns AI completion guide
Note over Browser,EditorAI: Guide now points to pair at top
Browser-->>User: Shows editor AI features
else User chooses "Generate with marimo new"
User->>Browser: Clicks "Generate notebooks with marimo new"
Browser->>Docs: GET /guides/generate_with_ai/text_to_notebook/
Docs-->>Browser: Returns one-shot notebook generation
Note over Browser: Guide suggests iterating with marimo pair
end
Note over User,OldURL: Old bookmarks and external links redirect permanently
User->>Browser: Opens old URL (e.g. /guides/generate_with_ai/prompts/)
Browser->>Vercel: GET /guides/generate_with_ai/prompts/
Vercel->>Vercel: Match redirect in vercel.json
Vercel-->>Browser: 301 → /guides/generate_with_ai/customize_your_agent/
Browser->>Docs: GET /guides/generate_with_ai/customize_your_agent/
Docs-->>Browser: Returns same merged guide
Note over User,Customize: Cross-references from other pages now point to pair
User->>Browser: Reads anywidget.md (old tip)
Browser->>Docs: GET /api/inputs/anywidget/
Docs-->>Browser: Updated tip → "install official skills" with link to customize page
User->>Browser: Reads agents.md
Browser->>Docs: GET /guides/editor_features/agents/
Docs-->>Browser: Added tip recommending marimo pair instead
User->>Browser: Reads mcp.md
Browser->>Docs: GET /guides/editor_features/mcp/
Docs-->>Browser: Added pointer to marimo pair for agent-driven notebooks
User->>Browser: Reads ai_completion.md
Browser->>Docs: GET /guides/editor_features/ai_completion/
Docs-->>Browser: Added tip steering to marimo pair, updated agents link
User->>Browser: Reads text_to_notebook.md
Browser->>Docs: GET /guides/generate_with_ai/text_to_notebook/
Docs-->>Browser: Added tip to iterate generated notebook via marimo pair
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
Contributor
There was a problem hiding this comment.
Pull request overview
This PR consolidates and reorients marimo’s AI documentation to reduce duplication, clarify the recommended “marimo pair” workflow, and keep legacy URLs working via redirects.
Changes:
- Consolidates multiple agent-customization docs into a single “Customize your agent” guide and updates the “Generate with AI” landing page to describe the three supported paths.
- Updates MkDocs navigation + theme tip icon, and adds Vercel redirects for removed AI doc URLs.
- Fixes/updates cross-page pointers and broken example thumbnail links.
Reviewed changes
Copilot reviewed 15 out of 15 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| mkdocs.yml | Updates nav labels/structure for AI docs and sets a custom “tip” admonition icon. |
| docs/vercel.json | Adds permanent redirects from removed AI doc URLs to the consolidated guide. |
| docs/guides/wasm.md | Updates skills link to point into the consolidated “Customize your agent” guide. |
| docs/guides/generate_with_ai/using_claude_code.md | Removes now-duplicated Claude Code customization content (redirected). |
| docs/guides/generate_with_ai/text_to_notebook.md | Adds guidance to iterate on generated notebooks via marimo pair; minor link/title tweak. |
| docs/guides/generate_with_ai/skills.md | Removes now-duplicated skills page content (redirected). |
| docs/guides/generate_with_ai/prompts.md | Removes now-duplicated prompts page content (redirected). |
| docs/guides/generate_with_ai/marimo_pair.md | Minor wording/heading cleanup and formatting fixes. |
| docs/guides/generate_with_ai/index.md | Rewrites as an orientation page describing the three AI workflows and linking into the new structure. |
| docs/guides/generate_with_ai/customize_your_agent.md | New consolidated guide covering skills, slash commands, and hooks. |
| docs/guides/editor_features/mcp.md | Adds a pointer steering users to marimo pair; needs a small wording consistency fix re: tool exposure. |
| docs/guides/editor_features/ai_completion.md | Adds a top-level pointer to marimo pair, fixes typos, and clarifies the “Agents panel” section. |
| docs/guides/editor_features/agents.md | Adds a pointer to marimo pair to disambiguate embedded-editor agents vs agent CLIs. |
| docs/examples/index.md | Fixes broken thumbnail links and normalizes some anchors/paths. |
| docs/api/inputs/anywidget.md | Updates the anywidget “prompts” reference to instead point to official skills in the new guide. |
Comments suppressed due to low confidence (1)
docs/guides/editor_features/mcp.md:43
- The MCP Server section currently describes the server as exposing “read-only tools”, but the “Available tools” paragraph right below says external applications can access “all AI tools” (which includes editing tools in the AI tools guide). This is internally inconsistent and can mislead readers about what MCP can do; please clarify that MCP exposes only the read-only/Ask tool subset (and not notebook-editing tools).
marimo can expose its [AI tools](tools.md) through an MCP server endpoint, allowing external AI applications to interact with your notebooks. If your goal is to have a coding agent drive a live notebook, see [marimo pair](../generate_with_ai/marimo_pair.md) instead; the MCP server exposes lower-level, read-only tools.
<video autoplay loop muted playsinline width="100%" height="100%" align="center">
<source src="/_static/docs-mcp-server.mp4" type="video/mp4">
</video>
Comment on lines
+183
to
+185
| This script checks if the Python file contains a `import marimo` and a `@app.cell` string. If that's the case | ||
| we assume we're dealing with a marimo notebook and we run `uvx marimo check` on the file. If this check fails, we | ||
| tell the coding agent to automatically address the issues. This can save *a lot* of time. |
mscolnick
approved these changes
Jul 23, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The AI docs had grown page-by-page as features shipped: four different ways to use an agent documented across four pages that didn't reference each other, skills explained in three places, an anywidget prompt duplicated verbatim on two pages, and marimo pair — the recommended path — not prominently documented.
This PR merges
prompts.md,skills.md, andusing_claude_code.mdinto a single "Customize your agent" guide (skills, slash commands, hooks). It also rewrites the Generate with AI index as an orientation page that lays out the three paths: pair an agent CLI (recommended), use the editor's built-in assistant, or generate from scratch withmarimo new. The nav now names marimo pair, andai_completion.mdhas a single nav home instead of appearing under two sections. Old URLs redirect via vercel.json.The merged guide drops the AGENTS.md/CLAUDE.md section: the marimo-notebook skill covers the same ground and is loaded on demand and centrally updated, while the curl'd snippet injected 370 stale lines into every conversation. (docs.marimo.io/CLAUDE.md itself still exists for current consumers.) The guide also recommends the cross-agent
.agents/skills/convention over.claude/skills/, and scopes the slash-command and hook examples to Claude Code explicitly.Pages that overlap with pair (
agents.md,mcp.md,ai_completion.md,text_to_notebook.md) each get one pointer with a distinct job — disambiguation, steering away from heavier integrations, or iterating on a generated notebook — rather than scattered mentions.Other drive-by fixes: Fixes the broken thumbnail links on the examples index, swaps the tip admonition icon from Material's default flame to a lightbulb outline, and fixes a few typos.