book-to-skill: 기술 서적을 Claude Code 스킬로 컴파일하는 법

book-to-skill 파이프라인 도식

기술 서적은 읽는 순간보다 다시 꺼내 쓰는 순간에 가치가 드러난다. 그런데 현실에서는 책 한 권을 다 읽고 나면, 필요한 장은 기억에서 흐려지고 PDF 검색은 맥락을 못 잡고, 결국 같은 내용을 다시 찾느라 시간을 쓴다. book-to-skill은 이 문제를 아주 다른 방식으로 푼다. 책을 “문서”로 두지 않고, Claude Code가 바로 쓸 수 있는 스킬로 컴파일한다.

이 프로젝트의 흥미로운 점은 단순히 PDF를 요약하는 도구가 아니라는 데 있다. 원문을 한 번 구조화한 뒤, 챕터별 파일과 용어집, 패턴 모음, 치트시트로 나눠서 저장한다. 즉, 한 권의 책을 검색 대상이 아니라 작업용 지식 레이어로 바꾸는 쪽에 가깝다.

딥다이브

book-to-skill이 만드는 산출물의 핵심은 ~/.claude/skills/<slug>/ 아래에 쌓이는 구조다. 단일 SKILL.md만 두는 게 아니라, 챕터 파일과 보조 파일을 함께 생성한다.

SKILL.md: 핵심 멘탈 모델과 전체 인덱스
chapters/: 장별 상세 파일, 온디맨드 로드용
glossary.md: 중요한 용어를 챕터 참조와 함께 정리
patterns.md: 기법, 알고리즘, 설계 패턴 모음
cheatsheet.md: 빠르게 훑어보는 결정표와 규칙

이 구조는 “책 전체를 한 번에 집어넣는 방식”과 다르다. 필요한 부분만 불러오게 설계돼 있어서, Claude Code 세션에서 문맥 낭비를 줄인다. 다시 말해, 책을 기억시키는 게 아니라 책을 재사용 가능하게 분해한다.

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

핵심 기능

이 저장소는 입력 문서를 꽤 넓게 받는다. 공식 README 기준으로 지원 형식은 다음과 같다.

PDF
EPUB
DOCX
TXT
Markdown
reStructuredText
HTML
RTF
MOBI / AZW / AZW3

추출 전략도 단순하지 않다. 문서 성격에 따라 경로를 다르게 탄다.

문서 유형	우선 도구	의도
기술서적, 코드, 표, 수식이 많은 문서	`docling`	표와 코드 블록을 살리기 위함
텍스트 중심 문서	`pdftotext` → `PyPDF2` → `pdfminer.six`	속도와 단순성을 우선

README는 시작 전에 사용자가 책의 성격을 technical 또는 text-heavy로 구분하게 하고, 그에 맞는 경로를 고른다고 설명한다. 이 부분이 중요하다. 이 프로젝트는 “무조건 가장 좋은 추출기”를 고르는 게 아니라, 문서 타입에 맞는 손실 함수를 고른다.

왜 이 접근이 다르게 느껴지나

RAG와 skill의 차이

README의 FAQ가 이 프로젝트의 포지션을 꽤 정확하게 보여준다. book-to-skill은 RAG처럼 질의 시점에 청크를 뒤지는 도구가 아니다. 대신 컴파일 시점에 책의 구조를 읽고, 저자가 실제로 사용한 프레임워크와 반패턴을 이름 붙여서 정리한다.

이 차이는 실무에서 크게 작동한다.

RAG는 “X가 들어간 부분을 찾아줘”에 강하다.
book-to-skill은 “이 책의 핵심 프레임워크를 지금 내 작업에 써먹고 싶다”에 강하다.

즉, 이 프로젝트는 검색 엔진보다 작업 보조 지식층에 가깝다. 책을 훑는 용도보다, 한 권을 오래 쓰는 용도에 맞는다.

성능과 트레이드오프

README의 벤치마크도 흥미롭다. 103페이지 기술서적을 CPU만으로 처리했을 때, pdftotext는 약 0.1초에 27K 토큰을 뽑아냈고, Docling은 약 164초가 걸렸지만 같은 수준의 토큰 수에 더해 표 48개와 코드 블록 36개를 보존했다. 토큰은 거의 비슷했지만, 보존한 구조는 훨씬 풍부했다.

이 수치는 이 프로젝트의 철학을 잘 보여준다. 속도만 보면 단순 추출기가 이긴다. 하지만 기술 서적에서는 “얼마나 빨리 텍스트를 뽑느냐”보다 얼마나 많이 구조를 살리느냐가 더 중요할 때가 많다.

다만 트레이드오프도 분명하다.

기술서적용 경로는 느릴 수 있다.
여러 권을 한 번에 검색하는 용도라면 NotebookLM이나 일반 RAG가 더 적합하다.
원문 품질이 낮으면 아무리 잘 컴파일해도 결과가 흐려진다.

그래서 이 도구는 “모든 책”을 위한 범용 라이브러리보다, 한 권을 깊게 쓰는 개인 워크플로우에 더 잘 맞는다.

실제로 쓰는 방식

README 기준 가장 단순한 사용법은 이렇다.

/book-to-skill <path-to-document> [skill-name-slug]

이후 생성된 스킬은 Claude Code에서 다른 스킬처럼 불러올 수 있다. 예를 들어 특정 책의 개념을 확인하고 싶을 때는 코어 스킬을 열고, 세부 내용이 필요하면 챕터를 호출하는 식이다. 중요한 건 “책 전체를 다시 읽는 것”이 아니라, 필요한 장만 다시 여는 습관을 만드는 데 있다.

마치며

book-to-skill은 단순한 변환기처럼 보이지만, 실제로는 지식 소비 습관을 바꾸는 도구다. 책을 읽고 끝내는 대신, 책을 나만의 작업 환경 안으로 들여와 재사용하게 만든다.

이런 도구가 좋은 이유는 화려해서가 아니다. 오히려 반대다. 잘 만든 컴파일러처럼 조용하게, 반복적인 맥락 전환 비용을 줄여 준다. 기술 서적을 자주 참고하는 사람이라면 특히 체감이 크다.