python-notebooks-async skill
✓ VerifiedHelps agents write and review asyncio code within Jupyter notebooks or cell-based workflows to avoid event loop conflicts.
- GitHub stars
- 6
- Files
- 2
- Last commit
- Oct 29, 2026
- License
- CC0-1.0
- Allowed tools
- —
What does the python-notebooks-async skill do?
python-notebooks-async helps agents write and review asyncio code within Jupyter notebooks or cell-based workflows to avoid event loop conflicts.
Summary generated from the skill's SKILL.md.
About the python-notebooks-async skill
Developers working in Jupyter notebooks or cell-based workflows use this skill to manage asynchronous Python code without triggering event loop conflicts. It provides guidance for agents tasked with writing, reviewing, or porting async scripts into environments where the notebook kernel already owns the event loop. By following these patterns, agents can avoid common errors like RuntimeError when using asyncio.run() or tasks that fail to complete silently.
An agent should load this skill when it encounters issues with asyncio.run() failures in cells or when orchestrating concurrent tasks using gather or TaskGroup within IPython kernels. The skill focuses on implementing top-level await, managing reusable logic in .py modules, and choosing between libraries like aiohttp or httpx instead of blocking calls. It treats nest_asyncio as a fallback rather than a primary solution to ensure code remains reliable and avoids masking underlying design problems.
What an agent can do with it
- 1Fixing event loop errorsResolve RuntimeError errors caused by calling asyncio.run() inside a notebook cell.
- 2Refactoring async notebook codeMove inline asynchronous helper functions from notebook cells into external Python modules for better testing.
- 3Preventing blocking I/O issuesIdentify and replace synchronous calls that starve the event loop with non-blocking alternatives.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the python-notebooks-async skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the python-notebooks-async skill in Claude Code
~/.claude/skills/python-notebooks-async/SKILL.md
$ npx degit ahgraber/skills/skills/python-notebooks-async ~/.claude/skills/python-notebooks-asyncInstall the python-notebooks-async skill in Claude Code (project)
.claude/skills/python-notebooks-async/SKILL.md
$ npx degit ahgraber/skills/skills/python-notebooks-async .claude/skills/python-notebooks-asyncInstall the python-notebooks-async skill in Codex
~/.agents/skills/python-notebooks-async/SKILL.md
$ npx degit ahgraber/skills/skills/python-notebooks-async ~/.agents/skills/python-notebooks-asyncInstall the python-notebooks-async skill in Gemini CLI
~/.gemini/skills/python-notebooks-async/SKILL.md
$ npx degit ahgraber/skills/skills/python-notebooks-async ~/.gemini/skills/python-notebooks-asyncInstall the python-notebooks-async skill in Claude.ai
npx degit ahgraber/skills/skills/python-notebooks-async python-notebooks-async && zip -r python-notebooks-async.zip python-notebooks-async # claude.ai → Customize → Skills → + → Create skill → Upload a skill → python-notebooks-async.zip
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachableahgraber/skills/skills/python-notebooks-async is public and reachablegithub.com/ahgraber/skills/tree/HEAD/skills/python-notebooks ↗Pass
- Open source license (OSI)CC0-1.0spdx.org/licenses/CC0-1.0.html ↗Pass
- Commit or release in the last yearLast commit 2026-10-29github.com/ahgraber/skills/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/ahgraber/skills/blob/HEAD/skills/python-notebooks ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/ahgraber/skills/blob/HEAD/skills/python-notebooks ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 66 linesgithub.com/ahgraber/skills/blob/HEAD/skills/python-notebooks ↗Pass
SKILL.md
View on GitHubPython Notebooks Async
Overview
Notebook kernels own the event loop; async code must cooperate with that ownership rather than fight it.
This skill covers orchestration patterns, top-level await, and compatibility constraints for .ipynb and #%% workflows.
Treat these recommendations as preferred defaults. When project constraints require deviation, call out tradeoffs and compensating controls.
When to Use
asyncio.run()raisesRuntimeErrorinside a notebook cell.- Event-loop conflicts when mixing async libraries in Jupyter.
- Porting async scripts into notebook workflows.
- Orchestrating concurrent tasks (
gather,TaskGroup) in IPython kernels. - Deciding where to place reusable async logic across notebook/module boundaries.
When NOT to Use
- Pure script or service code with no notebook involvement.
- Synchronous notebook workflows with no async needs.
- General asyncio API design outside notebook contexts — the
pythonskill covers concurrency audit defaults.
Invocation Notice
- Tell the user when this skill is running:
python-notebooks-async. Skip the notice when the user asked for the skill by name or slash command; spelling and spacing need not match. A phrase from this skill's own trigger list is not a name — naming the work is not naming the skill.
Quick Reference
- Treat notebook kernels as loop-owned environments; never create a competing loop.
- Use top-level
awaitinstead ofasyncio.run()in notebook cells. - Orchestrate concurrent work with
asyncio.gather()orasyncio.TaskGroup. - Keep reusable async logic in regular
.pymodules, imported into notebooks. - Use
nest_asyncioonly as a constrained compatibility fallback, not a default. - Avoid fire-and-forget tasks — always
awaitor collect results explicitly.
Common Mistakes
- Calling
asyncio.run()in a notebook cell. The kernel already runs a loop;asyncio.run()tries to start a second one and raisesRuntimeError. Useawaitdirectly instead. - Applying
nest_asyncioglobally by default. It patches the loop to allow reentrant calls but masks design problems and can hide subtle concurrency bugs. Reserve it for legacy compatibility. - Defining async helpers inline in cells instead of modules.
Inline definitions are lost on kernel restart and cannot be tested outside the notebook.
Extract to
.pyfiles. - Ignoring returned tasks or coroutines.
Calling an async function without
awaitsilently produces a never-executed coroutine object, with no error until results are missing downstream. - Mixing blocking I/O with async in the same cell.
Synchronous calls like
requests.get()block the event loop, starving concurrent tasks. Useaiohttp,httpx, orasyncio.to_thread().
References
references/notebooks-async.md— event-loop ownership, background-work and fire-and-forget patterns, script/notebook compatibility, blocking-library interop,nest_asynciopolicy
Files in this skill
2python-notebooks-async skill questions
How do I install the python-notebooks-async skill in Claude Code?
Run npx degit ahgraber/skills/skills/python-notebooks-async ~/.claude/skills/python-notebooks-async. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the python-notebooks-async skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
Why does asyncio.run() raise a RuntimeError in my notebook?
The notebook kernel already owns and runs an event loop; calling asyncio.run() attempts to start a second loop, causing a conflict. Use top-level await instead.
Should I use nest_asyncio in my notebook workflows?
You should only use nest_asyncio as a constrained compatibility fallback for legacy reasons, not as a default, because it can mask design problems and concurrency bugs.
How can I prevent blocking the event loop in a notebook cell?
Avoid using synchronous blocking I/O like requests.get(); instead, use asynchronous libraries like aiohttp, httpx, or wrap synchronous calls in asyncio.to_thread().