jupyter-notebook-writing by zc277584121/marketing-skills
npx skills add https://github.com/zc277584121/marketing-skills --skill jupyter-notebook-writing作为 DevRel 工作流,编写 Milvus 应用级别的 Jupyter notebook 示例。采用 Markdown 优先的方法 —— AI 编辑 .md 文件,然后通过 jupyter-switch 转换为 .ipynb。
先决条件 : Python >= 3.10, uv (
uvx命令可用)
用户想要创建或编辑一个 Jupyter notebook 示例,通常用于在应用场景(RAG、语义搜索、混合搜索等)中演示 Milvus 的使用。
Jupyter .ipynb 文件包含复杂的 JSON,其中包含元数据、输出和执行计数 —— 直接让 AI 编辑非常痛苦。因此采用以下方法:
.md 文件 —— AI 处理干净的 Markdown.ipynb —— 使用 生成可运行的 notebookWrite Milvus application-level Jupyter notebook examples as a DevRel workflow. Uses a Markdown-first approach — AI edits .md files, then converts to .ipynb via jupyter-switch.
Prerequisites : Python >= 3.10, uv (
uvxcommand available)
The user wants to create or edit a Jupyter notebook example, typically demonstrating Milvus usage in an application context (RAG, semantic search, hybrid search, etc.).
Jupyter .ipynb files contain complex JSON with metadata, outputs, and execution counts — painful for AI to edit directly. Instead:
.md file — AI works with clean Markdown广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
jupyter-switch.md 文件是编辑的单一事实来源在 .md 文件中:
python ... ) 在 notebook 中变为 代码单元格.md 中(它们会在运行 notebook 时生成)# Markdown -> Jupyter Notebook
uvx jupyter-switch example.md
# 生成 example.ipynb
# Jupyter Notebook -> Markdown
uvx jupyter-switch example.ipynb
# 生成 example.md
.bak 备份example.md(参见下面的结构)uvx jupyter-switch example.mdexample.md 和 example.ipynb 都存在了.ipynb 存在,先转换:uvx jupyter-switch example.ipynb.md 文件uvx jupyter-switch example.md在运行任何 notebook 之前,必须确定使用哪个 Python 环境。系统默认的 jupyter execute 可能没有安装所需的包。
步骤 A — 检查保存的偏好设置。 在当前项目的 CLAUDE.local.md 中查找 ## Jupyter Notebook Execution 部分。如果它包含一个内核名称,直接使用它并跳到步骤 2。
步骤 B — 如果没有保存的偏好设置,询问用户。 首先检测可用的环境:
# 发现 conda/mamba 环境
conda env list 2>/dev/null || mamba env list 2>/dev/null
# 发现已注册的 Jupyter 内核
jupyter kernelspec list 2>/dev/null
# 检查系统默认 Python
which python3 2>/dev/null && python3 --version 2>/dev/null
# 检查工作目录中的本地虚拟环境
ls -d .venv/ venv/ 2>/dev/null
# 检查是否是 uv 管理的项目 (pyproject.toml + .venv)
test -f pyproject.toml && test -d .venv && echo "uv/pip project venv detected"
然后呈现一个带编号的选择列表。包含所有检测到的环境:
jupyter execute,不使用 --kernel_name.venv/ 或 venv/)—— 该 venv 内的 Python关于 uv 项目的说明: 如果工作目录有
pyproject.toml+.venv/(一个 uv 管理的项目),本地 venv 选项覆盖了这种情况。如果 jupyter 是项目依赖项,用户也可以直接运行uv run jupyter execute example.ipynb。
对于每个选项,也提供一个“记住”的变体。示例提示:
我应该使用哪个 Python 环境来运行这个 notebook?
1. 系统默认 (按原样运行 jupyter execute)
2. conda: myenv (/path/to/envs/myenv)
3. Jupyter 内核: some-kernel
4. 本地 venv (.venv/)
5. 自定义 — 输入路径或环境名称
提示:添加 "remember" 来保存你的选择(例如 "2, remember"),
这样它就会被写入 CLAUDE.local.md,下次我就不用再问了。
步骤 C — 应用所选环境:
| 场景 | 操作 |
|---|---|
| 已经是已注册的 Jupyter 内核 | 使用 jupyter execute --kernel_name=<name> |
| Conda 环境尚未注册为内核 | 先注册:<env-python> -m ipykernel install --user --name <name> --display-name "<label>",然后使用 --kernel_name=<name> |
| 自定义 Python 路径 | 同上 — 先注册为内核,然后使用 --kernel_name |
步骤 D — 如果用户选择了“记住”: 在当前项目的 CLAUDE.local.md 中追加或更新 ## Jupyter Notebook Execution 部分:
## Jupyter Notebook Execution
- **Jupyter kernel**: `<kernel-name>`
这确保了未来的运行会跳过提示,直接使用保存的内核。
在运行之前,在 .md 文件中注释掉“仅用于设置”的单元格 —— 这些单元格是为首次用户准备的,但不应在自动化测试环境中运行。具体来说:
pip install 单元格 —— 依赖项应该已经安装在所选的 Jupyter 环境中。如果缺少任何包或需要升级,请在目标环境中外部安装它们(使用 --upgrade),而不是在 notebook 内部。os.environ["OPENAI_API_KEY"] = "sk-***********"。相反,应在运行前在外部设置环境变量(在 shell 中导出,或在 jupyter execute 之前通过代码注入)。要注释掉一个单元格,将其内容包装在块注释中,这样单元格仍然会执行(产生空输出)但什么都不做:
# # pip install --upgrade langchain pymilvus
# import os
# os.environ["OPENAI_API_KEY"] = "sk-***********"
这保持了 notebook 结构的完整性(单元格数量、顺序),同时防止与外部 Jupyter 环境发生冲突。
对于环境变量: 要么在运行 jupyter execute 之前在 shell 中 export 它们,要么在命令前添加它们:
OPENAI_API_KEY="sk-real-key" jupyter execute --kernel_name=<name> example.ipynb
.md 转换为 .ipynb<env-python> -m pip install --upgrade <packages>jupyter execute --kernel_name=<name> example.ipynb(如果使用系统默认,则省略 --kernel_name).md 文件中修复,如果需要调试则取消注释设置单元格,然后重新转换一个典型的 Milvus 示例 notebook 遵循以下结构:
# 标题
简要描述此 notebook 演示的内容。
## 先决条件
安装依赖项:
` ``python
!pip install pymilvus some-other-package
` ``
## 设置
导入和配置:
` ``python
from pymilvus import MilvusClient
client = MilvusClient(uri="http://localhost:19530")
` ``
## 准备数据
加载或生成示例数据:
` ``python
# 数据准备代码
` ``
## 创建集合并插入数据
` ``python
# 集合创建和数据插入
` ``
## 查询 / 搜索
` ``python
# 搜索或查询示例
` ``
## 清理
` ``python
client.drop_collection("example_collection")
` ``
此技能在 references/ 下包含两个参考文档。当任务涉及相关主题时,请阅读它们。
| 参考文档 | 何时阅读 | 文件 |
|---|---|---|
| Bootcamp 格式 | 编写 Milvus 集成教程(徽章、文档结构、章节格式、示例布局)时 | references/bootcamp-format.md |
| Milvus 代码风格 | 编写 pymilvus 代码(集合创建、MilvusClient 连接参数、模式模式、最佳实践)时 | references/milvus-code-style.md |
references/bootcamp-format.md)当用户为 bootcamp 仓库编写 Milvus 集成教程 时阅读此文档。它涵盖:
"sk-***********")references/milvus-code-style.md)当 notebook 涉及 pymilvus 代码 时阅读此文档。关键规则:
MilvusClient API —— 绝不使用遗留的 ORM 层(connections.connect()、Collection()、FieldSchema() 等)create_schema + add_field)—— 不要在没有模式的情况下使用快捷方式 create_collection(dimension=...)has_collection 检查create_collection() 中添加注释掉的 consistency_level="Strong" 行load_collection() —— 集合在创建时自动加载uri 选项(Milvus Lite / Docker / Zilliz Cloud)的引用块.md 文件,而不是直接编辑 .ipynb。.md 文件更易于 AI 读取和写入。.md 用于编辑,.ipynb 用于运行/分享。.md 后,始终重新运行 uvx jupyter-switch example.md 以同步 .ipynb。每周安装数
103
仓库
首次出现
2026年3月5日
安全审计
安装于
trae-cn103
antigravity103
codebuddy103
github-copilot103
codex103
kimi-cli103
.ipynb — using jupyter-switch for runnable notebook.md is the source of truth for editingIn the .md file:
python ... ) become code cells in the notebook.md (they get generated when running the notebook)# Markdown -> Jupyter Notebook
uvx jupyter-switch example.md
# produces example.ipynb
# Jupyter Notebook -> Markdown
uvx jupyter-switch example.ipynb
# produces example.md
.bak backup is created automaticallyexample.md with the content (see structure below)uvx jupyter-switch example.mdexample.md and example.ipynb now exist.ipynb exists, convert first: uvx jupyter-switch example.ipynb.md fileuvx jupyter-switch example.mdBefore running any notebook, you must determine which Python environment to use. The system default jupyter execute may not have the required packages installed.
Step A — Check for saved preference. Look in the current project's CLAUDE.local.md for a ## Jupyter Notebook Execution section. If it contains a kernel name, use it directly and skip to Step 2.
Step B — If no saved preference, ask the user. Detect available environments first:
# Discover conda/mamba environments
conda env list 2>/dev/null || mamba env list 2>/dev/null
# Discover registered Jupyter kernels
jupyter kernelspec list 2>/dev/null
# Check system default Python
which python3 2>/dev/null && python3 --version 2>/dev/null
# Check for local virtual environment in the working directory
ls -d .venv/ venv/ 2>/dev/null
# Check if a uv-managed project (pyproject.toml + .venv)
test -f pyproject.toml && test -d .venv && echo "uv/pip project venv detected"
Then present a numbered list of choices. Include all detected environments:
jupyter execute as-is, no --kernel_name.venv/ or venv/ found in working directory) — the Python inside that venvNote on uv projects: If the working directory has
pyproject.toml+.venv/(a uv-managed project), the local venv option covers this case. The user can also runuv run jupyter execute example.ipynbdirectly if jupyter is a project dependency.
For every option, also offer a "remember" variant. Example prompt:
Which Python environment should I use to run this notebook?
1. System default (jupyter execute as-is)
2. conda: myenv (/path/to/envs/myenv)
3. Jupyter kernel: some-kernel
4. Local venv (.venv/)
5. Custom — enter a path or environment name
Tip: add "remember" to save your choice (e.g. "2, remember"),
so it gets written to CLAUDE.local.md and I won't ask next time.
Step C — Apply the chosen environment:
| Scenario | Action |
|---|---|
| Already a registered Jupyter kernel | Use jupyter execute --kernel_name=<name> |
| Conda env not yet registered as kernel | Register first: <env-python> -m ipykernel install --user --name <name> --display-name "<label>", then use --kernel_name=<name> |
| Custom Python path | Same as above — register as kernel first, then use --kernel_name |
Step D — If the user chose "remember": append or update a ## Jupyter Notebook Execution section in the current project's CLAUDE.local.md:
## Jupyter Notebook Execution
- **Jupyter kernel**: `<kernel-name>`
This ensures future runs skip the prompt and use the saved kernel directly.
Before running, comment out "setup-only" cells in the .md file — cells that are meant for first-time users but should not run in an automated test environment. Specifically:
pip install cells — dependencies should already be installed in the chosen Jupyter environment. If any packages are missing or need upgrading, install them externally in the target environment (with --upgrade), not inside the notebook.os.environ["OPENAI_API_KEY"] = "sk-***********". Instead, set environment variables externally before running (export in shell, or inject via code before jupyter execute).To comment out a cell, wrap its content in a block comment so the cell still executes (producing empty output) but does nothing:
# # pip install --upgrade langchain pymilvus
# import os
# os.environ["OPENAI_API_KEY"] = "sk-***********"
This keeps the notebook structure intact (cell count, ordering) while preventing conflicts with the external Jupyter environment.
For environment variables: either export them in the shell before running jupyter execute, or prepend them to the command:
OPENAI_API_KEY="sk-real-key" jupyter execute --kernel_name=<name> example.ipynb
.md to .ipynb if needed<env-python> -m pip install --upgrade <packages>jupyter execute --kernel_name=<name> example.ipynb (omit --kernel_name if using system default).md file, uncomment setup cells if needed for debugging, and re-convertA typical Milvus example notebook follows this structure:
# Title
Brief description of what this notebook demonstrates.
## Prerequisites
Install dependencies:
` ``python
!pip install pymilvus some-other-package
` ``
## Setup
Import and configuration:
` ``python
from pymilvus import MilvusClient
client = MilvusClient(uri="http://localhost:19530")
` ``
## Prepare Data
Load or generate example data:
` ``python
# data preparation code
` ``
## Create Collection & Insert Data
` ``python
# collection creation and data insertion
` ``
## Query / Search
` ``python
# search or query examples
` ``
## Cleanup
` ``python
client.drop_collection("example_collection")
` ``
This skill includes two reference documents under references/. Read them when the task involves their topics.
| Reference | When to Read | File |
|---|---|---|
| Bootcamp Format | Writing a Milvus integration tutorial (badges, document structure, section format, example layout) | references/bootcamp-format.md |
| Milvus Code Style | Writing pymilvus code (collection creation, MilvusClient connection args, schema patterns, best practices) | references/milvus-code-style.md |
references/bootcamp-format.md)Read this when the user is writing a Milvus integration tutorial for the bootcamp repository. It covers:
"sk-***********")references/milvus-code-style.md)Read this when the notebook involves pymilvus code. Key rules:
MilvusClient API — never use the legacy ORM layer (connections.connect(), Collection(), FieldSchema(), etc.)create_schema + add_field) — do not use the shortcut create_collection(dimension=...) without schemahas_collection check before creating collectionsconsistency_level="Strong" line in create_collection()load_collection() — collections auto-load on creationuri options (Milvus Lite / Docker / Zilliz Cloud).md file, not the .ipynb directly. The .md is easier for AI to read and write..md for editing, .ipynb for running/sharing..md, always re-run uvx jupyter-switch example.md to sync the .ipynb.Weekly Installs
103
Repository
First Seen
Mar 5, 2026
Security Audits
Installed on
trae-cn103
antigravity103
codebuddy103
github-copilot103
codex103
kimi-cli103
AI Elements:基于shadcn/ui的AI原生应用组件库,快速构建对话界面
66,200 周安装
Web开发全栈指南:Bootstrap、Django、HTMX框架实战与最佳实践
102 周安装
FDA咨询专家服务:医疗器械法规、质量体系、HIPAA合规与网络安全咨询
198 周安装
AI上下文管理器技能 - 动态上下文工程、向量数据库与多智能体工作流编排专家指南
201 周安装
项目安全设置协调器 - 自动化安全扫描、配置与风险评估工具
203 周安装
TypeScript/Python/.NET项目代码检查工具自动配置 - ESLint, Ruff, Roslyn Analyzers
199 周安装
Eve 计划实施技能:将计划文档转化为并行任务,实现高效项目编排与执行
201 周安装