book-to-skill 공식 로고 book-to-skill 공식 로고 — 출처: book-to-skill

기술서를 한 권 사서 읽습니다. 석 달 뒤에 그 책에 7장이 있었다는 사실조차 기억나지 않습니다. 그래서 PDF를 AI에게 통째로 던져 봅니다 — 400쪽이면 대략 20만 토큰(token, 모델이 글을 쪼개 세는 단위)이고, 그 비용은 대화를 새로 열 때마다, 심지어 한 턴마다 다시 청구됩니다.

이 문제를 정면으로 겨냥한 오픈소스 도구가 있습니다. 책을 요약하는 게 아니라 에이전트가 쓰는 스킬(skill)로 컴파일해 버리는 book-to-skill입니다. GitHub 별 1만 6천 개를 넘겼고, 만든 지 석 달밖에 안 됐습니다.

말만 듣고 넘어가긴 아까워서 직접 설치해 책 한 권을 통째로 변환하고, 나온 결과물과 토큰 사용량까지 재봤습니다.

왜 책을 스킬로 바꾸나 — 탐색 루프 세금

PDF를 읽는 AI 에이전트(agent, 스스로 도구를 골라 일을 처리하는 AI)는 그냥 읽지 않습니다. 목차를 불러오고, 모르는 용어가 나오면 다른 페이지를 더 당겨오고, 되짚어 돌아갑니다. 그렇게 끌어온 페이지가 전부 대화 기록에 쌓이고, 이후 모든 턴에서 다시 처리됩니다. 개발자는 이걸 Discovery Loop Tax(탐색 루프 세금)라고 부릅니다.

book-to-skill의 발상은 단순합니다. 그 탐색 비용을 컴파일 시점에 한 번만 내자는 것입니다. 책을 미리 뜯어 프레임워크·원칙·안티패턴으로 구조화해 두면, 실행할 때는 작은 핵심 파일 하나와 필요한 챕터 하나만 읽으면 됩니다.

공식 문서는 이 주장을 추정이 아니라 실측으로 내놓습니다. tiktoken으로 토큰을 직접 세고, 저장소에 들어 있는 discovery_tax.py로 누구나 자기 책에 재현해 볼 수 있게 해뒀습니다.

실제 책 3권으로 측정한 Discovery Loop Tax 비교표 실제 책 3권으로 측정한 Discovery Loop Tax 비교표 — 출처: book-to-skill

책이 클수록 이득도 커집니다. 챕터가 작은 Think Python 2는 전문 붙여넣기 대비 24배, 챕터가 큰 AI Engineering은 51배입니다. 그리고 이 절감은 매 턴 반복됩니다.

컨텍스트 윈도가 커진 건 가능해졌다는 뜻이지, 싸졌다는 뜻이 아닙니다

문서의 FAQ에 나오는 문장이 이 도구의 입장을 가장 잘 요약합니다. 100만 토큰 창이 생겼다고 20만 토큰짜리 책을 상주시키는 게 합리적이 되는 건 아니라는 겁니다. 토큰은 여전히 개당 과금되고, 문맥이 가득 찰수록 특정 사실을 정확히 꺼내오는 정확도는 오히려 떨어집니다.

book-to-skill은 정확히 무엇인가

브라질 개발자 virgiliojr94가 2026년 5월 1일에 시작한 Python 프로젝트입니다. MIT 라이선스이고, 제가 확인한 시점 기준 별 16,154개 · 포크 1,721개 · 기여자 19명, 최신 릴리스 v1.3.0은 7월 30일에 나왔습니다. 세 달 만의 성장 속도로 보면 같은 갈증을 느낀 사람이 꽤 많았던 셈입니다.

book-to-skill GitHub 저장소 메인 화면 book-to-skill GitHub 저장소 메인 화면 — 출처: GitHub

중요한 건 이게 특정 AI 전용이 아니라는 점입니다. 열린 Agent Skills 표준을 따르기 때문에 Claude Code, GitHub Copilot CLI, Amp가 같은 SKILL.md 형식을 읽습니다. 설치는 자기 스킬 폴더에 저장소를 복제하면 끝입니다.

무엇을 넣을 수 있나

PDF · EPUB · DOCX · TXT · Markdown · reStructuredText · AsciiDoc · HTML · RTF, 그리고 Calibre가 깔려 있으면 MOBI/AZW까지 받습니다. 파일 하나가 아니라 폴더나 와일드카드 여러 개를 한꺼번에 넘겨 하나의 스킬로 합칠 수도 있습니다.

이름은 책이지만 입력은 사실상 구조화된 산문 전부입니다. 사내 아키텍처 결정 기록, 런북, 온보딩 문서, 브랜드 보이스 가이드, 논문 묶음, RFC와 API 계약서 — 자주 다시 열어보는 문서라면 전부 후보입니다.

추출기를 두 갈래로 나눠 쓴다

변환을 시작하면 스킬이 먼저 묻습니다. “이 책은 기술서인가요, 산문 위주인가요?” 이 답이 추출 도구를 가릅니다.

모드 도구 103쪽 기술 PDF 기준 표 보존 코드블록 보존
산문 위주 pdftotext 0.1초 0개 0개
기술서 Docling 164초 (쪽당 ~1.5초) 48개 36개

1,600배 넘게 느린 대신 표와 코드를 마크다운으로 살려냅니다. 알고리즘 책이나 논문처럼 표·수식이 본론인 자료를 빠른 쪽으로 뽑으면 정작 필요한 정보가 통째로 날아갑니다.

직접 돌려봤습니다 — 스트렁크 『The Elements of Style』

책을 하나 골라야 했는데, 저작권 문제가 없어야 하고(뒤에서 다시 이야기합니다) 결과물이 한눈에 검증 가능해야 했습니다. 그래서 1918년판 『The Elements of Style』을 골랐습니다. 윌리엄 스트렁크가 쓴 영어 문장 교본이고, 미국 저작권이 만료된 퍼블릭 도메인이라 Project Gutenberg에서 전문을 받을 수 있습니다. 무엇보다 번호가 붙은 규칙 18개로 이뤄져 있어서, 도구가 구조를 제대로 뽑았는지 대조하기 좋습니다.

설치하고 추출기를 돌리는 데까지 1분이 안 걸렸습니다.

추출 단계

스크립트가 뱉은 값은 이렇습니다 — 16,967단어, 약 22K 토큰, 챕터 9개 감지, 목차 있음. 여기까지는 순수 텍스트 처리라 순식간에 끝납니다.

그다음이 실제 비용이 드는 구간입니다. 스킬은 생성에 들어가기 전 예상 토큰과 시간을 먼저 보여주고 확인을 받습니다. 달러 금액을 코드에 박아두지 않고 “오늘 단가를 곱해서 추정치라고 밝히라”고 지시해 둔 점이 눈에 띄었습니다. 모델 가격이 자주 바뀌는 걸 감안한 설계입니다.

생성 단계

여기서 스킬은 원문을 처음부터 끝까지 읽지 않습니다. 5만 토큰이 넘는 책은 grep으로 챕터 위치를 찾고 sed로 필요한 구간만 잘라 오라고 지시합니다. 200쪽 책을 챕터마다 다시 읽으면 입력 토큰이 200만 개까지 불어나기 때문입니다.

챕터별 요약의 분량도 고정값이 아니라 책 성격 × 사용 목적 행렬로 정해집니다.

  참고용(빠른 조회) 학습용(깊이 읽기)
산문 위주 800~1,200 토큰 1,000~1,800 토큰
기술서 1,200~1,800 토큰 2,000~3,000 토큰

학습용을 고르면 저자가 직접 풀어놓은 사례를 한 개는 반드시 복원하라는 조건이 붙습니다. 분량을 채우려고 문장을 늘리는 걸 막고, 실제로 다시 찾아보게 되는 건 그 사례라는 판단입니다. 정직한 설계라고 느낀 부분입니다 — 채울 게 없으면 하한 아래로 내려가고 대신 “이 챕터는 내용이 얇다”고 적으라고까지 명시해 뒀습니다.

책의 문장이 프레임워크·판단 규칙 카드로 재배열되는 3D 콘셉트 씬 책의 문장이 프레임워크·판단 규칙 카드로 재배열되는 3D 콘셉트 씬 — 출처: 개념 컷 — agy 자가 생성

나온 결과물 뜯어보기

strunk-style이라는 이름으로 파일 11개가 만들어졌습니다. 요약본 한 덩어리가 아니라 역할이 나뉜 묶음이라는 게 핵심입니다.

파일 무엇이 담기나 언제 읽히나
SKILL.md 저자의 핵심 프레임워크, 챕터 색인, 주제 색인 항상
chapters/ch01~07 챕터별 핵심 개념·안티패턴·재현된 사례 그 주제를 물었을 때만
glossary.md 용어와 정의, 등장 챕터 번호 용어를 물었을 때
patterns.md 실제로 적용하는 기법과 트레이드오프 고쳐쓸 때
cheatsheet.md 판단 규칙과 결정표 결정을 내릴 때

생성된 strunk-style 스킬의 파일별 토큰 크기 생성된 strunk-style 스킬의 파일별 토큰 크기 — 출처: tiktoken 실측 기반 자가 렌더

전체 합계는 14,224 토큰입니다. 원문 24,081 토큰의 59% 수준인데, 여기서 중요한 건 총량이 아니라 상시 로드되는 게 2,211 토큰짜리 SKILL.md 하나뿐이라는 점입니다. 나머지는 디스크에 누워 있다가 그 주제를 물었을 때만 올라옵니다.

요약이 아니라 구조라는 말의 의미

가장 인상적이었던 건 cheatsheet.md였습니다. 스킬 명세가 이 파일에 대해 “용어 나열이면 실패다, 저자의 판단을 담아라”라고 못 박아 둡니다. 그래서 나온 게 이런 표입니다.

규칙이 충돌하면 이기는 쪽 이유
분사구 연결(7번) vs 능동태(10번) 7번 잘못 붙은 수식은 오류, 수동태는 취향
병렬 구조(15번) vs 군더더기 삭제(13번) 15번 반복되는 관사·전치사는 대칭을 사는 값
관련어 인접(16번) vs 강조어 후치(18번) 16번 오결합은 오류, 약한 마무리는 약점일 뿐

이 표는 책 어디에도 그대로 실려 있지 않습니다. 규칙 18개를 서로 부딪혀 보고 추려낸 결과입니다. 붙여넣은 원문에서는 절대 나오지 않는 층이고, 이게 “검색이 아니라 추론”이라는 이 도구의 주장에 해당하는 부분입니다.

보안 점검을 강제한다

생성이 끝나면 scan_generated_skill.py를 돌려 주입 공격 패턴이나 권한 탈취 문구가 섞여 들어가지 않았는지 검사하라고 지시합니다. 스킬은 결국 AI에게 읽히는 지시문이니, 출처 불명 PDF에서 만든 스킬이 조용히 지시를 심는 통로가 될 수 있습니다. 제 결과물은 통과했고, Claude Code 규격 검사기(validate_skill.py)도 경고 0으로 지나갔습니다.

숫자로 확인 — 이득은 어디서 나는가

여기서부터가 직접 재본 이유입니다. 공식 수치는 대형 기술서 기준이고, 제가 고른 책은 24K 토큰짜리 얇은 책입니다.

질문 하나에 답하려고 문맥에 넣는 토큰 비교 질문 하나에 답하려고 문맥에 넣는 토큰 비교 — 출처: discovery_tax.py 실측 기반 자가 렌더

책 전문을 붙여넣는 방식 대비로는 5.3배 아꼈습니다. 이 절감은 대화가 이어지는 내내 매 턴 반복되니 실제 체감은 배수보다 큽니다.

그런데 같은 도구가 내놓은 두 번째 비교는 정반대 방향을 가리킵니다. 원문에서 목차를 보고 필요한 챕터만 직접 찾아 읽으면 3,110 토큰이고, 스킬은 4,502 토큰입니다. 이 책에서는 스킬 쪽이 오히려 손해라는 뜻입니다.

공식 문서도 이 지점을 숨기지 않습니다. 챕터가 작은 책에서는 탐색 루프 대비 이득이 2.4배까지 줄고, “한 번 읽고 말 자료라면 그냥 PDF 에이전트를 쓰라”고 적어 뒀습니다. 제 실험은 그 경계선 바깥의 사례를 하나 더한 셈입니다.

얇은 책은 스킬로 만들 이유가 없습니다 — 두껍고, 자주 돌아오는 책이라야 남습니다

컴파일 비용은 공식 추정으로 책 한 권에 약 1달러, 우리 돈 1,400원 안팎입니다. 한 번만 내면 되는 돈이라 부담은 아니지만, 그 값을 회수하려면 그 책에 반복해서 돌아와야 합니다.

잘 안 되는 지점도 있었습니다

문서에 적힌 한계가 실제로 재현됐습니다. 챕터 자동 분할이 그것입니다.

이 도구는 Chapter N 같은 알아볼 수 있는 챕터 제목이 있어야 책을 자릅니다. 로마 숫자·한중일 표기·한국어 제N장까지 지원하지만, 제목만으로 장을 여는 책은 깔끔하게 나뉘지 않습니다.

제 책에서 벌어진 일은 조금 더 짓궂었습니다. 감지기가 챕터로 잡아낸 목록에 이런 게 섞여 있었습니다.

감지된 항목 실제 정체 결과
C. Subject. 본문 속 개요 작성 예시의 소항목 챕터 100번으로 오인
Chapter XII 숫자 표기법을 설명하는 예문 챕터 12번으로 오인
III. Explain and correct… 부록 연습문제 번호 챕터 3번과 충돌

그 바람에 정작 알맹이인 3장(문장·문단 원칙, 규칙 8~18)의 본문이 305 토큰에서 잘려 나갔습니다. 원래 7,000 토큰 규모의 장입니다.

다행히 이게 결과물을 망치지는 않았습니다. 자동 분할 결과는 비용 추정과 측정 도구에만 쓰이고, 실제 챕터 요약은 AI가 원문을 직접 훑어 만들기 때문입니다. 다만 미리 보여주는 예상 비용과 discovery_tax.py 측정치는 그만큼 신뢰도가 떨어집니다. 변환 전에 감지된 챕터 수가 책의 실제 장 수와 맞는지 한 번 보는 게 좋겠습니다.

저작권은 사용자 책임입니다

저장소는 책 내용을 한 쪽도 담고 있지 않습니다. 내가 가진 파일을 가리키면 내 컴퓨터에서 추출이 돌아갑니다. 명세에도 “원문을 절대 그대로 복사하지 말고 항상 합성하라”는 규칙이 박혀 있습니다.

그래도 산 책으로 만든 스킬을 공개 저장소에 올리거나 팀에 뿌리는 건 다른 문제입니다. 문서는 “손으로 쓴 독서 노트처럼 개인용으로만 두라”고 권합니다. 이번 실험에 굳이 퍼블릭 도메인 책을 고른 것도 그래서입니다. 사내 문서나 직접 쓴 글, 오픈 라이선스 자료라면 물론 자유롭게 공유해도 됩니다.

그래서 언제 쓰면 좋은가

한 문장으로 줄이면 자주 돌아오는 두꺼운 자료에 쓴다입니다.

상황 판단
두꺼운 기술서를 몇 달째 계속 참조한다 적합 — 가장 이득이 큰 자리
사내 문서·런북·아키텍처 기록이 흩어져 있다 적합 — 폴더째 하나로 합칠 수 있음
관련 논문 여러 편을 계속 쌓아간다 적합 — 기존 스킬에 접어 넣기 지원
책 수십 권을 가로질러 검색하고 싶다 부적합 — RAG나 NotebookLM 쪽
한 번 읽고 끝낼 자료다 부적합 — 그냥 읽는 게 싸다
얇은 문서를 정확히 조회만 한다 부적합 — 원문 직접 조회가 더 쌈

README는 RAG(검색 증강 생성)와의 차이도 선을 그어 설명합니다. RAG는 질의 시점에 유사한 조각을 찾아오고, book-to-skill은 컴파일 시점에 프레임워크를 뽑아둡니다. 넓고 얕게 훑는 일은 RAG가, 좁고 깊게 파는 일은 스킬이 낫다는 정리입니다. 서로 대체재가 아니라 책장을 색인하는 도구와 한 권을 체화하는 도구의 차이에 가깝습니다.

마무리

책을 요약하는 도구는 이미 많습니다. book-to-skill이 다른 지점은 결과물을 사람이 읽는 노트가 아니라 AI가 실행하는 지시문으로 만든다는 데 있습니다. 규칙마다 “언제 쓰는가”와 “왜 실패하는가”가 붙고, 규칙끼리 충돌할 때 무엇이 이기는지까지 표로 남습니다.

직접 돌려보고 남은 인상은 두 가지입니다. 하나는 측정에 정직하다는 것 — 자기 도구가 지는 구간을 문서에 그대로 적어 두고, 그걸 재현할 스크립트까지 같이 넣어 뒀습니다. 다른 하나는 얇은 책에 쓰면 손해라는 것이고, 이건 도구를 폄하하는 결론이 아니라 적용 범위를 정확히 아는 편이 낫다는 쪽에 가깝습니다.

몇 달째 책상 위에 펼쳐둔 두꺼운 기술서가 있다면, 1,400원과 몇 분을 써볼 만합니다.

참고 출처