이미지: METAL LAB 생성
요약
- virgiliojr94가 기술서 PDF나 문서 폴더를 AI 에이전트용 스킬로 바꿔주는 오픈소스 book-to-skill을 공개했어요
- 실측 기준으로 책 전체를 컨텍스트에 넣는 방식보다 24배에서 51배 적은 토큰으로 같은 질문에 답할 수 있다고 밝혔어요
- GitHub Copilot CLI, Amp, Claude Code가 공통으로 쓰는 오픈 Agent Skills 표준(SKILL.md) 위에서 동작해요
- 저장소
- github.com/virgiliojr94/book-to-skill
- 제작자
- virgiliojr94
- 라이선스
- MIT (변환기 코드·스킬 정의에만 적용, 처리 대상 문서에는 미적용)
- 호환 호스트
- GitHub Copilot CLI, Amp, Claude Code
- 토큰 절감
- 실제 책 기준 24배~51배 (책 전체를 컨텍스트에 넣는 방식 대비)
- 기본 명령
- /book-to-skill <경로|폴더|글롭> [스킬이름]
- 표준 문서
- SKILL.md (오픈 Agent Skills 포맷)
사놓고 안 읽은 책, 다시 여는 대신 물어본다
두꺼운 기술서를 사서 한 번 읽고 나면 3개월 뒤엔 7장에 뭐가 있었는지도 가물가물해지죠. 그럴 때마다 책을 다시 펼쳐 목차를 뒤지는 대신, AI 에이전트에게 그 책 내용을 통째로 맡겨두고 필요할 때마다 물어볼 수 있게 만드는 오픈소스 도구가 github.com/virgiliojr94/book-to-skill 저장소에 공개됐어요. 개발자 virgiliojr94가 만든 book-to-skill은 기술서 PDF나 문서 폴더, 여러 자료 묶음을 하나의 '에이전트 스킬'로 바꿔주는 변환기예요.
왜 PDF를 그냥 넣으면 안 되나
AI 에이전트에게 PDF를 통째로 읽히면, 에이전트는 매 턴마다 목차를 다시 훑고 필요한 부분을 찾아 되짚는 과정을 반복해요. 질문 하나에 답하려고 책 전체 분량의 토큰을 매번 다시 처리하는 셈이죠. book-to-skill은 이 구조화 비용을 변환 시점에 한 번만 치르도록 설계했어요. 책을 챕터 단위 파일로 쪼개 저장해두고, 실제로 그 주제를 물어봤을 때만 해당 챕터를 불러오는 방식이에요. 개발자에 따르면 이렇게 하면 같은 질문에 답하는 데 드는 토큰이 책 전체를 컨텍스트에 넣는 것보다 24배에서 51배 적다고 해요.
어떻게 작동하나
구조는 크게 두 부분으로 나뉘어요. 하나는 결정론적인 파이썬 추출기로, 문서를 깨끗한 텍스트와 메타데이터로 바꿔줘요. 다른 하나는 스펙 기반 생성기인데, 에이전트가 SKILL.md 문서를 따라 그 텍스트를 구조화된 스킬로 조립해요. 이 스킬은 github-copilot, Amp, Claude Code가 공통으로 채택한 오픈 Agent Skills 표준 위에서 돌아가기 때문에 세 호스트 중 어느 걸 쓰든 같은 SKILL.md 포맷을 읽어요.
포맷별로 우선 시도하는 추출 도구도 다른데, 표와 코드 블록이 많은 기술서는 Docling을, 산문 위주 책은 더 빠른 pdftotext를 자동으로 골라 쓴다고 밝혔어요. 페이지 이미지만 있는 스캔본 PDF는 애초에 추출할 텍스트가 없어서, 변환기가 앞부분 페이지를 확인한 뒤 곧바로 멈추고 이유를 설명해준다고 해요. 빈 스킬을 만들어놓고 끝내는 대신 OCR을 먼저 돌리라고 안내하는 구조예요.
어떻게 써보나
어디서 시작하나 — GitHub Copilot CLI, Amp, Claude Code 중 하나를 쓰고 있다면 저장소의 설치 문서(docs/install.md)를 따라 해당 호스트에 book-to-skill 컨버터를 붙이는 게 시작점이에요.
단계별 사용 순서
- 에이전트 채팅창에
/book-to-skill <파일경로|폴더|글롭> [스킬이름]명령을 입력해요. 파일 하나, 폴더 전체, 여러 파일 목록 어느 쪽이든 넣을 수 있어요. - 변환기가 문서 형식을 판단해 알맞은 추출 도구를 자동으로 골라 텍스트와 메타데이터를 뽑아내요.
- 생성기가 이 결과를 SKILL.md와 챕터별 파일로 조립해 호스트에 맞는 스킬 디렉터리에 저장해요.
- 이후에는
/책이름-슬러그 질문내용형태로 물어보면, 에이전트가 필요한 챕터 파일만 불러와 실제 본문 기준으로 답해요.
누가 쓸 수 있나 — GitHub Copilot CLI, Amp, Claude Code처럼 오픈 Agent Skills 표준을 지원하는 호스트라면 쓸 수 있고, MIT 라이선스라 무료로 공개돼 있어요. 다만 책 내용 자체는 저장소에 들어있지 않고, 사용자가 이미 가지고 있는 파일을 변환하는 방식이라 저작권·이용 약관은 사용자 책임이에요.
| 호스트 | 스킬 저장 경로 |
|---|---|
| GitHub Copilot CLI | ~/.copilot/skills/<slug>/ |
| Amp (크로스 에이전트) | ~/.agents/skills/<slug>/ |
| Claude Code | ~/.claude/skills/<slug>/ |
무엇을 해볼 수 있나 — 책 이름을 달았지만 입력은 구조화된 산문이면 뭐든 상관없다고 밝혔어요. 자주 다시 여는 사내 매뉴얼, 규정집, 팀 문서 묶음도 같은 방식으로 스킬화할 수 있어요. 저장소에 소개된 사례로는 개발자 경험(DevEx)을 다룬 책 한 권을 변환해 300명 넘는 엔지니어 설문 자료로 활용한 경우가 있다고 해요.
에디터의 시선
이 도구가 흥미로운 지점은 book-to-skill 자체가 아니라, 그게 딛고 선 표준이에요. 지난 8월 초 GitHub Copilot 앱, 슬래시 명령어로 워크플로 단축 지원 기사에서 다뤘듯 코파일럿 앱은 컨텍스트를 자동 관리하는 쪽으로, AWS, Bedrock 자동 추론 정책에 오픈소스 에이전트 스킬 도입 기사에서 봤듯 앤스로픽이 제안한 Agent Skills 포맷은 AWS 같은 인프라 기업까지 끌어들이는 쪽으로 각각 확장하고 있어요. book-to-skill은 이 두 흐름이 만나는 지점에 있어요 — 개인 사용자의 책 한 권짜리 지식도 기업용 스킬과 같은 SKILL.md 문법으로 묶인다는 뜻이거든요.
이런 류의 도구를 실제로 붙여보면 체감이 늘 비슷해요. PDF를 통째로 던져 넣는 방식은 초반 몇 번은 편하지만, 대화가 길어질수록 같은 목차를 다시 훑는 비용이 누적돼요. 챕터 단위로 쪼개 필요할 때만 불러오는 구조는 그 누적 비용을 없애는 대신, 변환이라는 초기 작업을 한 번 더 요구하죠. 토큰 비용을 신경 써야 하는 팀이라면 자주 참조하는 사내 문서부터 스킬화해보는 게 합리적인 시작점이에요. 반대로 어쩌다 한 번 찾아보는 자료라면 굳이 변환할 이유가 없어요.
스캔본 PDF를 미리 걸러내고 이유를 알려주는 설계도 눈여겨볼 만해요. 빈 스킬을 만들어놓고 나중에 문제를 발견하는 것보다, 변환 전에 멈추는 쪽이 실무에서 시간을 덜 버리게 해줘요. Agent Skills 표준을 지원하는 호스트가 앞으로 더 늘어난다면, 이런 개인용 변환 도구들도 함께 늘어날 걸로 봐요.
댓글