jupyter-notebook

# Utilisation À utiliser quand l'utilisateur demande de créer, structurer ou éditer des notebooks Jupyter (`.ipynb`) pour des expériences, explorations ou tutoriels ; préférez les modèles fournis et exécutez le script d'aide `new_notebook.py` pour générer un notebook de démarrage propre.

npx skills add https://github.com/openai/skills --skill jupyter-notebook

Compétence Jupyter Notebook

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

  • Expériences et analyse exploratoire
  • Tutoriels et procédures pédagogiques

Préférer les modèles groupés et le script d'assistance pour une structure cohérente et moins d'erreurs JSON.

Quand 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 facilement parcourable.
  • Construire des expériences ou des tutoriels qui seront lus ou réexécutés par d'autres personnes.

Arbre de décision

  • Si la demande est exploratoire, analytique ou basée sur une hypothèse, choisir experiment.
  • Si la demande est instructive, étape par étape, ou spécifique à un public, choisir tutorial.
  • Si vous modifiez un notebook existant, le traiter comme une refactorisation : préserver l'intention et améliorer la structure.

Chemin de compétence (à 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 compétences au niveau utilisateur s'installent sous $CODEX_HOME/skills (par défaut : ~/.codex/skills).

Flux de travail

  1. Verrouiller l'intention. Identifier le type de notebook : experiment ou tutorial. Capturer l'objectif, le public et ce que « terminé » signifie.

  2. Construire à partir du modèle. Utiliser le script d'assistance pour éviter de créer manuellement du JSON de 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

  1. Remplir le notebook avec de petites étapes exécutables. Maintenir chaque cellule de code concentrée sur une étape. Ajouter de courtes cellules markdown qui expliquent le but et le résultat attendu. Éviter les sorties volumineuses et bruyantes quand un court résumé suffit.

  2. Appliquer le bon modèle. Pour les expériences, suivre references/experiment-patterns.md. Pour les tutoriels, suivre references/tutorial-patterns.md.

  3. Éditer en toute sécurité lorsque vous travaillez avec des notebooks existants. Préserver la structure du notebook ; éviter de réordonner les cellules sauf si cela améliore l'histoire de haut en bas. Préférer les modifications ciblées aux réécritures complètes. Si vous devez éditer du JSON brut, consulter d'abord references/notebook-structure.md.

  4. Valider le résultat. Exécuter le notebook de haut en bas quand l'environnement le permet. Si l'exécution n'est pas possible, le dire explicitement et expliquer comment valider localement. Utiliser la liste de contrôle de passage final dans references/quality-checklist.md.

Modèles et script d'assistance

  • Les modèles se trouvent dans assets/experiment-template.ipynb et assets/tutorial-template.ipynb.
  • Le script d'assistance charge un modèle, 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 temporaires et de sortie

  • Utiliser tmp/jupyter-notebook/ pour les fichiers intermédiaires ; supprimer une fois terminé.
  • Écrire les artefacts finaux sous output/jupyter-notebook/ quand vous travaillez dans ce dépôt.
  • Utiliser des noms de fichiers stables et descriptifs (par exemple, ablation-temperature.ipynb).

Dépendances (installer uniquement si nécessaire)

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

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

uv pip install jupyterlab ipykernel

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

Environnement

Aucune variable d'environnement requise.

Carte 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 : liste de contrôle de validation finale.