格式约定

在 .md 文件中：

• Python 代码块 (python ... ) 在 notebook 中变为 代码单元格
• 其他所有内容 变为 Markdown 单元格
• 单元格输出不会保留在 .md 中（它们会在运行 notebook 时生成）

转换命令

# Markdown -> Jupyter Notebook
uvx jupyter-switch example.md
# 生成 example.ipynb

# Jupyter Notebook -> Markdown
uvx jupyter-switch example.ipynb
# 生成 example.md

• 原始输入文件永远不会被修改或删除
• 如果输出文件已存在，会自动创建 .bak 备份

分步指南

创建新的 Notebook

1. 创建包含内容的 example.md（参见下面的结构）
2. 转换：uvx jupyter-switch example.md
3. 现在 example.md 和 example.ipynb 都存在了

编辑现有的 Notebook

1. 如果只有 .ipynb 存在，先转换：uvx jupyter-switch example.ipynb
2. 编辑 .md 文件
3. 转换回来：uvx jupyter-switch example.md

测试 / 运行

1. 确定 Jupyter 执行环境

在运行任何 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"

然后呈现一个带编号的选择列表。包含所有检测到的环境：

1. 系统默认 —— 按原样运行 jupyter execute，不使用 --kernel_name
2. 每个检测到的 conda/mamba 环境 —— 显示名称和路径
3. 每个已注册的 Jupyter 内核 —— 显示内核名称
4. 本地 venv（如果在工作目录中找到 .venv/ 或 venv/）—— 该 venv 内的 Python
5. 自定义 —— 让用户输入 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 — 应用所选环境：

步骤 D — 如果用户选择了“记住”： 在当前项目的 CLAUDE.local.md 中追加或更新 ## Jupyter Notebook Execution 部分：

## Jupyter Notebook Execution

- **Jupyter kernel**: `<kernel-name>`

这确保了未来的运行会跳过提示，直接使用保存的内核。

2. 准备 notebook 以执行

在运行之前，在 .md 文件中注释掉“仅用于设置”的单元格 —— 这些单元格是为首次用户准备的，但不应在自动化测试环境中运行。具体来说：

• pip install 单元格 —— 依赖项应该已经安装在所选的 Jupyter 环境中。如果缺少任何包或需要升级，请在目标环境中外部安装它们（使用 --upgrade），而不是在 notebook 内部。
• API 密钥 / 凭证占位符单元格 —— 例如 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

3. 转换并运行

1. 如果需要，将 .md 转换为 .ipynb
2. 在目标环境中外部安装任何缺失的依赖项：<env-python> -m pip install --upgrade <packages>
3. 运行：jupyter execute --kernel_name=<name> example.ipynb（如果使用系统默认，则省略 --kernel_name）
4. 如果发现错误，在 .md 文件中修复，如果需要调试则取消注释设置单元格，然后重新转换

Notebook 结构模板

一个典型的 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 格式 (references/bootcamp-format.md)

当用户为 bootcamp 仓库编写 Milvus 集成教程 时阅读此文档。它涵盖：

• 徽章格式（顶部的 Colab + GitHub 徽章）
• 文档结构：页眉 -> 先决条件 -> 主要内容 -> 结论
• 依赖项安装格式，附带 Google Colab 重启说明
• API 密钥占位符约定 ("sk-***********")
• 每个代码块之前应有简短的文字介绍

Milvus 代码风格 (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() —— 集合在创建时自动加载
• 第一个 MilvusClient 连接必须包含解释 uri 选项（Milvus Lite / Docker / Zilliz Cloud）的引用块

重要说明

• 始终编辑 .md 文件，而不是直接编辑 .ipynb。.md 文件更易于 AI 读取和写入。
• 保留两个文件 —— .md 用于编辑，.ipynb 用于运行/分享。
• 编辑 .md 后，始终重新运行 uvx jupyter-switch example.md 以同步 .ipynb。

每周安装数

103

仓库

zc277584121/mar…g-skills

首次出现

2026年3月5日

安全审计

Gen Agent Trust HubPassSocketPassSnykWarn

安装于

trae-cn103

antigravity103

codebuddy103

github-copilot103

codex103

kimi-cli103

Format Convention

In the .md file:

• Python code blocks (python ... ) become code cells in the notebook
• Everything else becomes markdown cells
• Cell outputs are not preserved in .md (they get generated when running the notebook)

Conversion Commands

# Markdown -> Jupyter Notebook
uvx jupyter-switch example.md
# produces example.ipynb

# Jupyter Notebook -> Markdown
uvx jupyter-switch example.ipynb
# produces example.md

• The original input file is never modified or deleted
• If the output file already exists, a .bak backup is created automatically

Step-by-Step

Creating a New Notebook

1. Create example.md with the content (see structure below)
2. Convert: uvx jupyter-switch example.md
3. Both example.md and example.ipynb now exist

Editing an Existing Notebook

1. If only .ipynb exists, convert first: uvx jupyter-switch example.ipynb
2. Edit the .md file
3. Convert back: uvx jupyter-switch example.md

Testing / Running

1. Resolve the Jupyter execution environment

Before 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:

1. System default — run jupyter execute as-is, no --kernel_name
2. Each detected conda/mamba environment — show name and path
3. Each registered Jupyter kernel — show kernel name
4. Local venv (if .venv/ or venv/ found in working directory) — the Python inside that venv
5. Custom — let the user type a Python path or environment name

Note 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 run uv run jupyter execute example.ipynb directly 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:

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.

2. Prepare the notebook for execution

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.
• API key / credential placeholder cells — e.g. os.environ["OPENAI_API_KEY"] = "sk-***********". Instead, set environment variables externally before running (export in shell, or inject via code before jupyter execute).
• Mock / demo-only cells — any cells that exist purely for illustration and would fail or interfere in a real run.

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

3. Convert and run

1. Convert .md to .ipynb if needed
2. Install any missing dependencies in the target environment externally: <env-python> -m pip install --upgrade <packages>
3. Run: jupyter execute --kernel_name=<name> example.ipynb (omit --kernel_name if using system default)
4. If errors found, fix in the .md file, uncomment setup cells if needed for debugging, and re-convert

Notebook Structure Template

A 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")
` ``

Reference Documents

This skill includes two reference documents under references/. Read them when the task involves their topics.

Bootcamp Format (references/bootcamp-format.md)

Read this when the user is writing a Milvus integration tutorial for the bootcamp repository. It covers:

• Badge format (Colab + GitHub badges at the top)
• Document structure: Header -> Prerequisites -> Main Content -> Conclusion
• Dependency install format with Google Colab restart note
• API key placeholder conventions ("sk-***********")
• Each code block should have a short text introduction before it

Milvus Code Style (references/milvus-code-style.md)

Read this when the notebook involves pymilvus code. Key rules:

• Always useMilvusClient API — never use the legacy ORM layer (connections.connect(), Collection(), FieldSchema(), etc.)
• Always define schema explicitly (create_schema + add_field) — do not use the shortcut create_collection(dimension=...) without schema
• Include has_collection check before creating collections
• Add commented consistency_level="Strong" line in create_collection()
• No need to call load_collection() — collections auto-load on creation
• First MilvusClient connection must include the blockquote explaining uri options (Milvus Lite / Docker / Zilliz Cloud)

Important Notes

• Always edit the.md file, not the .ipynb directly. The .md is easier for AI to read and write.
• Keep both files — .md for editing, .ipynb for running/sharing.
• After editing .md, always re-run uvx jupyter-switch example.md to sync the .ipynb.

Weekly Installs

103

Repository

zc277584121/mar…g-skills

First Seen

Mar 5, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykWarn

Installed on

trae-cn103

antigravity103

codebuddy103

github-copilot103

codex103

kimi-cli103