TL;DR

book-to-skill은 PDF·EPUB·DOCX 등 기술 문서를 입력받아 저자의 프레임워크와 챕터별 핵심을 추출해 SKILL.md와 챕터 파일로 컴파일하는 도구이다. 포맷별 추출기를 우선순위로 호출하고 기술서인 경우 Docling을 사용해 표와 코드 블록을 보존한 뒤 Claude로 구조를 분석해 온디맨드로 불러오는 챕터 방식으로 작동한다. 이 과정은 런타임마다 전체 문서를 컨텍스트로 넣는 방식보다 토큰 비용을 크게 낮추며 README의 측정에서는 컨텍스트 덤프 대비 24×–51×, discovery loop 대비 2.4×–15.6×의 절감 효과가 보고되었다. 단일 회차 참조에는 이득이 작을 수 있고 챕터 자동 분할은 명시적 'Chapter N' 식의 표기가 필요할 수 있다는 한계가 존재한다.

주요 기능

• 책과 문서 집합을 직접 스킬 패키지로 생성하는 기능을 제공한다. 입력으로 파일·폴더·glob·파일 목록을 받아 SKILL.md와 챕터별 마크다운, 용어집, 패턴, 치트시트 등을 생성한다. 생성된 스킬은 호스트별 스킬 디렉터리에 쓰여 온디맨드로 챕터를 로드해 런타임 토큰 비용을 줄인다.
• 기술 서적의 표와 코드 블록을 보존해 마크다운으로 추출하는 워크플로를 지원한다. 책 유형을 묻고 technical 모드 선택 시 Docling을 우선 사용해 표와 코드 예제를 손실 없이 포함한다. 이로 인해 실습 예제와 표 기반 레퍼런스를 그대로 에이전트가 읽을 수 있게 만든다.
• 온디맨드 챕터 로딩으로 런타임 컨텍스트 크기를 제한한다. SKILL.md가 약 4,000토큰의 핵심 코어를 담고 각 챕터는 요청 시에만 로드되며 챕터 파일은 보통 ~1,000토큰이다. 이 접근은 동일한 질문을 반복할 때 매번 전체 책을 컨텍스트로 넣는 방식보다 토큰 비용을 크게 낮춘다.
• 다양한 문서 포맷을 지원하고 추출기 우선순위를 자동 선택한다. 지원 포맷으로 PDF, EPUB, DOCX, Markdown, HTML, RTF, MOBI/AZW 등이 명시되어 있고 각 포맷에 대해 권장 추출 도구와 설치 명령을 안내한다. --check 명령을 통해 현재 시스템에 설치된 추출기를 한 번에 점검할 수 있다.

어떻게 동작하는가

사용자가 파일·폴더·glob를 지정하면 로컬에서 우선순위에 따라 포맷별 추출기를 호출해 모든 소스를 병합한 full_text와 메타데이터를 생성한다. 병합된 본문은 Claude에게 구조 분석(제목, 저자, 챕터, ToC) 명령으로 넘겨져 챕터별 요약과 패턴, 용어집, 치트시트를 생성한다. 생성된 SKILL.md와 챕터 파일은 호스트별 스킬 디렉터리에 기록되고 런타임에는 SKILL.md의 코어와 요청된 챕터만 로드되어 반복적인 토큰 비용을 줄이는 흐름을 따른다.

해결 문제

원문 전체를 매번 컨텍스트로 넣어 질문할 때 발생하는 반복적 토큰 비용과 맥락 상실 문제를 줄인다. book-to-skill은 추출 시점에 저자의 프레임워크와 핵심 규칙을 구조화해 저장하고 런타임에는 관련 챕터만 로드해 질문에 답한다. 이 방식은 반복해서 참조하는 기술서나 내부 문서를 작업 흐름에 통합할 때 유의미한 비용·정확도 이점을 제공한다.

지금 주목받는 이유

이 레포는 2026년 5월 23일 Trendshift의 Python Repository of the Day 상위권에 올랐고 GitHub에서 7,578개의 스타를 기록해 관심을 받고 있다.

차별점

• 컴파일 타임에 저자의 프레임워크를 구조화해 스킬로 저장하는 접근을 채택한다. RAG처럼 쿼리 시점에 임베딩·검색·주입하는 방식과 달리 한 번의 심층 추출로 챕터 기반 파일과 핵심 모델을 만들어 놓는다. 이로 인해 반복 질의에서 매번 문서를 재처리하는 비용이 사라지고 원문과의 대조가 쉬워진다.
• 디스커버리 루프 비용을 정량적으로 낮춘다는 점이 명확히 제시되어 있다. README의 측정값은 컨텍스트 덤프 대비 24×–51×, discovery loop 대비 2.4×–15.6×의 토큰 절감 비율을 보이며 실사용에서 비용 절감 근거를 제공한다. 이러한 숫자는 챕터 크기와 분절 방식에 따라 달라지며 대형 챕터일수록 장점이 커진다.
• 여러 호스트와 포맷을 표준화된 출력으로 연결하는 통합 경로를 제공한다. 생성물은 SKILL.md와 챕터 파일 형태로 Copilot CLI, Amp, Claude Code가 공통으로 읽을 수 있는 형식으로 저장되며 standalone CLI 경로도 함께 제공된다. 따라서 단일 도구로 다양한 워크플로에 스킬을 배포하고 업데이트하는 흐름이 간결하다.

사용 사례

• 기술 서적을 작업 중인 코드나 문서 세션에서 즉시 참조 가능한 스킬로 전환해 실무 중 바로 질문하고 답을 얻는 워크플로에 적용할 수 있다. 개발자는 특정 챕터나 패턴을 에이전트에게 요청하면 해당 챕터 파일만 로드해 근거를 확인하면서 답을 얻을 수 있다. 이 방식은 재학습 없이 참조 빈도가 높은 레퍼런스 자료를 작업 환경에 통합할 때 유용하다.
• 내부 문서 집합, 온보딩 가이드, 디자인 시스템 같은 조직 지식을 하나의 스킬로 접합해 팀 작업 중 바로 불러오는 데에 적합하다. 여러 문서를 하나의 스킬로 병합하면 팀원들이 슬래시 명령으로 정책이나 규칙을 조회할 수 있고 중앙 저장된 원문을 근거로 답변을 제공한다. 업데이트는 새 문서를 fold-in하는 방식으로 스킬을 갱신해 유지 관리가 가능하다.
• 연구 논문 클러스터나 관련 자료를 통합해 특정 주제에 대해 깊이 있는 추론을 요구하는 작업에서 쓸 수 있다. 논문과 노트를 통합해 하나의 스킬로 만들면 모델이 저자 고유의 프레임워크와 결론을 기준으로 추론할 수 있으며, 반복 조회 시 토큰 비용을 줄일 수 있다. 대규모 색인이 필요한 광범위 검색용 워크플로보다는 좁고 깊은 주제에 더 적합하다.

시작하기

에이전트 스킬로 사용하려면 레포를 호스트의 스킬 디렉터리에 git clone으로 복제하고 세션에서 스킬을 리로드하면 슬래시 명령이 활성화된다. 예를 들어 Copilot CLI 개인 스킬은 ~/.copilot/skills/book-to-skill에 클론한 뒤 copilot 세션에서 /skills reload를 실행하면 된다. standalone CLI로 쓰려면 pip install "book-to-skill[pdf,epub,docx]"로 설치하고 book-to-skill --check로 추출기 설치 상태를 확인한 뒤 book-to-skill ~/path/to/book.pdf --mode text 같은 명령으로 실행하면 된다.

요구사항

• Python 3 런타임이 기본 요구사항으로 명시되어 있고 일부 포맷은 추가 도구가 필요하다. PDF 텍스트는 pdftotext(poppler)·pypdf·pdfminer.six 중 가용한 것을 사용하며 기술 서적은 Docling을 권장한다. EPUB, DOCX, HTML, RTF 등 각 포맷에 대해 권장 파이썬 패키지(ebooklib, python-docx, beautifulsoup4, striprtf) 또는 외부 앱(Calibre)이 별도로 요구된다.
• 추출기는 포맷별로 우선순위를 두고 사용 가능한 도구를 자동 선택하므로 일부 포맷은 추가 설치가 권장된다. README는 설치 명령과 함께 어떤 도구가 최적화된 결과를 내는지 표로 정리해 두었고 --check 명령으로 현재 시스템 상태를 확인할 수 있다. 시스템에서 해당 추출기가 없으면 스크립트가 어떤 명령을 실행해야 하는지 안내 메시지를 출력한다.
• 실행 환경은 CPU만으로도 동작하지만 성능과 속도는 사용한 추출기·서버 리소스에 따라 달라진다. 예시 벤치마크는 CPU 기준 측정값을 제공하며 대용량 책을 처리할 때 처리 시간·토큰 생성량·비용 발생 항목을 고려해야 한다. Docling 처리 시 페이지당 약 1.5초의 속도 정보가 README에 포함되어 있다.

벤치마크