633 ／ 633
기술 서적을 AI 에이전트 스킬로 전환하는 book-to-skill
두꺼운 기술 서적이나 방대한 문서 더미를 읽고 시간이 지나면 핵심 내용이 희미해진다. PDF를 검색해도 원하는 답이 아닌 페이지 목록만 돌아오며, AI 에이전트에게 물어도 때로는 정확하지 않은 정보를 주거나 아예 모른다고 답한다. book-to-skill은 이런 문제들을 해결하고자 기술 서적, 문서 폴더, 여러 소스 컬렉션을 ‘통합 에이전트 스킬’로 변환하는 오픈소스 도구이다. 공개 이후 깃허브에서 별 2만 8천여 개를 받으며 빠르게 주목받았다. 이 도구는 GitHub Copilot CLI, Amp, Claude Code, Hermes Agent 등 Agent Skills 오픈 표준을 지원하는 다양한 호스트에서 활용할 수 있다.
기술 서적을 에이전트 스킬로
일반적인 학습 방식으로는 기술 서적의 방대한 내용을 효과적으로 관리하기 어렵다. PDF 검색은 단순히 키워드를 포함한 페이지를 찾아줄 뿐 실제 답변을 제공하지 않는다. 에이전트에 책 내용을 통째로 넣으면 토큰을 과도하게 소모하거나 부정확한 답변을 생성하기도 한다. 또한 직접 작성한 학습 노트는 시간이 지나면 다시 열어보지 않는 경우가 많다.
book-to-skill은 이러한 한계를 극복하고 책의 내용을 구조화된 스킬로 변환하여 에이전트가 필요할 때 활용하도록 돕는다. 이 과정은 다음 3단계로 진행된다.
- 지정: 사용자는 파일, 폴더, 또는 글로브 패턴을 이용해 변환할 자료를 지정한다. 예를 들어
/book-to-skill ./my-book.pdf명령어를 사용한다. - 증류: 도구는 자료를 프레임워크, 결정 규칙, 안티패턴, 챕터별 파일 등 스킬 형태로 증류한다. 이는 단순 요약이 아닌 구조화된 지식을 생성한다.
- 로드: 에이전트는 사용자의 질문에 따라 필요한 스킬을 로드한다. 예를 들어
/my-book replication이라고 입력하면 에이전트가 해당 챕터를 읽고 실제 내용에 기반해 답변을 생성한다. 이 과정에서 환각(hallucination) 현상이 발생하지 않는다.
에이전트 스킬의 구성 요소
book-to-skill은 지정된 자료를 변환하여 에이전트 스킬 디렉토리에 여러 파일을 생성한다. 각 파일은 특정 목적을 지닌다.
다음은 book-to-skill your-book.pdf 명령 실행 시 생성되는 주요 파일과 그 목적이다.
| 파일 | 목적 | 크기 |
|---|---|---|
SKILL.md |
핵심 멘탈 모델 및 챕터 인덱스 | ~4,000 토큰 |
chapters/ch01-*.md |
챕터별 파일 (요청 시 로드) | 각 ~1,000 토큰 |
glossary.md |
핵심 용어, 알파벳순 정렬, 챕터 참조 | ~1,500 토큰 |
patterns.md |
기술, 알고리즘, 디자인 패턴 | ~2,000 토큰 |
cheatsheet.md |
의사결정 테이블 및 빠른 참조 규칙 | ~1,000 토큰 |
여기서 챕터 파일은 사용자가 해당 주제를 질문할 때만 로드된다. 따라서 에이전트가 항상 모든 내용을 메모리에 올릴 필요가 없으며, 이는 스킬의 효율성을 높이는 중요한 요소이다.
압도적인 토큰 효율성
기존 방식에서는 책 전체를 에이전트의 컨텍스트에 한 번에 넣어 질문에 답하는 경우가 많다. 이 경우 에이전트는 목차를 다시 확인하고, 내용을 되돌아가서 처리하는 등 ‘디스커버리 루프 세금’이라는 추가 비용을 지불한다. book-to-skill은 이러한 구조화 비용을 변환 시점에 한 번만 처리한다.
이러한 접근 방식으로, 실제 서적을 대상으로 측정했을 때 book-to-skill은 책 전체를 컨텍스트에 덤핑하는 방식보다 질문당 24배에서 51배 적은 토큰을 사용한다. 이는 비용 절감과 응답 속도 향상으로 이어진다.
책을 넘어 다양한 정보원에 적용
이 도구의 이름은 ‘book’이지만, 실제로는 구조화된 모든 유형의 산문 자료에 적용할 수 있다. 사용자가 자주 참고하고 다시 읽는 모든 지식은 스킬로 변환될 후보이다.
- 사내 문서: 아키텍처 결정 기록, 런북, 온보딩 가이드 등을 스킬로 변환해 코딩 중 실시간으로 질의한다.
- 브랜드 및 디자인 시스템: 브랜드 가이드라인, 톤앤매너 문서, 컴포넌트 원칙 등을 스킬로 만들어 팀원이 60페이지짜리 PDF를 일일이 읽지 않고도 필요한 정보를 얻도록 돕는다.
- 연구 클러스터: 여러 논문과 개인 노트 묶음을 단일 스킬로 통합하고, 새로운 자료가 추가될 때마다 업데이트한다.
- 사양 및 표준: RFC, API 계약, 규제 문서 등 자주 참조하지만 암기하기 어려운 자료들을 스킬로 만들어 활용한다.
book-to-skill의 작동 원리
book-to-skill은 두 가지 핵심 부분으로 구성된다. 첫째는 파이썬 익스트랙터(extractor)이다. 이는 문서에서 깔끔한 텍스트와 메타데이터를 추출하는 결정론적 모듈이다. 둘째는 스펙 기반의 제너레이터(generator)이다. 이 모듈은 익스트랙터가 추출한 정보를 바탕으로 에이전트가 따를 SKILL.md 형식의 구조화된 스킬을 생성한다. 챕터별 파일은 필요에 따라 로드되어 스킬 크기를 작게 유지한다.
이 도구는 PDF, EPUB, DOCX, MD, HTML, RTF, MOBI 등 다양한 형식을 지원하며, 각 형식에 맞는 최적의 추출 도구를 사용한다. 특히 기술 서적의 경우 docling을 사용해 코드 블록이나 표를 보존한다.
저작권과 공정 이용에 대한 이해
book-to-skill은 어떠한 책 내용도 포함하지 않는다. 이는 사용자가 이미 소유한 파일을 변환하는 도구일 뿐이다.
- 처리 과정은 로컬에서 이루어진다: 자료 추출과 분석은 사용자의 기기에서 진행되며, 파일이 외부로 업로드되지 않는다.
- 사용자 소유 자료를 활용한다: 사용자는 구매한 책, 회사 소유 문서, 읽을 권리가 있는 논문 등 자신이 소유한 자료를 사용한다.
- 생성된 스킬은 개인 노트이다: 생성된 스킬은 프레임워크 이름, 정의, 핵심 요약 등 구조화되고 합성된 파생물이며, 원문 텍스트를 그대로 복제한 것이 아니다. 개인 학습 노트와 같이 사적으로 활용하는 것을 전제로 한다.
- 재배포는 금지된다: 저작권이 있는 저작물의 스킬을 생성하여 공유하거나 재배포하는 것은 저작권 침해로 이어질 수 있다. 따라서 타사 서적의 스킬은 개인적으로만 보관해야 한다.
이 프로젝트는 도구이며, 그 활용에 대한 책임은 사용자에게 있다.
출처
- virgiliojr94, book-to-skill (GitHub, MIT License)
- https://github.com/virgiliojr94/book-to-skill