Book-to-SKILL: 기술 서적 PDF나 EPUB을 Claude Code 스킬로 변환해 작업 중에 바로 활용하는 도구

9bow · 5월 8, 2026, 12:30오전

book-to-skill 소개

기술 서적을 한 번 읽고 나서 몇 달 뒤 다시 떠올리려 할 때, 정확한 챕터 위치는 잊어버렸지만 어떤 개념이 어디에 있다는 흐릿한 기억만 남는 경험은 흔합니다. PDF 안에서 키워드를 검색해도 답이 아닌 페이지 목록만 나오고, 그렇다고 책 전체를 Claude의 컨텍스트(Context)에 매번 붙여 넣자니 한 권에 약 200K 토큰을 매 대화마다 소비하게 됩니다. book-to-skill은 이런 문제를 직접 다루는 오픈소스 도구로, 기술 서적 PDF 또는 EPUB 파일을 Claude Code의 스킬(Skill) 형태로 변환하여, 작업 도중 필요한 챕터만 온디맨드(On-demand)로 불러올 수 있게 해 줍니다.

핵심 발상은 검색(Retrieval)과 추론(Reasoning)을 분리하는 것입니다. 일반적인 RAG(Retrieval-Augmented Generation)는 책 전체를 청크로 나누고 임베딩 벡터의 유사도 검색으로 단편을 찾아오는 방식이라 "이 부분이 뭐라고 적혀 있나?" 라는 질문에는 잘 동작하지만, 저자가 책 전체를 통해 빌드해 둔 프레임워크나 안티패턴(Anti-pattern), 의사결정 규칙을 그대로 가져오기는 어렵습니다. book-to-skill은 컴파일 시점에 한 번 깊이 분석하여 명명된 멘탈 모델(Mental Models), 핵심 패턴, 용어집, 결정 표(Decision Tables), 챕터별 요약을 모두 미리 추출하고, Claude는 사용 시점에 이 구조화된 자료를 그대로 활용하여 추론합니다.

이 프로젝트는 Python으로 작성된 추출 스크립트와 Claude Code 스킬 정의(SKILL.md)로 구성된 단순한 구조이지만, 책의 성격에 따라 적절한 추출 도구를 자동으로 선택하고 산출물을 토큰 예산(Token Budget)에 맞게 분할 저장한다는 점이 특징입니다. 코드 블록과 표가 많은 기술 서적은 IBM의 docling을 사용해 마크다운 표와 코드 블록을 보존하고, 산문 위주의 책은 pdftotext나 PyPDF2, pdfminer.six를 사용해 즉시 추출하는 식입니다. EPUB 입력은 ebooklib 또는 표준 라이브러리 zipfile로 처리되며, 별도 환경 구축 없이도 표준 도구만으로 동작합니다.

Book-to-SKILL의 동작 원리

/book-to-skill <path-to-pdf-or-epub> 명령을 호출하면, 책의 성격을 묻는 단계부터 시작해 추출과 분석, 산출물 작성까지 한 번에 진행됩니다. 산출물은 사용자의 홈 디렉토리에 위치한 ~/.claude/skills/<slug>/ 경로에 정리되며, 다음 대화에서 같은 슬래시 명령으로 즉시 호출할 수 있습니다. 추출과 분석 흐름은 다음과 같습니다.

PDF or EPUB
     │
     ▼
Step 1.5 — "Technical or text-heavy book?"
     │
     ├── technical → Docling  (tables + code blocks as markdown, ~1.5s/page)
     └── text      → pdftotext → PyPDF2 → pdfminer  (instant)
     │
     ▼
scripts/extract.py --mode <technical|text>
  EPUB → ebooklib → stdlib zipfile
     │
     ├── /tmp/book_skill_work/full_text.txt
     └── /tmp/book_skill_work/metadata.json
               │
               ▼
          Claude analyzes structure
          (title, author, chapters, ToC)
               │
               ▼
          Generates per-chapter summaries  (800–1,200 tokens each)
          Generates glossary, patterns, cheatsheet
          Generates master SKILL.md with core mental models
               │
               ▼
          ~/.claude/skills/<slug>/  ✅ written

추출 단계에서는 책 성격에 맞는 도구가 가지는 트레이드오프(Trade-off)가 명확합니다. 저자가 공개한 103페이지 분량의 기술 서적 벤치마크에서 pdftotext는 약 0.1초 만에 27K 토큰을 추출하지만 표 0개, 코드 블록 0개로 구조 정보가 사라지는 반면, docling은 약 164초가 걸리는 대신 표 48개와 코드 블록 36개를 마크다운으로 보존합니다. 이 때문에 도구가 책 성격을 먼저 묻고, 산문 위주라면 빠른 추출기를, 코드와 표가 중요하다면 docling을 선택하는 방식으로 균형을 맞춥니다.

분석 단계에서는 책의 구조(제목, 저자, 차례)를 먼저 식별한 뒤, 챕터별로 800~1,200 토큰 분량의 요약을 생성하고, 책 전체를 가로지르는 용어집과 패턴, 치트시트(Cheatsheet)를 추출합니다. 마지막으로 마스터 SKILL.md에는 책의 핵심 멘탈 모델과 챕터 인덱스가 들어가며, 각 챕터 파일은 토큰 예산을 매번 차지하지 않고 사용자가 그 주제를 물어볼 때만 동적으로 로드됩니다.

book-to-skill이 생성하는 산출물 구조

생성되는 스킬 디렉토리는 다음 다섯 종류의 파일로 구성되며, 각 파일의 토큰 분량과 역할이 명확하게 분리되어 있습니다. 책 전체를 한 번에 부풀려 컨텍스트에 넣지 않고, 질문 유형에 따라 필요한 부분만 로드하도록 설계된 점이 특징입니다.

SKILL.md: 책의 핵심 멘탈 모델과 챕터 인덱스를 담은 진입점입니다. 약 4,000 토큰 분량.
chapters/ch01-*.md: 챕터별 요약 파일로, 사용자가 해당 주제를 묻기 전까지는 로드되지 않습니다. 챕터당 약 1,000 토큰.
glossary.md: 핵심 용어를 알파벳순으로 정렬하고 각 용어가 등장한 챕터를 함께 표시한 용어집. 약 1,500 토큰.
patterns.md: 책에서 반복적으로 등장하는 기법, 알고리즘, 디자인 패턴을 모은 파일. 약 2,000 토큰.
cheatsheet.md: 결정 표와 빠르게 참조 가능한 규칙을 모은 파일. 약 1,000 토큰.

저자가 명시한 설계 원칙은 다섯 가지입니다. 첫째, 완결성보다 밀도(Density over completeness)를 우선시하여 1,000 토큰의 잘 만든 요약이 10,000 토큰의 발췌보다 낫다는 입장을 취합니다. 둘째, 실무자 어조(Practitioner Voice)로 "X는 Y한 경우에 사용한다" 처럼 행동 지향 문장을 선호합니다. 셋째, 컴팩션(Compaction)이 일어나도 살아남는 첫 5,000 토큰에 가장 중요한 내용을 전면 배치합니다. 넷째, 챕터 요약은 사용 시점에만 로드합니다. 다섯째, 원문을 그대로 옮기지 않고 항상 요약·구조화하여 신호(Signal)만 남깁니다.

Book-to-SKILL 설치 및 사용 예시

Book-to-SKILL 설치는 Claude Code 세션 안에서 한 줄을 입력하는 것으로 충분합니다. 이 줄은 저장소의 SKILL.md를 읽도록 지시하여, 이후의 단계는 Claude가 안내에 따라 진행합니다.

Install book-to-skill: https://raw.githubusercontent.com/virgiliojr94/book-to-skill/master/SKILL.md

수동 설치를 선호한다면 다음과 같이 SKILL.md와 추출 스크립트를 직접 가져와도 됩니다. 설치 후에는 슬래시 명령(/book-to-skill)으로 변환할 책 파일을 지정하면 됩니다.

mkdir -p ~/.claude/skills/book-to-skill/scripts

curl -o ~/.claude/skills/book-to-skill/SKILL.md \
  https://raw.githubusercontent.com/virgiliojr94/book-to-skill/master/SKILL.md

curl -o ~/.claude/skills/book-to-skill/scripts/extract.py \
  https://raw.githubusercontent.com/virgiliojr94/book-to-skill/master/scripts/extract.py

추출이 완료되면 변환된 책은 일반 슬래시 명령처럼 호출됩니다. 예를 들어 "Designing Data-Intensive Applications" 라는 책을 변환했다면, 다음과 같이 핵심 멘탈 모델만 빠르게 떠올리거나, 특정 토픽이 어디에 있는지 찾거나, 특정 챕터로 깊이 들어갈 수 있습니다.

/book-to-skill ~/Downloads/designing-data-intensive-applications.pdf

# 변환 후 사용
/designing-data-intensive-apps                  # 핵심 멘탈 모델만 로드
/designing-data-intensive-apps replication      # 토픽 위치 탐색 + 설명
/designing-data-intensive-apps ch05             # 5장 자세히 읽기
/designing-data-intensive-apps "what chapters do you have?"

이 도구는 NotebookLM처럼 80권을 가로질러 검색하는 용도로는 적합하지 않다고 저자가 명시합니다. 한 권을 깊이 파고들어 그 책의 프레임워크가 코딩이나 글쓰기 작업의 일부가 되도록 만드는 것이 목표이므로, 사례 비교를 위해서는 RAG와 함께 두고 상황에 맞게 선택해 사용하는 편이 권장됩니다.

book-to-skill 라이선스

book-to-skill 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~