book-to-skill — 책 PDF를 Claude가
"챕터별로 골라 읽는 친구"로 만드는 법

먼저, "Claude Code 스킬"이 뭔지부터

왜 이 작은 레포가 트렌딩 14위에 올랐는가.

book-to-skill은 에이전트 중립(agent-neutral) 스킬이다 — Claude Code뿐 아니라 GitHub Copilot CLI, Amp 등도 지원하며, 설치 경로도 ~/.agents/skills/ 같은 공용 경로를 권장한다. SKILL.md의 when_to_use 필드가 어느 에이전트에서나 트리거를 결정한다.

2025년 가을 Anthropic이 Claude Code Skills를 정식 출시한 뒤로 — 트렌드시프트 상위 30위 안에 "~/.claude/skills 디렉토리에 마크다운 한 장을 넣어두면 Claude가 알아서 트리거" 패턴이 매주 새로 올라왔다. multica-ai/andrej-karpathy-skills, MiniMax-AI/skills, hesreallyhim/awesome-claude-code, Yuan1z0825/nature-skills … 모두 같은 컨셉의 변주다.

그 안에서 book-to-skill이 특이한 위치를 잡았다 — "네가 가진 PDF 책 자체를 스킬로 만들어준다". 즉 다른 사람이 만들어 둔 스킬을 설치하는 게 아니라, 내 책장에 있는 Designing Data-Intensive Applications·Clean Code·Domain-Driven Design PDF를 /book-to-skill book.pdf 한 줄로 — Claude가 챕터별로 골라 읽고 답하는 도구로 바꾼다.

이 프로젝트의 핵심 메시지

한 문장으로 줄이면.

2026년 5월, 트렌딩 #14에 오른 이유

작은 레포(13 stars·100% Python·4 커밋)인데 왜 떴나.

풀어야 했던 진짜 문제

레포 README가 직설적으로 정리한다.

• "PDF 검색" — 페이지 번호 목록만 나옴, 답이 아님.
• "Claude에게 책 내용 물어보기" — 환각하거나 "그 책은 없어요" 한다.
• "읽으면서 노트" — 200줄 문서가 쌓이는데 다시 안 본다.

book-to-skill의 답: PDF를 한 번 분해해 마크다운 트리로 펼쳐두면, Claude는 그 트리를 "자기 파일 시스템"으로 본다. 답을 만들기 위해 chapter 5만 골라 읽고 답한다. 환각이 0에 가까워진다.

경쟁 제품 대비 — 무엇이 다른가

왜 지금 떴나 — 3가지 트렌드 정렬

① Anthropic의 Skills 정식 출시(2025). ~/.claude/skills/ 디렉토리가 표준이 되자 — 누구든 자기만의 스킬을 만들 욕구가 폭발. book-to-skill은 그 욕구를 가장 친숙한 자료(PDF 책)로 만든다.

② 카르파시·multica-ai 등 "마크다운 한 장이 모델 행동을 바꾼다"의 확산. CLAUDE.md → SKILL.md로 진화한 패턴. book-to-skill은 그 패턴을 한 권의 책 분량까지 확장한 첫 사례.

③ "독서 → 적용"의 시간차 문제. 좋은 기술서를 사도 3개월 후엔 chapter 7이 있었는지조차 모른다. book-to-skill은 책을 "작업 중 호출 가능한 동료"로 바꾼다.

이 레포가 의존하는 모든 것

놀랍게도 — 본체 코드 한 줄도 Python 표준 라이브러리만 쓴다.

3-1. 본체 레이어 — 단 두 개 파일

레포 전체가 4 커밋. 산출물은 두 개뿐이다.

• SKILL.md — Claude Code가 읽는 프롬프트 + 10단계 워크플로 + 토큰 예산 룰. "코드가 아니라 명세"가 본체.
• scripts/extract.py — PDF/EPUB → 텍스트 변환 진입점(래퍼). 실제 추출 로직은 scripts/extractor/ 패키지(utils.py + parsers/ 서브패키지: pdf.py·epub.py·docx.py·html.py·rtf.py·text.py·calibre.py 등)에 분산되어 있다.

3-2. PDF 추출 — 4단 폴백

extract.py(실제로는 scripts/extractor/parsers/pdf.py)가 시도 순서대로 호출하는 라이브러리:

요점: 하나라도 설치돼 있으면 동작하고, 없으면 정확한 설치 명령을 알려준다. "의존성을 강요하지 않고 환경에 맞춰 적응"이 핵심 미학.

3-3. 멀티포맷 지원 — EPUB · DOCX · HTML · TXT · RTF · MOBI

PDF 외에도 EPUB·DOCX·HTML·Markdown·TXT·RTF·MOBI/AZW3·AsciiDoc·reStructuredText를 지원한다. scripts/extractor/parsers/ 안에 포맷별 파서(epub.py·docx.py·html.py·rtf.py·text.py·calibre.py)가 별도로 존재한다. EPUB 추출 옵션은 다음과 같다.

• ebooklib + BeautifulSoup4 — 정식 EPUB 라이브러리 + HTML 파서. 추천.
• zipfile + stdlib HTMLParser — 의존성 0개 fallback. Python 표준만으로 OPF spine 읽어 챕터 순서대로 처리.

3-4. Claude Code 측 의존성

스킬이 동작하려면 Claude Code 본체가 다음 도구를 허용해야 한다. SKILL.md 프론트매터에 명시:

allowed-tools: Bash(python3 *) Bash(pdftotext *)
              Bash(mkdir *) Bash(cp *) Bash(find *)
              Bash(wc *) Bash(echo *) Bash(cat *)
              Bash(date *) Read Write Glob Grep

모든 bash 명령이 화이트리스트. 임의 명령 실행은 차단. 이게 Claude Code 스킬의 안전 모델 — "허용된 도구만, 명시된 패턴으로".

10단계 파이프라인 — 입력부터 산출까지

SKILL.md를 읽으면 정확히 이 흐름이 보인다.

PDF/EPUB 입력
   │
   ▼
[Step 0] 인자 검증 — PDF 경로가 맞나? 아니면 stop.
   │
   ▼
[Step 1] 파일 존재 + 확장자 확인
   │
   ▼
[Step 2] scripts/extract.py 호출
   │     → /tmp/book_skill_work/full_text.txt
   │     → /tmp/book_skill_work/metadata.json
   ▼
[Step 2.5] 비용 견적 사전 표시 ⭐
   │     "입력 ~150K 토큰, 출력 ~80K 토큰,
   │      Sonnet 기준 ~$1.65, 약 8분 예상.
   │      진행할까요?" → 사용자 확인 대기
   ▼
[Step 3] 첫 8000자 읽고 구조 분석
   │     → 제목·저자·챕터·핵심 테마 파악
   │     → ToC 있으면 매핑
   │
   │ ┌─ 모드 분기 ─┐
   │ │ Analyze Only → 추출 보고서만 출력하고 STOP
   │ │ Full → 다음 단계로
   │ └────────────┘
   ▼
[Step 4] 사용자에게 목적 질문
   │     "프레임워크 적용? 멘탈 모델? 챕터 참조?"
   ▼
[Step 5] 스킬 슬러그 결정
   │     {author}-{concept} 또는 {title-lowercase}
   ▼
[Step 6] ~/.claude/skills/<slug>/chapters/ 생성
   │
   ▼
[Step 7] 챕터별 요약 ⭐⭐⭐ — 각 800~1,200 토큰
   │     ch01-*.md, ch02-*.md, ...
   │     템플릿: Core Idea / Frameworks /
   │            Key Concepts / Mental Models /
   │            Anti-patterns / Takeaways / Connects To
   ▼
[Step 8] 부속 파일 3개
   │     glossary.md  (1500토큰: 용어집)
   │     patterns.md  (2000토큰: 기법·패턴)
   │     cheatsheet.md (1000토큰: 의사결정표)
   ▼
[Step 9] 마스터 SKILL.md ⭐⭐ — <4000 토큰
   │     Core Frameworks 2000토큰 (앞쪽 배치!)
   │     + Chapter Index 표
   │     + Topic Index (알파벳)
   │     + Supporting Files 링크
   ▼
[Step 10] /tmp 정리 + 완료 보고
         ✅ 사용자에게 위치·크기·사용법 출력

핵심 설계 패턴 ① — "Step 2.5: 사전 비용 견적"

대부분의 자동화 도구가 빠뜨리는 디테일. 큰 변환 작업 전에 견적부터 보여주고 동의를 받는다:

📖 Book detected: clean-code.pdf
📄 Pages: ~462 | Words: ~115,000 | Source tokens: ~153K

💰 Estimated token cost (Full Conversion):
   Input  : ~199K tokens
   Output : ~75K tokens
   Total  : ~274K tokens

   Sonnet 4.5  → ~$1.72 USD
   Haiku 4.5   → ~$0.46 USD

   ⏱  Estimated time: ~10 minutes

📁 Files to be generated:
   SKILL.md + 17 chapter files + glossary + patterns + cheatsheet

➡  Proceed? (or "analyze only" to preview)

이게 별로 안 보이는 점잖은 디테일이지만 — "AI 에이전트가 사용자 돈을 쓰기 전에 견적을 보여줘야 한다"는 Karpathy·Anthropic이 강조한 '책임 있는 자율성'의 실천 사례.

핵심 설계 패턴 ② — "On-demand chapters"

17개 챕터 × 1000 토큰 = 17,000 토큰. 만약 SKILL.md 안에 모두 박아 넣으면 매 호출마다 이걸 다 읽어야 한다. book-to-skill의 해결책:

1. SKILL.md엔 Topic Index만 둔다 — "replication → ch05", "consistency → ch05, ch07"
2. Claude가 사용자의 질문을 받으면, Topic Index를 보고 해당 챕터 파일만 Read 도구로 읽는다
3. 다른 16개 챕터는 메모리에 안 들어옴 → 토큰 절약

핵심 설계 패턴 ③ — "Front-loaded SKILL.md"

Claude Code는 대화가 길어지면 컨텍스트를 압축(compaction)한다. 잘리는 방향은 항상 끝쪽. 그래서 SKILL.md의 본문 순서가 중요하다:

SKILL.md 구조 (위 → 아래)
─────────────────────────
1. Frontmatter (메타데이터, ~200토큰)
2. How to Use This Skill (사용법, ~300토큰)
3. Core Frameworks & Mental Models ⭐ (~2,000토큰)
   ← 압축돼도 살아남는 영역
4. Chapter Index (표, ~500토큰)
5. Topic Index (알파벳, ~500토큰)
6. Supporting Files 링크 (~100토큰)
7. Scope & Limits (~200토큰)
   ← 압축되면 가장 먼저 잘림

"가장 중요한 건 맨 위, 가장 덜 중요한 건 맨 아래" — 이 한 줄이 모든 자동 생성을 좌우한다.

핵심 설계 패턴 ④ — 4가지 모드

같은 입력(PDF)에 대해 4가지 출력 경로:

생성되는 스킬 디렉토리 5종 — 각각의 임무

변환이 끝나면 — 이 트리가 ~/.claude/skills/<slug>/에 생긴다.

~/.claude/skills/clean-code/        ← 슬러그 = 책 이름 또는 저자-개념
├── SKILL.md                        ← 항상 로드, ~4000 토큰
│   ├── Frontmatter
│   ├── How to Use This Skill
│   ├── Core Frameworks ⭐ (전체의 50%)
│   ├── Chapter Index 표
│   ├── Topic Index 알파벳
│   └── Supporting Files 링크
│
├── chapters/                       ← on-demand, 챕터당 ~1000 토큰
│   ├── ch01-clean-code.md
│   ├── ch02-meaningful-names.md
│   ├── ch03-functions.md
│   └── ... (17 챕터)
│
├── glossary.md                     ← on-demand, ~1500 토큰
│   "Cyclomatic Complexity — 함수 분기 수 (Ch3)"
│
├── patterns.md                     ← on-demand, ~2000 토큰
│   "## Single Responsibility Principle
│    When: 함수가 두 가지 일을 할 때
│    How: 추출해서 분리"
│
└── cheatsheet.md                   ← on-demand, ~1000 토큰
    의사결정표, 비교 매트릭스, "한 페이지 요약"

마스터 SKILL.md의 6-섹션 구조

1. Frontmatter — name·description·when_to_use·allowed-tools·argument-hint. Claude Code 본체가 이 메타로 트리거 결정.
2. How to Use This Skill — 4가지 호출 패턴 명시 (/skill-name, /skill-name topic, /skill-name ch05, "what chapters do you have?").
3. Core Frameworks & Mental Models — 이 책의 핵심 2000 토큰. 압축돼도 살아남는다.
4. Chapter Index — 표 형식, 각 챕터 한 줄 + 핵심 프레임워크 2~3개.
5. Topic Index — 알파벳 정렬, **Term** → ch<N>. 이게 Claude의 검색 경로.
6. Scope & Limits — 책에 없는 것은 어디서 찾으라는 안내.

챕터 파일 1개의 7-섹션 템플릿

모든 챕터가 같은 7-섹션 구조를 따른다 — 일관성이 검색 가능성을 만든다.

# Chapter N: <Full Title>

## Core Idea
<1~2 문장: 이 챕터가 가르치는 가장 중요한 한 가지>

## Frameworks Introduced
- **<Framework Name>**: <저자의 정확한 명명을 보존>
  - When to use: <구체적 상황>
  - How: <단계 또는 기준>

## Key Concepts
- **<Term>**: <1문장 정의>
(5~10개 핵심 용어)

## Mental Models
<2~4개 사고 도구. "Use X when Y", "Think of X as Y">

## Anti-patterns
- **<피해야 할 것>**: <왜 실패하는가>

## Key Takeaways
1. <실행 가능한 통찰>
(3~7개)

## Connects To
- **Ch N**: <다른 챕터와의 연결>

Claude가 "Anti-patterns"를 찾으면 — 어느 챕터든 같은 위치에서 발견한다. "표준 폼이 검색을 가능하게 만든다".

이 작은 레포에서 배울 수 있는 5가지 핵심 기술

코드는 250줄이지만 학습 밀도는 높다.

① Claude Code 스킬 설계 패턴

SKILL.md 한 장이 — 어떻게 명세·트리거·도구 화이트리스트·논리 흐름을 다 담는지. 이건 "프롬프트 엔지니어링의 운영체제급 버전"이다.

• 프론트매터 필드 익히기: name·description·when_to_use·allowed-tools·effort·context
• allowed-tools에 Bash(pdftotext *)처럼 화이트리스트 패턴 쓰는 법
• context: fork로 메인 대화와 분리된 컨텍스트에서 실행
• 실습 아이디어: 자주 하는 작업(이메일 정리, 회의록 요약 등)을 SKILL.md 한 장으로 만들기

② 토큰 경제학 — On-demand loading 패턴

이 레포의 가장 강력한 통찰: "모든 걸 컨텍스트에 넣는 게 아니라 인덱스만 두고 호출 시 읽게 한다".

• SKILL.md = 인덱스(4K 토큰)
• chapters/*.md = 본문(각 1K, 17개)
• 매 호출 비용 = 4K + 사용한 챕터만큼
• 실습 아이디어: 회사 wiki를 같은 방식으로 변환(메인 + Topic Index + on-demand 사례)

③ "Density over completeness" 작문 원칙

이건 단순한 작문 조언이 아니라 — LLM 시대의 정보 압축 원칙이다. 발췌(원문 그대로)는 LLM이 다시 요약해야 한다. 요약(이미 정리됨)은 바로 적용 가능. 토큰 효율 차이가 10배.

④ Python 표준 라이브러리만으로 EPUB 파서

extract.py의 _HTMLTextExtractor 클래스가 백미. html.parser.HTMLParser를 상속해 — 외부 의존성 0개로 EPUB의 HTML을 평문화한다.

class _HTMLTextExtractor(html.parser.HTMLParser):
    SKIP_TAGS = {"script", "style", "head"}

    def handle_starttag(self, tag, attrs):
        if tag in self.SKIP_TAGS:
            self._skip_depth += 1
        if tag in ("p", "br", "h1", "h2", ...):
            self._parts.append("\n")

    def handle_data(self, data):
        if not self._skip_depth:
            self._parts.append(data)

BeautifulSoup도 좋지만 — "표준 라이브러리만 가능한 fallback"이 있다는 것 자체가 미덕.

⑤ 3단 폴백 + 적응적 에러 메시지

extract.py의 PDF 추출 로직 — 좋은 도구의 황금 패턴:

print("Trying pdftotext...", end=" ", flush=True)
text = extract_with_pdftotext(input_path)
if text:
    method = "pdftotext"; print("OK")
else:
    print("not available")
    print("Trying PyPDF2...", end=" ", flush=True)
    ... (PyPDF2 시도)
    ... (pdfminer 시도)
    print("\nERROR: Could not extract text.")
    print("Install one of:")
    print("  sudo apt install poppler-utils")
    print("  pip3 install PyPDF2")

요점: 실패해도 사용자가 다음에 무엇을 해야 하는지 정확히 알려준다. "Could not extract text"만 출력하고 끝나는 도구와의 차이.

실제 실행에 필요한 것들

대부분의 노트북에서 그대로 동작한다.

필수

• Claude Code 본체 — Anthropic 공식 CLI. npm i -g @anthropic-ai/claude-code 또는 공식 설치 스크립트.
• Python 3.9+ — pyproject.toml 공식 요구사항(requires-python = ">=3.9"). SKILL.md는 3.7+ 명시.
• PDF 추출기 1개 이상 — pdftotext(추천) / PyPDF2 / pdfminer.six.

선택

• ebooklib + beautifulsoup4 — EPUB 처리 품질 향상. pip3 install ebooklib beautifulsoup4.
• pdfinfo(poppler) — 페이지 수 정확 계산. 없으면 PyPDF2 fallback.

리소스

• 토큰 비용 — 책 1권 변환에 Sonnet 4.5 기준 ~$1.5~3, Haiku ~$0.4. Step 2.5에서 견적 미리 표시.
• 시간 — 200~500페이지 책: ~5~15분. 챕터 수에 비례.
• 디스크 — 생성 스킬 1개당 ~50~200KB. 100권 만들어도 20MB.

난이도별 실습 과제 5개

한 번 만든 스킬은 평생 쓴다 — 시작은 책 한 권부터.

① 좋아하는 기술서 1권을 스킬로 만들기EASY

가장 기본 실습. Designing Data-Intensive Applications, Clean Code, Domain-Driven Design 같은 고전 PDF로 시작.

# 설치 (에이전트 중립 경로 — Claude Code·Copilot CLI·Amp 공용)
git clone https://github.com/virgiliojr94/book-to-skill.git \
  ~/.agents/skills/book-to-skill
# Claude Code 사용자는 ~/.claude/skills/book-to-skill 로도 가능

# 실행 (Claude Code 안에서)
/book-to-skill ~/Books/clean-code.pdf

완성 후 /clean-code "함수가 너무 길어요"로 호출해 응답 비교. "환각 vs 챕터 인용"의 차이를 직접 보게 된다.

② "Analyze Only" 모드로 책 미리 보기EASY

비용 들이기 전에 — 책 안에 뭐가 있는지만 보고 싶을 때.

/book-to-skill ~/Books/some-book.pdf analyze only

출력: Author's Core Frameworks · Key Principles · Techniques · Anti-patterns 리스트. 이걸 보고 — "이 책은 스킬화 가치 있다 / 없다" 결정.

③ 한국어 책으로 스킬 만들기MEDIUM

SKILL.md가 영어 책 가정으로 쓰여 있지만 — 한국어 PDF도 들어간다. 단 챕터 감지 정규식이 영문 "Chapter N"에 맞춰져 있어, 한국어 PDF는 scripts/extract.py의 detect_structure를 수정해야 한다.

chapter_pattern = re.compile(
    r"^\s*(chapter\s+\d+|CHAPTER\s+\d+"
    r"|ch\.\s*\d+|\d+\.\s+[A-Z]"
    r"|제\s*\d+\s*[장부편]"      # ← 추가
    r"|\d+장\s+[가-힣])",          # ← 추가
    re.IGNORECASE
)

실습 결과로 — 자기 PR을 virgiliojr94 레포에 제출하면 보너스. 한국어 + 일본어 + 중국어 챕터 패턴은 누군가 채워야 할 빈 자리.

④ "회사 wiki → 스킬" 같은 패턴으로 확장MEDIUM

book-to-skill의 아이디어를 PDF 너머로 확장. 회사 Notion / Confluence를 마크다운으로 export한 뒤 — 같은 5-파일 구조로 변환하는 wiki-to-skill 만들기.

• SKILL.md = 회사 핵심 정책 (~4000토큰)
• chapters/ = 팀별 / 토픽별 (인사·인프라·코드 컨벤션·온콜 가이드)
• glossary.md = 사내 약어 (PRD, OKR, NPI…)
• patterns.md = 자주 쓰는 워크플로
• cheatsheet.md = "처음 들어온 사람을 위한 요약"

⑤ "내 GitHub 레포 → 스킬" 메타 패턴HARD

가장 야심찬 응용. tree-sitter로 코드를 AST 파싱 + 모듈별 역할 추출 + 의존성 그래프 + 자주 사용되는 함수 패턴 — 을 같은 5-파일 형태로 변환. safishamsi/graphify와 결합하면 강력.

• SKILL.md = 아키텍처 개요 + 디렉토리 맵
• chapters/ = 모듈별 (auth/, api/, models/…)
• glossary.md = 내부 도메인 용어
• patterns.md = 코드 컨벤션·디자인 패턴
• cheatsheet.md = "이 레포에서 흔히 하는 일 10가지"

결과물을 팀에 공유하면 — 온보딩 시간이 절반으로 준다.

주차별 학습 계획 — Claude Code 스킬 마스터 코스

이 한 레포에서 출발해 — 4주 후엔 자기만의 스킬 라이브러리.

이 로드맵 후 → 더 깊은 길

• Plugins로 확장 — anthropics/claude-plugins-official 레포의 공식 디렉토리 참고. 스킬 묶음을 플러그인으로 배포.
• MCP Server 만들기 — 스킬은 마크다운 한 장, MCP는 외부 도구 접근. 다음 단계.
• SkillKit 등으로 배포 자동화 — rohitg00/skillkit이 SKILL.md를 한 줄로 설치하는 패키지 매니저.

이 레포에서 등장하는 모든 기술 용어

한 번에 정리.

레포·관련 자료·생태계

한 번에 모은 다음 단계 진입로.

본체

github.com/virgiliojr94/book-to-skill · 13 stars · 4 commits · 100% Python · MIT.

Claude Code & Skills 공식

• docs.claude.com/en/docs/claude-code — Claude Code 공식 문서.
• docs.claude.com → Skills — SKILL.md 명세, 프론트매터 필드, allowed-tools 패턴.
• anthropics/claude-plugins-official — Anthropic 공식 플러그인 디렉토리.

유사·보완 레포

• hesreallyhim/awesome-claude-code — Claude Code 자료·스킬 큐레이션.
• multica-ai/andrej-karpathy-skills — 단일 CLAUDE.md로 Claude 코딩 개선.
• rohitg00/skillkit — SKILL.md 한 줄 설치 패키지 매니저.
• safishamsi/graphify — 코드/문서를 knowledge graph로 변환. book-to-skill의 코드 버전.

PDF 처리 라이브러리

• poppler — pdftotext가 속한 PDF 렌더링·추출 라이브러리 (공식 저장소: GitLab).
• py-pdf/pypdf — PyPDF2의 후속작.
• pdfminer/pdfminer.six — Python PDF 추출 라이브러리.
• aerkalov/ebooklib — Python EPUB 처리.

토큰 경제학 & Compaction

• Anthropic — Context Management — 긴 컨텍스트와 압축 패턴.
• Prompt caching — 반복 컨텍스트 캐싱으로 비용 90% 절감.