jupyter-notebook

jupyter-notebook 스킬 개요

jupyter-notebook 스킬은 실험, 탐색적 분석, 튜토리얼용 .ipynb 파일을 만들고, 다듬고, 구조화하는 데 도움이 됩니다. 핵심은 “내 환경에서는 잘 돌아가는 것”이 아니라, 다시 실행해도 되고 훑어봐도 이해되며 다른 사람과 공유할 수 있는 깔끔한 노트북을 만드는 데 있습니다.

이 스킬은 데이터 분석, 데모, 교육 자료용 노트북을 만드는 사람에게 가장 잘 맞습니다. 특히 결과물에 분명한 서사와 적은 JSON 오류가 필요할 때 유용합니다. 단순한 프롬프트 보조 도구라기보다, 적절한 뼈대와 구획, 실행 습관을 갖춘 실사용 가능한 노트북 산출물을 만드는 데 초점이 있습니다.

이 스킬이 잘하는 일

새 노트북이 필요하거나, 대충 메모해 둔 내용을 구조화된 노트북으로 바꾸고 싶거나, 이미 만든 노트북이 너무 읽기 어려워져서 정리가 필요할 때 jupyter-notebook 스킬을 사용하세요. 재현성과 가독성을 함께 챙겨야 하는 jupyter-notebook for Data Analysis 워크플로에서 특히 적합합니다.

무엇이 다른가

이 스킬은 원시 notebook JSON을 직접 손으로 편집하는 대신, 포함된 템플릿과 헬퍼 스크립트를 활용하는 쪽에 가깝습니다. 노트북은 상태를 가진 JSON 문서라서 구조, 셀 순서, 실행 메타데이터가 쉽게 지저분해질 수 있기 때문입니다. 또한 experiment와 tutorial이라는 두 가지 대표 모드를 분리해, 작업 목적에 맞는 노트북 형태를 만들도록 돕습니다.

언제 선택하는 것이 맞나

다른 사람이 실행하거나 검토할 수 있는 노트북을 배포하는 것이 목표라면 jupyter-notebook을 선택하세요. 단순히 빠른 답만 필요하다면 일반 프롬프트로도 충분할 수 있습니다. 하지만 섹션이 있고, 재사용 가능한 구조를 갖추며, 의도가 분명한 재현 가능한 노트북이 필요하다면 이 스킬이 더 좋은 출발점입니다.

jupyter-notebook 스킬 사용 방법

설치하고 스킬 파일 위치 확인하기

다음 명령으로 설치합니다:

npx skills add openai/skills --skill jupyter-notebook

설치 후에는 보통 스킬 디렉터리 아래에 경로가 잡히고, 저장소의 헬퍼 스크립트는 scripts/new_notebook.py에서 사용할 수 있습니다. 프롬프트를 넣기 전에 먼저 SKILL.md를 읽고, 이어서 references/notebook-structure.md, references/experiment-patterns.md, references/tutorial-patterns.md, references/quality-checklist.md를 확인해 워크플로를 이해하는 것이 좋습니다.

노트북답게 브리프를 주기

좋은 입력은 노트북 유형, 대상 독자, 목표, 기대 결과물을 분명하게 설명합니다. 예를 들어 “pandas에 대한 노트북을 만들어줘”라고 하기보다, “CSV에서 월별 매출 추이를 분석하는 experiment 노트북을 만들어줘. 기준 차트 1개, 짧은 지표 표 1개, 마지막 메모 섹션이 필요해”처럼 요청하세요. 튜토리얼이라면 학습자 수준과 결과를 구체적으로 적어야 합니다. 예: “초보자를 위한 tutorial 노트북을 만들어줘. 아주 작은 데이터셋으로 조인 개념을 설명하고, 연습 문제 1개를 포함해줘.”

템플릿 우선 워크플로를 따르기

실제 jupyter-notebook usage 흐름은 다음과 같습니다. 먼저 작업이 experiment인지 tutorial인지 정한 뒤, 포함된 템플릿으로 뼈대를 만들고, 그다음 섹션을 작업에 맞게 편집합니다. new_notebook.py 헬퍼 스크립트를 사용해 JSON을 손으로 만드는 대신 깔끔한 시작 노트북을 생성하세요. 노트북 구조는 유지하고, 앞쪽 셀은 독립적으로 실행 가능하게 만들며, 이전 실행 결과에 숨게 의존하는 흐름은 피해야 합니다.

먼저 읽어야 할 저장소 파일

설치 판단을 할 때 중요한 것은 메인 스킬 문서만이 아닙니다. 먼저 assets/experiment-template.ipynb와 assets/tutorial-template.ipynb를 확인해 예상되는 노트북 형태를 보고, 이어서 references 파일을 통해 셀, 서사, 품질 검사가 어떻게 정리되는지 파악하세요. 일관된 출력을 원한다면, 막연하게 “잘 구조화된 노트북”이라고만 하지 말고 이런 패턴을 프롬프트에 반영하는 편이 좋습니다.

jupyter-notebook 스킬 FAQ

jupyter-notebook은 데이터 분석에만 쓰이나요?

아닙니다. jupyter-notebook은 jupyter-notebook for Data Analysis에 강하지만, 튜토리얼, 탐색 작업, 노트북 기반 문서화에도 잘 맞습니다. 최종 결과물이 분명한 섹션을 갖춘 실행 가능한 .ipynb여야 한다면 좋은 선택입니다.

Jupyter 전문가가 아니어도 사용할 수 있나요?

네. 목표를 분명하게 설명할 수만 있다면 초보자도 쉽게 사용할 수 있습니다. 가장 중요한 것은 실험용인지 튜토리얼인지, 어떤 데이터나 주제를 다루는지, 노트북의 상세 수준을 어느 정도로 원하는지 알려주는 일입니다.

그냥 일반 프롬프트를 쓰면 안 되나요?

일반 프롬프트로도 내용 초안은 만들 수 있지만, jupyter-notebook skill은 구조를 지키는 힘이 있습니다. 노트북 유형 선택, 템플릿 기반 뼈대 구성, 재현 가능한 셀에 대한 안내가 포함되기 때문입니다. 그 결과 잘못된 형식의 노트북, 누락된 설정 셀, 불명확한 서사 흐름이 생길 가능성이 줄어듭니다.

언제 쓰지 않는 게 좋나요?

한 번만 필요한 설명, 단순 스크립트, 또는 노트북이 아닌 보고서가 필요하다면 jupyter-notebook을 쓰지 마세요. 또한 노트북 셀을 전혀 실행하거나 검증할 수 없는 상황이라면 적합하지 않습니다. 품질 체크리스트는 가능한 경우 처음부터 끝까지 실행하는 것을 전제로 하기 때문입니다.

jupyter-notebook 스킬 개선 방법

소음보다 제약 조건을 더 정확하게 주기

가장 좋은 jupyter-notebook install 결과는 정밀한 입력에서 나옵니다. 노트북 종류, 데이터셋 형태, 대상 독자, 성공 기준을 분명히 적으세요. 좋은 예: “SQL은 알지만 Jupyter는 모르는 분석가를 위한 튜토리얼. 하나의 데이터셋과 한 번의 체크포인트 연습 문제로 groupby를 설명해줘.” 약한 예: “교육적으로 만들어줘.” 목표 독자와 출력 형식이 구체적일수록 노트북 구조도 더 좋아집니다.

노트북의 첫 실행 형태를 지정하기

스킬이 어떤 순서로 내용을 담아야 하는지 알려주세요. 예: imports, setup, baseline analysis, interpretation, wrap-up. 실험용이라면 질문과 핵심 지표를 포함하세요. 튜토리얼이라면 학습 목표, 사전 지식, 연습 문제 1개를 넣으세요. 이렇게 하면 jupyter-notebook usage가 좋아집니다. 첫 시도부터 실행과 검토가 쉬운 노트북이 되기 때문입니다.

흔한 실패 모드를 미리 점검하기

가장 흔한 문제는 출력이 지나치게 길어지는 것, 이전 실행에서 남은 상태가 숨어 있는 것, 그리고 실행 가능한 구조보다 설명만 과한 노트북입니다. 첫 결과가 약하다면 더 타이트한 템플릿, 더 작은 코드 셀, 그리고 markdown 설명과 실행 셀의 구분을 더 명확히 해 달라고 요청하세요. 기존 노트북을 리팩터링하는 경우에는 무엇을 유지하고 무엇을 정리할지 분명히 말해야 합니다.

검토 가능한 체크포인트로 반복 개선하기

첫 버전 이후에는 한 번에 하나씩만 개선하세요. 노트북 순서, 셀 명확성, 재현성, 대상 적합성 중 하나를 골라 다듬는 방식이 좋습니다. 채택을 막는 요소가 무엇이었는지에 따라 더 짧은 기준선, 더 깔끔한 서사, 더 강한 마무리 요약을 요청하세요. 이것이 실제로 다시 쓰이는 jupyter-notebook guide로 바꾸는 가장 빠른 방법입니다.