nbdev-editing

Stars5

Forks0

UpdatedJuly 22, 2026 at 01:51

Workflow and gotchas for nbdev projects, where notebooks in nbs/ are the source of truth. TRIGGER — read BEFORE touching code, tests, or docs in ANY nbdev repo (has a [tool.nbdev] section in pyproject.toml): before the first cell edit, not after. Don't edit the autogenerated .py files (projects often also mix in plain hand-written .py modules - check the per-file marker). Routes to the pyskill docs that carry the substance, and holds the nbdev v3 delta and environment specifics. Assumes and pulls in the persistent-python and coding-patterns skills.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

AnswerDotAI

AnswerDotAI/skill-plugins

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

File Explorer

2 files

SKILL.md

readonly

name

nbdev-editing

description

Editing nbdev Projects

First read and use the persistent-python skill - it is a must: all work here happens in that kernel using the pyskills-registered tooling, and its rules (reprs, doc(...) inspection, raw strings) are assumed, not repeated. Style and testing process follow the coding-patterns skill, also assumed.

The substance lives in the pyskill docs - read both (free doc() cells) before working:

doc(nbdev.skill): notebook authoring - the source-of-truth/export model, mixed notebook/plain projects, narrative rhythm, examples-as-docs, directives, state flow. Read before writing or reviewing any notebook content.
doc(llmsurgery.dlgskill): reading, searching, and editing notebooks - see its "Idiomatic usage" section. clikernel's own docs cover the nbdev-specific kernel rules (shell nbdev-export/nbdev-test, restart after export, %nbrun red-green).

nbdev v3

Everything here is on nbdev v3 (released Jan 2026, likely after your training cutoff). Key user-visible changes from v2: config moved from settings.ini to pyproject.toml - standard metadata in [project], nbdev-specific keys in [tool.nbdev] (defaults now nbs_path='nbs', doc_path='_docs'), version in __init__.py exposed via dynamic = ["version"], and _modidx registered under [project.entry-points.nbdev]. CLI commands use hyphens, not underscores (nbdev-export, nbdev-test, nbdev-readme, ...), though the Python functions keep underscores (nbdev_export). GitHub workflows use the v3 actions (fastai/workflows/nbdev3-ci, quarto-ghp3).

Environment specifics

Most ipynb files are fine to nbdev-test, but some are slow or require API keys, so plan to run nbdev-test on the changed notebook when done making changes, but check with Jeremy first before you actually do it. Once you know an ipynb or project is safe to run, go ahead without checking as needed (known safe: all of pyskills).
Tests use the fastcore.test helpers (test_eq, expect_fail, ...) in plain code cells.
from fastcore.utils import * in an early cell already provides os, Path, etc. - don't re-import those later.
For project-level questions, read nbs/index.ipynb, not README.md: the README is generated from it, renders worse (no cell ids, flattened outputs), and can be stale if regeneration lagged. They should match; when they don't, index.ipynb is the truth. Regen with nbdev-readme after editing it.

Before you wrap up

Red-green ran: each new test failed before the change and passed after, via targeted %nbrun (using --above first to set up state as needed).
Page read: re-read the touched section (view_dlg or find_msgs with context=) as a reader would, checking it against nbdev.skill's conventions. Style damage fails silently: tests pass, export succeeds, and the harm only shows on the docs page or to the next reader.

More from this repository

same repository

claude-code-docs

AnswerDotAI/skill-plugins

Use when answering questions about current Claude Code behavior, configuration, CLI features, hooks, skills, plugins, sessions, compaction, permissions, or other Claude Code-specific interfaces from official documentation.

2026-07-225

coding-patterns

AnswerDotAI/skill-plugins

Jeremy's coding style and conventions (fastai style guide + 3 decades of experience), used across ALL his projects. TRIGGER — read before the first tool call that reads, writes, or searches files: the patterns are needed to discuss and assess code that's read or found, not only to write it. Tasks that never touch the filesystem don't need it. Certainly BEFORE writing or editing any Python: a new file, a one-line change, a test, a refactor, anything. Don't skip because a change "looks trivial" or you're "just" fixing one line. Covers naming, layout, concision, imports, testing process (TDD red-green, pytest), docments, versioning, and the fastcore/fasthtml ecosystem preference.

2026-07-225

nbdev-editing

AnswerDotAI/skill-plugins

2026-07-225

persistent-python

AnswerDotAI/skill-plugins

The persistent clikernel Python session — Jeremy's preferred single tool for nearly ALL Python work. TRIGGER — read and bootstrap as step zero of EVERY session where clikernel is available, before the first tool call: even tasks that only read a file or search a directory, plus stateful inspection, editing code or notebooks, debugging, experiments, API probes, data transforms, pyskills discovery, notebook-style work, local tool orchestration. If it could go through Python, it goes here — never python -c, Bash heredocs, or ad hoc scripts.

2026-07-225

write-prose

AnswerDotAI/skill-plugins

How to write prose that doesn't read as AI slop. TRIGGER — read BEFORE writing or editing ANY prose meant for a human to read: READMEs, docs, articles, PR/commit text, emails, announcements, release notes, or comments longer than a line. Not for code. Covers a marked good/sloppy sample pair, the numbered tells they illustrate, banned words, and the em-dash and hard-wrap bans.

2026-07-225

codex-docs

AnswerDotAI/skill-plugins

Use when answering questions about current Codex behavior, configuration, CLI features, hooks, skills, plugins, sessions, compaction, permissions, or other Codex-specific interfaces from official documentation.

2026-07-225

name

nbdev-editing

description

Editing nbdev Projects

The substance lives in the pyskill docs - read both (free doc() cells) before working:

doc(nbdev.skill): notebook authoring - the source-of-truth/export model, mixed notebook/plain projects, narrative rhythm, examples-as-docs, directives, state flow. Read before writing or reviewing any notebook content.
doc(llmsurgery.dlgskill): reading, searching, and editing notebooks - see its "Idiomatic usage" section. clikernel's own docs cover the nbdev-specific kernel rules (shell nbdev-export/nbdev-test, restart after export, %nbrun red-green).

nbdev v3

Environment specifics

Most ipynb files are fine to nbdev-test, but some are slow or require API keys, so plan to run nbdev-test on the changed notebook when done making changes, but check with Jeremy first before you actually do it. Once you know an ipynb or project is safe to run, go ahead without checking as needed (known safe: all of pyskills).
Tests use the fastcore.test helpers (test_eq, expect_fail, ...) in plain code cells.
from fastcore.utils import * in an early cell already provides os, Path, etc. - don't re-import those later.
For project-level questions, read nbs/index.ipynb, not README.md: the README is generated from it, renders worse (no cell ids, flattened outputs), and can be stale if regeneration lagged. They should match; when they don't, index.ipynb is the truth. Regen with nbdev-readme after editing it.

Before you wrap up

Red-green ran: each new test failed before the change and passed after, via targeted %nbrun (using --above first to set up state as needed).
Page read: re-read the touched section (view_dlg or find_msgs with context=) as a reader would, checking it against nbdev.skill's conventions. Style damage fails silently: tests pass, export succeeds, and the harm only shows on the docs page or to the next reader.