book-to-skill: 기술 서적을 에이전트 스킬로 변환, 온디맨드 로딩으로 토큰 절약

수백 페이지짜리 두꺼운 기술 서적을 정독해도, 몇 달 뒤 터미널에서 코딩할 때는 특정 챕터에 무슨 내용이 있었는지 기억나지 않기 마련입니다. 그렇다고 PDF 전체를 에이전트에 통째로 넘기면 컨텍스트 창이 가득 차고, 모델이 수많은 페이지를 헤매며 엉뚱한 답을 내놓거나 막대한 토큰을 낭비하게 됩니다.

오픈소스 도구 book-to-skill은 이 문제를 해결하기 위해 등장했습니다. 책과 문서를 작업 흐름 속에서 필요할 때만 불러오는 에이전트 플러그인 형태로 바꿔 줍니다.

한 번 컴파일하고 필요할 때만 펼치는 지식

book-to-skill은 단순한 검색 도구가 아니라 비정형 문서를 에이전트 맞춤형 지식으로 변환하는 일종의 지식 컴파일러입니다.

작업은 두 단계로 진행됩니다. 먼저 파이썬 스크립트가 원본 파일에서 텍스트와 메타데이터를 정제해 추출합니다. 이어 모델이 문서 전체를 분석해 핵심 뼈대, 의사결정 규칙, 안티패턴, 챕터별 구조를 표준 Agent Skills 형식으로 정리해 냅니다.

Claude Sonnet 4.5를 기준으로 400페이지 분량의 책 한 권을 변환하는 데 드는 비용은 약 1달러 수준입니다. 변환이 끝나면 에이전트는 평소 가벼운 핵심 색인만 들고 있다가, 특정 주제에 대한 질문을 받았을 때만 해당 챕터 파일을 온디맨드로 불러옵니다.

실제 책을 대상으로 측정한 결과, 단일 쿼리당 토큰 소모량은 약 5K 수준으로 줄었습니다. 책 전체를 프롬프트에 통째로 밀어 넣는 방식과 비교하면 토큰 소비가 24배에서 51배까지 절감됩니다.

사용 환경과 지원 문서

이 도구는 기술 서적 외에도 다양한 포맷을 지원합니다. PDF를 비롯해 EPUB, DOCX, TXT, Markdown, HTML, RTF, MOBI 형식을 모두 다룰 수 있습니다. 사내 아키텍처 결정 기록(ADR), 장애 대응 가이드, 브랜드 디자인 가이드, RFC 표준 등 자주 참고하지만 외우기는 어려운 모든 사내 문서가 대상입니다.

생성된 스킬은 오픈 Agent Skills 표준을 따르므로, 공용 디렉터리에 설치되어 Claude Code, GitHub Copilot CLI, Amp, Codex, Hermes Agent, OpenCode, OpenClaw 등 다양한 에이전트에서 그대로 작동합니다.

설치 역시 터미널에서 npx skills add virgiliojr94/book-to-skill 명령어를 실행하거나 로컬 스킬 폴더에 복사하는 것만으로 손쉽게 끝납니다.

왜 중요한가

긴 기술 문서를 AI에게 다루게 할 때 지금까지는 RAG를 이용해 조각조각 검색하거나 거대한 컨텍스트 창에 전부 던져 넣는 방식이 일반적이었습니다. 하지만 RAG는 책의 전체적인 맥락을 놓치기 쉽고, 거대 컨텍스트는 비용 부담이 크며 환각 위험도 높습니다.

book-to-skill의 영리한 점은 책을 읽는 방식을 실제 엔지니어의 작업 방식과 똑같이 설계했다는 데 있습니다. 문서를 사전에 규칙과 챕터 단위로 구조화해 두고, 필요할 때만 관련 챕터를 꺼내 읽게 만들어 일상적인 추론 비용을 극적으로 낮췄습니다.

개발자 입장에서는 단돈 1~2달러의 변환 비용만 들이면, 책장에 꽂아두고 잊어버리던 전문 서적을 터미널 안에서 즉시 조언해 주는 든든한 사수로 만들 수 있습니다.

물론 스캔 품질이 떨어지는 문서나 복잡한 수식이 얽힌 자료는 사전 추출 과정에서 품질이 떨어질 수 있다는 한계가 있습니다. 그럼에도 긴 문서를 표준 에이전트 스킬로 미리 컴파일해 온디맨드로 활용하는 이 패턴은 향후 엔지니어링 문서 소비 방식에 중요한 기준점을 제시하고 있다고 봅니다.