Skill Jupyter Notebook

Créez des notebooks Jupyter propres et reproductibles pour deux modes principaux :

Expériences et analyses exploratoires
Tutoriels et présentations pédagogiques

Préférez les templates groupés et le script helper pour une structure cohérente et moins d'erreurs JSON.

Quand l'utiliser

Créer un nouveau notebook .ipynb à partir de zéro.
Convertir des notes brutes ou des scripts en un notebook structuré.
Refactoriser un notebook existant pour le rendre plus reproductible et facile à survoler.
Construire des expériences ou des tutoriels qui seront lus ou relancés par d'autres personnes.

Arbre de décision

Si la demande est exploratoire, analytique ou fondée sur une hypothèse, choisissez experiment.
Si la demande est instructive, progressive ou adaptée à un public spécifique, choisissez tutorial.
Si vous éditez un notebook existant, traitez-le comme une refonte : préservez l'intention et améliorez la structure.

Chemin du skill (à définir une fois)

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export JUPYTER_NOTEBOOK_CLI="$CODEX_HOME/skills/jupyter-notebook/scripts/new_notebook.py"

Les skills au niveau utilisateur s'installent sous $CODEX_HOME/skills (défaut : ~/.codex/skills).

Workflow

Verrouiller l'intention. Identifiez le type de notebook : experiment ou tutorial. Capturez l'objectif, le public et ce que « fait » signifie.
Générer le scaffold à partir du template. Utilisez le script helper pour éviter d'écrire du JSON notebook brut.

uv run --python 3.12 python "$JUPYTER_NOTEBOOK_CLI" \
  --kind experiment \
  --title "Compare prompt variants" \
  --out output/jupyter-notebook/compare-prompt-variants.ipynb

uv run --python 3.12 python "$JUPYTER_NOTEBOOK_CLI" \
  --kind tutorial \
  --title "Intro to embeddings" \
  --out output/jupyter-notebook/intro-to-embeddings.ipynb

Remplir le notebook avec des étapes petites et exécutables. Gardez chaque cellule de code focalisée sur une étape. Ajoutez de courtes cellules markdown qui expliquent l'objectif et le résultat attendu. Évitez les résultats volumineux et bruyants quand un court résumé suffit.
Appliquer le bon pattern. Pour les expériences, suivez references/experiment-patterns.md. Pour les tutoriels, suivez references/tutorial-patterns.md.
Éditer en toute sécurité quand vous travaillez sur des notebooks existants. Préservez la structure du notebook ; évitez de réordonner les cellules sauf si cela améliore l'histoire de haut en bas. Préférez les édits ciblés aux réécrits complets. Si vous devez éditer du JSON brut, consultez d'abord references/notebook-structure.md.
Valider le résultat. Exécutez le notebook de haut en bas quand l'environnement le permet. Si l'exécution n'est pas possible, dites-le explicitement et indiquez comment valider localement. Utilisez la checklist de passage final dans references/quality-checklist.md.

Templates et script helper

Les templates se trouvent dans assets/experiment-template.ipynb et assets/tutorial-template.ipynb.
Le script helper charge un template, met à jour la cellule de titre et écrit un notebook.

Chemin du script :

$JUPYTER_NOTEBOOK_CLI (installation par défaut : $CODEX_HOME/skills/jupyter-notebook/scripts/new_notebook.py)

Conventions temp et output

Utilisez tmp/jupyter-notebook/ pour les fichiers intermédiaires ; supprimez-les une fois terminé.
Écrivez les artefacts finaux sous output/jupyter-notebook/ quand vous travaillez dans ce repo.
Utilisez des noms de fichiers stables et descriptifs (par exemple, ablation-temperature.ipynb).

Dépendances (installer uniquement si nécessaire)

Préférez uv pour la gestion des dépendances.

Paquets Python optionnels pour l'exécution locale du notebook :

uv pip install jupyterlab ipykernel

Le script scaffold groupé utilise uniquement la bibliothèque standard Python et ne nécessite pas de dépendances supplémentaires.

Environnement

Aucune variable d'environnement requise.

Plan de référence

references/experiment-patterns.md : structure et heuristiques de l'expérience.
references/tutorial-patterns.md : structure du tutoriel et flux pédagogique.
references/notebook-structure.md : forme JSON du notebook et règles d'édition sécurisée.
references/quality-checklist.md : checklist de validation finale.