Book-to-SKILL: 기술서적을 Claude Code 스킬로 바꾸는 지식 구조화 파이프라인

기술 서적에 담긴 방대한 도메인 지식을 AI 에이전트가 작업 중 즉시 참조할 수 있도록 만드는 오픈소스 도구 Book-to-SKILL이 공개됐다. PDF나 EPUB 형식의 기술 서적을 Claude Code 스킬 포맷으로 자동 변환하여 ~/.claude/skills/ 디렉토리에 배포하는 전 과정을 파이프라인으로 자동화한 것이다. 단순한 파일 변환을 넘어 문서 구조 분석·챕터 요약·용어집 생성·패턴 추출·치트시트 합성 등 지식 구조화 단계를 포함한다.

코드와 표를 잃지 않고 텍스트를 뽑아내는 법

기술 서적 PDF를 AI가 활용 가능한 형태로 변환하는 첫 번째 관문은 정확한 텍스트 추출이다. 일반 문서와 달리 기술 서적은 코드 블록·표·수식·다이어그램이 혼재하며, 이를 손실 없이 추출하려면 목적에 맞는 파서 선택이 핵심이다.

Book-to-SKILL은 서적의 성격에 따라 두 가지 파싱 엔진을 선택한다. 코드 예시와 표가 많은 기술 서적에는 IBM이 오픈소스로 공개한 Docling을 사용하고, 설명 위주의 텍스트 서적에는 pdftotext·PyPDF2·pdfminer를 사용한다. Docling은 PDF 문서를 DoclingDocument 중간 표현(IR)으로 변환한 뒤 마크다운·JSON·HTML 등 다양한 포맷으로 내보낼 수 있는 파이프라인 아키텍처를 갖는다. 처리 속도는 페이지당 약 1.5초로 실용적인 수준이며, 레이아웃 분석·OCR·표 인식 모델이 내장되어 있어 복잡한 기술 문서도 구조를 유지한 채로 추출할 수 있다. VLM(비전-언어 모델) 파이프라인도 지원하여 스캔 문서나 수식 이미지가 많은 서적에도 대응한다. EPUB 처리에는 ebooklib와 표준 라이브러리 zipfile을 조합하여 사용한다. EPUB은 실질적으로 ZIP 아카이브 안에 XHTML 파일이 담긴 구조이므로, 챕터 파일을 순서대로 언패킹하여 HTML → 마크다운 변환을 적용하면 된다.

원시 텍스트가 확보되면 Claude가 직접 문서 구조를 분석한다. 제목·저자·출판연도와 같은 메타데이터를 /tmp/book_skill_work/metadata.json에 저장하고, 목차를 기준으로 챕터 경계를 식별한다. 챕터별로 800~1,200 토큰 분량의 요약을 생성하며, 기술 서적의 경우 Code Examples 섹션과 Reference Tables 섹션을 별도로 구성한다. 섹션 분류 시에는 헤딩 레벨 패턴(H1/H2/H3)과 페이지 번호 패턴을 조합하여 논리적 단위를 분리한다. 부록·참고문헌·색인은 별도 섹션으로 처리하여 핵심 콘텐츠와 분리한다.

기술 서적에서 코드 블록과 테이블은 핵심 참조 자료다. Docling의 마크다운 내보내기는 펜스드 코드 블록(```)과 파이프 테이블 문법을 그대로 유지하므로, SKILL.md에 통합될 때 Claude가 코드를 코드로, 표를 표로 인식할 수 있다. 코드 블록 처리 시 언어 힌트(python, java 등)가 없는 경우 주변 텍스트 맥락을 분석하여 언어를 추론하고 태그를 자동 추가한다. 이렇게 하면 스킬이 활성화되었을 때 Claude가 해당 언어의 문법으로 예시를 설명하거나 변형할 수 있다.

description이 트리거가 되는 스킬 포맷

Book-to-SKILL로 생성된 결과물은 Claude Code의 스킬 포맷을 따른다. 스킬은 ~/.claude/skills/<slug>/ 디렉토리 아래에 SKILL.md를 중심으로 구성된다.

스킬의 트리거 설계는 Claude가 100개 이상의 스킬 중에서 올바른 스킬을 선택하는 핵심 메커니즘이다. Claude Code는 시작 시 모든 스킬의 YAML 프론트매터(name·description)만 미리 로드하고, 스킬이 관련성이 있다고 판단될 때만 SKILL.md 전체를 읽는다. 따라서 description 필드가 트리거 역할을 한다. 효과적인 트리거 패턴은 "Use when [사용자 의도 또는 맥락]" 형식을 따른다. 스킬이 무엇을 하는지 설명하는 게 아니라 언제 선택되어야 하는지를 명시해야 한다. Book-to-SKILL이 생성하는 스킬의 description은 서적 제목·핵심 개념·다루는 기술 스택을 포함하여 최대한 구체적으로 작성된다. 예를 들어 "Designing Data-Intensive Applications" 서적을 변환하면 트리거 설명은 다음과 같이 생성된다.

---
name: designing-data-intensive-apps
description: >
  Use when working with distributed systems, data replication, consistency,
  consensus, stream processing, or batch processing. Reference for DDIA
  concepts by Kleppmann — replication strategies, partitioning, transactions,
  and data system design tradeoffs.
---

disable-model-invocation: true 필드를 사용하면 Claude가 스킬을 자동으로 선택하지 않고 사용자가 명시적으로 슬래시 커맨드로 호출할 때만 활성화된다. 레퍼런스성 스킬에는 자동 호출을 허용하고, 특정 명령 실행이 필요한 스킬에는 수동 호출을 설정하는 것이 일반적인 패턴이다.

SKILL.md에서 !command 형식으로 셸 명령을 삽입하면 Claude가 스킬을 읽기 전에 해당 명령의 출력이 인라인으로 치환된다. 이를 동적 컨텍스트 주입(Dynamic Context Injection)이라 한다. Book-to-SKILL은 이 기능을 활용하여 서적의 인덱스 파일 목록, 최근 갱신된 챕터 요약, 용어집 엔트리 수 등을 런타임에 주입한다.

## 현재 스킬 상태
챕터 수: !ls references/chapters/ | wc -l
마지막 갱신: !stat -c %y references/glossary.md

이렇게 하면 스킬이 활성화될 때마다 최신 상태 정보가 컨텍스트에 포함되어 Claude가 "이 스킬에 몇 챕터가 있는지", "용어집이 최근에 갱신됐는지" 등을 별도 파일을 읽지 않고도 즉시 알 수 있다.

필요한 만큼만 펼치는 계층 구조

단일 SKILL.md에 모든 내용을 집어넣으면 컨텍스트 창이 불필요하게 소비된다. Book-to-SKILL은 프로그레시브 디스클로저(Progressive Disclosure) 패턴을 적용하여 스킬을 계층적으로 구성한다. 스킬 디렉토리 구조는 다음과 같다.

~/.claude/skills/designing-data-intensive-apps/
├── SKILL.md              # 핵심 멘탈 모델·사용법 (항상 로드)
├── references/
│   ├── chapters/
│   │   ├── ch01-reliable-scalable-maintainable.md
│   │   ├── ch05-replication.md
│   │   └── ...
│   ├── glossary.md       # 용어집
│   └── patterns.md       # 설계 패턴 모음
├── cheatsheet.md         # 1-페이지 치트시트
└── scripts/
    └── search.sh         # 키워드 검색 헬퍼

SKILL.md에는 핵심 멘탈 모델과 각 하위 파일에 대한 참조만 포함하고, Claude는 사용자 질의에 따라 필요한 챕터 파일만 추가로 로드한다. 이 방식으로 컨텍스트 효율을 유지하면서도 전체 서적의 지식에 접근할 수 있다.

도구를 검색하는 RAG, 그리고 하이브리드 지식 구조

Book-to-SKILL은 단순한 파일 변환 도구를 넘어 AI 에이전트의 도메인 지식 통합 문제를 해결하는 접근법을 보여준다. 에이전트가 특정 도메인 지식을 언제·어떻게 활용하느냐는 에이전트 설계의 핵심 과제 중 하나다.

전통적인 RAG(Retrieval-Augmented Generation)는 사용자 쿼리가 들어오면 벡터 DB에서 관련 문서 청크를 검색하여 컨텍스트로 전달한다. 이 방식은 대규모 문서 코퍼스에 유리하지만, Claude Code처럼 실시간 코딩 작업을 지원하는 환경에서는 검색 레이턴시와 청크 분절 문제가 발생할 수 있다. 최근 주목받는 Tool RAG는 문서 대신 도구를 검색한다는 개념이다. 사용자 쿼리가 들어오면 도구 설명·API 스키마·사용 패턴을 담은 레지스트리에서 의미론적으로 가장 관련성 높은 도구를 선택하여 LLM에 전달한다. Red Hat의 연구에 따르면 Tool RAG는 도구 호출 정확도를 세 배 높이면서 프롬프트 길이를 절반으로 줄인다. Book-to-SKILL의 스킬 레지스트리는 이 Tool RAG 개념의 실용적 구현에 해당한다. Claude는 100개 이상의 스킬 description을 읽고 현재 작업 맥락에 가장 적합한 스킬을 동적으로 선택한다.

에이전트가 도메인 지식을 활용하는 방식은 사전 학습으로 모델 가중치에 저장돼 갱신이 어렵고 최신 정보 반영에 한계가 있는 파라메트릭 지식(Parametric Knowledge), 프롬프트에 직접 포함돼 유연하고 최신 정보 주입이 가능하지만 컨텍스트 창 한계가 있는 인컨텍스트 지식(In-context Knowledge), 외부 저장소에서 필요 시 검색해 주입해 대규모 지식에 적합하지만 검색 품질에 의존적인 검색 기반 지식(Retrieval-based Knowledge)으로 나뉜다. Book-to-SKILL의 스킬 포맷은 두 번째와 세 번째 방식을 결합한다. 스킬 활성화 시 핵심 지식을 컨텍스트에 직접 주입하고(인컨텍스트), 세부 내용은 하위 파일 참조를 통해 필요 시 로드(검색 기반)하는 하이브리드 구조다.

도메인 지식은 고정되어 있지 않다. 프레임워크 신버전 출시, 보안 취약점 발견, 모범 사례 변화 등으로 기술 서적의 내용도 시간이 지나면 갱신이 필요하다. Book-to-SKILL은 전체 스킬을 재생성하는 대신 특정 챕터 파일만 다시 생성해 컨텍스트 연속성을 유지하는 챕터 단위 재생성을 지원하며, 스킬 메타데이터의 last_updated 필드로 갱신 이력을 추적한다. 단일 서적뿐 아니라 공식 문서·블로그 포스트·GitHub 저장소를 추가 소스로 통합하는 Skill Seekers 같은 확장 도구도 존재한다. 18가지 소스 타입을 지원하며 충돌 감지(Conflict Detection) 기능도 내장되어 있다. 2026년 기준으로 엔터프라이즈 환경에서는 RAG를 단순 검색 레이어가 아니라 검색·검증·추론·접근제어·감사 추적을 통합 관리하는 지식 런타임(Knowledge Runtime)으로 취급하는 방향으로 발전하고 있다. Book-to-SKILL의 스킬 레지스트리 패턴은 이 트렌드와 궤를 같이한다.

서적에서 스킬 레지스트리까지, 파이프라인 전체 흐름

아래 다이어그램은 PDF/EPUB 서적이 Claude Code 스킬로 변환되어 에이전트 작업에 통합되는 전체 파이프라인을 나타낸다.

⤢✕

파이프라인은 크게 세 단계로 구분된다. 첫째, 문서 파싱 단계에서 입력 포맷과 콘텐츠 특성에 따라 최적의 파서를 선택하여 원시 텍스트를 추출한다. 둘째, 지식 구조화 단계에서 Claude가 구조를 분석하고 계층적 요약과 참조 자료를 생성한다. 셋째, 배포 및 통합 단계에서 스킬 디렉토리를 생성하고 레지스트리에 등록하여 에이전트 작업 중 동적으로 활성화된다. Skill Seekers처럼 문서 웹사이트·GitHub 저장소·PDF를 모두 스킬로 변환하는 도구도 등장하면서, 에이전트가 참조할 수 있는 도메인 지식의 범위가 점점 넓어지고 있다. 단순히 서적 한 권을 변환하는 것에 그치지 않고, 팀 전체의 지식 베이스를 스킬 레지스트리로 관리하는 방향으로 확장 가능하다.

Book-to-SKILL은 기술 서적이라는 정형화된 지식 자산을 AI 에이전트가 실시간으로 활용할 수 있는 스킬로 변환함으로써, 에이전트의 도메인 지식 한계를 실용적인 방식으로 극복하는 접근법을 제시한다. Docling 기반 PDF 파싱·프로그레시브 디스클로저·동적 컨텍스트 주입의 조합은 컨텍스트 효율과 지식 접근성을 동시에 확보하는 설계 원칙을 보여준다. 앞으로는 단일 서적을 넘어 조직 전체의 기술 문서를 스킬 레지스트리로 통합 관리하는 엔터프라이즈 지식 런타임 패턴이 확산될 것으로 전망된다.