모든 기술 서적, 문서 폴더 또는 소스 모음을 통합된 에이전트 기술(Agent Skill)로 변환하세요 — GitHub Copilot CLI, Amp 또는 Claude Code에서 작업하는 동안 즉시 학습하고, 참조하며, 사용할 수 있습니다.

🏆 Trendshift 선정 2026년 5월 23일 기준 #10 Python Repository of the Day 및 #25 Repository of the Day

이유 · 생성 결과물 · 도서 그 이상 · 사용법 · 요구 사항 · 작동 원리 · Discovery Loop Tax · FAQ · 설치 · 변경 이력 · 성능 · 아키텍처

질문에 답하기 위해 책 전체를 컨텍스트(Context)에 쏟아붓는 것보다 토큰(Token) 사용량을 24배에서 51배까지 절감합니다. (실제 도서를 기준으로 측정됨 (측정 방식)).

3단계 작동 원리:

지정(Point): 파일, 폴더 또는 글로브(Glob)를 지정합니다 — /book-to-skill ./my-book.pdf

추출(Distills): 책을 기술(Skill)로 정제합니다 — 프레임워크, 의사 결정 규칙, 안티 패턴(Anti-patterns) 및 장(Chapter)별 파일로 구성됩니다. 요약이 아닌 구조를 만듭니다.

온디맨드 로드(Your agent loads it on demand): 에이전트에게 요청하세요 — /my-book replication

그러면 에이전트가 올바른 장을 읽고 실제 내용을 바탕으로 답변하며, 환각(Hallucination) 현상이 발생하지 않습니다.

훌륭한 기술 서적을 구매했습니다. 한 번 읽었습니다. 3개월 후에는 7장에 무엇이 있었는지조차 기억나지 않습니다.

일반적인 우회 방법들은 도움이 되지 않습니다:

• 📄 "그냥 PDF에서 검색해 보자" → 답변이 아닌 페이지 목록만 얻게 됩니다.
• 🧠 "에이전트에게 이 책에 대해 물어보자" → 에이전트가 환각(Hallucination)을 일으키거나 해당 콘텐츠가 없다고 말합니다.
• 📝 "읽으면서 노트를 적어두자" → 결국 다시는 열어보지 않을 200줄짜리 문서가 생길 뿐입니다.

book-to-skill은 책을 에이전트가 필요할 때마다 로드할 수 있는 구조화된 기술(Skill)로 변환함으로써 이 문제를 해결합니다.

설치 후, 단순히 /your-book-slug replication이라고 입력하기만 하면 됩니다.

그러면 에이전트가 올바른 장을 읽고 실제 콘텐츠를 바탕으로 답변합니다. 환각(Hallucination)도 없고, PDF를 뒤질 필요도 없습니다. 책이 당신의 워크플로(Workflow)의 일부가 됩니다.

개방형 에이전트 기술(Agent Skills) 표준을 지원하는 모든 호스트에서 작동합니다 — GitHub Copilot CLI, Amp, Claude Code 모두 동일한 SKILL.md 형식을 읽습니다.

/book-to-skill your-book.pdf (또는 폴더, 글로브, 파일 목록)를 실행하면 에이전트의 기술 디렉토리(~/.copilot/skills/<slug>/)에 완전한 기술(Skill)이 생성됩니다.

Copilot CLI의 경우, ~/.agents/skills/<slug>/

Amp 또는 교차 에이전트(cross-agent)의 경우, ~/.claude/skills/<slug>/

Claude Code의 경우:

파일	용도	크기
SKILL.md	핵심 멘탈 모델 (Mental models) + 장 인덱스 (Chapter index)	~4,000 토큰
chapters/ch01-*.md …	각 장당 하나의 파일, 온디맨드 (On-demand) 로드	각 ~1,000 토큰
glossary.md	모든 주요 용어, 장 참조와 함께 알파벳순 정렬	~1,500 토큰
patterns.md	모든 기술, 알고리즘 및 디자인 패턴 (Design patterns)	~2,000 토큰
cheatsheet.md	결정 테이블 (Decision tables) 및 빠른 참조 규칙	~1,000 토큰

장(Chapter) 파일은 온디맨드 (On-demand)로 로드됩니다 — 해당 주제에 대해 질문하기 전까지는 기술 예산 (Skill budget)에 포함되지 않습니다.

이름은 "book"이지만, 입력값은 어떤 구조화된 산문(Structured prose)이든 가능합니다. 동일한 추출 방식은 여러분이 소유하고 끊임없이 다시 읽는 지식에도 적용됩니다:

내부 문서 (Internal documentation) — 아키텍처 결정 기록 (ADR), 런북 (Runbooks), 온보딩 가이드. 전체 docs/ 폴더를 하나의 기술로 접어 넣고 코딩 중에 질문하세요.
브랜드 및 디자인 시스템 (Brand & design systems) — 보이스 가이드라인, 톤 오브 보이스 (Tone-of-voice) 문서, 컴포넌트 원칙. 브랜드 북을 60페이지짜리 PDF를 훑어보는 대신 팀이 질의할 수 있는 기술로 변환하세요.
연구 클러스터 (Research clusters) — 논문 더미와 본인의 노트를 하나의 통합된 기술로 병합하고, 새로운 자료가 들어올 때마다 업데이트하세요 (Update / fold-in 참조).
사양 및 표준 (Specs & standards) — 참조는 하지만 절대 암기하지 않는 RFC, API 계약, 컴플라이언스 문서.

문서를 너무 자주 다시 열어보게 되어 차라리 외워버리고 싶다는 생각이 든다면, 그것이 바로 대상 후보입니다.

/book-to-skill <문서-폴더-경로-또는-글롭>... [skill-name-slug]

지원되는 문서 형식: PDF, EPUB, DOCX, TXT, Markdown, reStructuredText, AsciiDoc, HTML, RTF, MOBI/AZW/AZW3.

예시:

# 여러 파일을 하나의 통합된 기술로 함께 처리
/book-to-skill ~/papers/paper1.pdf ~/notes/export.txt unified-research
# 폴더 내의 모든 지원되는 파일을 함께 처리
...

기술이 생성된 후에는 다른 에이전트 기술과 마찬가지로 사용하세요:

/designing-data-intensive-apps # 핵심 멘탈 모델 (mental models) 로드
/designing-data-intensive-apps replication # 특정 주제를 찾아 설명
/designing-data-intensive-apps ch05 # 5장 심층 분석
...

GitHub Copilot CLI를 사용하는 경우, 파일이 작성된 후 /skills reload를 실행해야 /skills list에 새로운 기술 (skill)이 나타납니다.

Claude Code와 Amp는 다음 세션에서 이를 자동으로 인식합니다.

추출기 (extractor)는 형식별로 순서대로 도구를 시도하며, 사용 가능한 첫 번째 도구를 사용합니다. 설치된 것이 없다면 실행해야 할 명령어를 알려줍니다. 일반 텍스트 (Plain text), Markdown, reStructuredText 및 AsciiDoc은 추가 의존성 (deps)이 필요하지 않습니다.

다음 명령어로 설정을 확인하세요:
python3 scripts/extract.py --check

이 명령은 파일 없이도 모든 형식에 대해 설치된 추출기를 출력하며, 누락된 항목을 설치하기 위한 정확한 명령어를 알려줍니다.

PDF — 도서 유형에 따라 선택:

도서 유형	도구	설치	속도
텍스트 위주 (산문, 표 적음)	pdftotext (poppler)	sudo apt install poppler-utils	⚡ 즉시
텍스트 위주 대체안	pypdf	pip3 install pypdf	⚡ 즉시
텍스트 위주 대체안	pdfminer.six	pip3 install pdfminer.six	⚡ 즉시
기술 서적 (코드, 표, 수식)	docling	pip3 install docling	~1.5s/page

추출이 시작되기 전, 기술 (skill)은 해당 도서가 기술 서적인지 또는 텍스트 위주인지 묻고 적절한 도구를 자동으로 선택합니다. Docling은 마크다운 (markdown) 표와 코드 블록을 보존하며, pdftotext는 산문 위주의 도서에서 더 빠릅니다.

EPUB:

도구	설치	품질
ebooklib + beautifulsoup4	pip3 install ebooklib beautifulsoup4	⭐⭐⭐ 최상
표준 라이브러리 (stdlib) zipfile	내장됨 — 설치 불필요	⭐⭐ 항상 사용 가능

기타 형식:

형식	도구	설치
DOCX	python-docx (fallback: 표준 라이브러리 (stdlib) ZIP/XML)	pip3 install python-docx
HTML	beautifulsoup4 (fallback: 표준 라이브러리 (stdlib) html.parser)	pip3 install beautifulsoup4
RTF	striprtf (fallback: 정규표현식 (regex))	pip3 install striprtf
MOBI / AZW / AZW3	Calibre ebook-convert (외부 앱, pip 아님)	https://calibre-ebook.com/download
TXT / Markdown / reStructuredText / AsciiDoc	내장됨	—

파일 하나 · 폴더 · 글로브 (glob) · 경로 리스트
│
▼
...

추출 벤치마크 (Extraction benchmark) (103페이지 기술 서적, CPU 전용):

방법	시간	토큰 (Tokens)	표 (Tables)	코드 블록 (Code blocks)
pdftotext	0.1s	27K	0	0
Docling	164s	27K (+1.2%)	48	36

실제 변환 사례 (Real conversions) (측정 기준: 페이지, 추출된 토큰, 챕터 자동 감지, Claude Sonnet 4.5 기준 MTok당 $3/$15의 추정 1회 통과 비용):

도서	형식	페이지	토큰 (Tokens)	챕터	~비용
Think Python 2		244	119K	19	$0.88
...

† 챕터 자동 감지는 명시적인 Chapter N / Capítulo N 헤딩이 필요합니다. Pro Git은 섹션 제목을 사용하고 Moby-Dick은 챕터 제목 / 로마 숫자를 사용하므로, 둘 다 자동 분할(auto-segments)되지는 않습니다. 추출 및 변환은 여전히 작동하지만, 섹션을 수동으로 지정해야 합니다. 전체 스킬(skill) 구축 비용은 책 한 권당 대략 $1 정도이며, 이는 매 세션마다 PDF를 다시 읽는 것보다 훨씬 저렴합니다.

설계 원칙 (Design principles) (클릭하여 확장)

완전성보다 밀도 (Density over completeness) — 10,000토큰의 발췌본보다 1,000토큰의 요약본이 더 낫습니다.
실무자 관점 (Practitioner voice) —

PDF를 읽는 에이전트는 단순히 읽기만 하는 것이 아니라, *탐색(navigates)*합니다. 질문 하나를 던지면 에이전트는 목차를 가져오고, 정의할 수 없는 용어를 발견하면 더 많은 페이지를 불러오고, 다시 뒤로 돌아갑니다. 이러한 모든 도약(hop)은 대화 기록(conversation history)에 남게 되며, **이후의 모든 턴(turn)마다 재처리(re-processed)**됩니다. 예산(budget)을 유지하기 위해 서브 에이전트(sub-agent)는 읽은 내용을 매우 높은 압축률로 압축해야만 하며, 이 과정에서 메인 에이전트에게는 **원본과 대조하여 사실 확인(fact-check)을 할 수 없는 저하된 요약본(degraded summary)**을 전달하게 됩니다.

book-to-skill은 이러한 탐색 비용을 컴파일 타임(compile time)에 단 한 번만 지불합니다. 런타임(runtime) 시 어시스턴트는 작은 상주 코어(resident core)와 필요한 사전 컴파일된 챕터 하나만을 로드합니다. 즉, 탐색 루프(discovery loop)도, 맞춤형 압축(compress-to-fit)도 필요 없으며, 추출된 전체 소스는 검증을 위해 디스크에 그대로 유지됩니다.

주장하는 것이 아니라 측정합니다. 세 권의 실제 도서를 대상으로 tools/discovery_tax.py를 실행한 결과 — 단일 타겟 질문에 답변하기 위해 컨텍스트(context)로 들어가는 토큰 수 (book-to-skill = 상주 코어 + 컴파일된 챕터 1개 ≈ 5,000토큰):

도서 (크기)	컨텍스트 덤프 (Context-dump)	탐색 루프 (Discovery loop)	book-to-skill	덤프/루프 대비
Think Python 2 (119K, 작은 챕터들)	119,264	12,152	~5,000	24× / 2.4×
...

이 이점은 챕터 크기에 따라 확장(scales)됩니다. 컨텍스트 덤프와 비교했을 때 일관되게 24~51배의 이득을 보며(이 비용은 매 턴마다 반복됩니다), 일회성 탐색 루프와 비교했을 때는 작은 챕터로 구성된 도서의 경우 2.4배에서, 큰 챕터로 구성된 도서의 경우 15.6배까지 차이가 납니다. 본인의 도서로 재현해 보세요:

python3 tools/discovery_tax.py --full-text /tmp/book_skill_work/full_text.txt --target-chapter 5

솔직한 주의사항: (1) 탐색 수치는 도서의 실제 목차(ToC)/챕터 크기를 모델링한 일회성 비용입니다. 잘 조정된 에이전트는 최상의 결과에 더 가깝게 도달합니다. 반면, 컨텍스트 덤프 비용은 매 턴마다 반복됩니다. (2) 이 도구는 도서를 분할하기 위해 명시적인 Chapter N / Capítulo N 헤딩(heading)이 필요합니다. 제목만 있거나 로마 숫자로 된 도서(그리고 ebooklib 없이 추출된 EPUB)는...

) 깔끔하게 분할되지 않을 것입니다. book-to-skill은 지식에 반복적으로 돌아올 때 승리합니다. 단 한 번의 일회성 읽기라면 일반적인 PDF 에이전트로도 충분합니다.

"그냥 PDF/EPUB를 Claude 프로젝트 컨텍스트(context)에 쏟아부으면 안 되나요?"

할 수는 있습니다. 하지만 매 대화마다 그 토큰 예산을 미리 소모하게 됩니다. 400페이지 분량의 책은 약 200K 토큰입니다. Skill(기술)을 사용하면 질문과 관련된 장(chapter)만 로드됩니다. 일반적으로 SKILL.md 핵심 내용(~4K)과 질문한 해당 장(~1K)이 로드됩니다. 나머지는 필요할 때까지 디스크에 남아 있습니다.

경제성의 핵심은 크기가 아니라 분할 상환(amortization)입니다. 책을 통째로 붙여넣는 것은 모든 세션의 모든 턴마다 영원히 전체 토큰 비용을 지불하는 방식입니다. 반면 book-to-skill은 추출 비용을 단 한 번만 지불하며, 이후의 모든 대화는 필요한 부분만 로드합니다. 컨텍스트 윈도우(context window)가 커질수록 이 점은 더욱 중요해집니다. 큰 윈도우는 데이터 주입을 가능하게 만들 뿐, 저렴하게 만들지는 않기 때문입니다.

더 중요한 점은 다음과 같습니다: 원문 텍스트 주입은 검색(retrieval)입니다. Skill은 추론(reasoning)입니다. 장(chapter) 파일을 로드할 때, Claude는 키워드 일치 여부를 검색하는 것이 아닙니다. 읽기용이 아니라 적용을 위해 구조화된, 미리 추출된 명명된 프레임워크(frameworks), 원칙(principles), 그리고 멘탈 모델(mental models)을 가지고 작업하는 것입니다.

"Claude는 이제 1M 토큰 컨텍스트 윈도우를 가지고 있는데, 그냥 책 전체를 로드해 두면 안 되나요?"

윈도우가 커지는 것은 무엇이 들어갈 수 있는지를 바꾸는 것이지, 무엇이 영리한지를 바꾸는 것이 아닙니다. Skill이 대체재가 될 수 없는 세 가지 이유는 다음과 같습니다:

1. 토큰당, 호출당 비용을 지불합니다. 1M 윈도우가 해당 토큰들을 무료로 만들어주지는 않습니다. 오히려 크고 반복적인 청구서를 가능하게 만들 뿐입니다. Skill은 메가바이트(MB)가 아닌 킬로바이트(KB) 단위로 로드합니다.
2. 채워질수록 회상(Recall) 능력이 저하됩니다. 모델은 거의 가득 찬 컨텍스트 속에 파묻힌 특정 사실을 검색할 때 정밀도를 잃습니다 ("lost in the middle" 현상). 하나의 질문에 답하는 데 있어서는 200K의 원문 산문보다 1K의 큐레이션된 장(chapter)이 훨씬 뛰어납니다.
3. 윈도우 ≠ 구조. 컨텍스트에 들어있는 전체 책은 여전히 모델이 매 턴마다 다시 파싱(parse)해야 하는 원문 텍스트일 뿐입니다. Skill은 미리 추출된 프레임워크를 제공합니다. 즉, 검색이 아닌 추론을 제공하는 것입니다.

큰 윈도우는 다시는 필요하지 않을 자료를 한 번 훑어보는 용도로 사용하세요. Skill은 반복적으로 찾아보게 될 지식을 위해 사용하세요.

"이것은 그냥 RAG 아닌가요?"

RAG는 쿼리 시점 (query time)에 작동합니다: 책을 청크 (chunk)로 나누고 → 모든 것을 임베딩 (embed) 하고 → 유사한 벡터를 찾아 → 프롬프트 (prompt)에 주입합니다. 이는 "X에 대해 말하는 부분을 찾아줘"라는 요청에 최적화되어 있습니다.

book-to-skill은 컴파일 시점 (compile time)에 작동합니다: 단 한 번의 심층 분석 실행을 통해 저자의 실제 프레임워크 (frameworks)를 추출하고, 이름을 붙이고, 각각을 언제 사용해야 하는지 설명하며, 안티 패턴 (anti-patterns)을 포착합니다. 결과물은 저자가 수년간 구축해 온 구조이지, 저자의 문장들을 대상으로 한 유사도 검색 (similarity search)이 아닙니다.

RAG는 다음과 같이 답합니다: "당신의 쿼리와 유사한 청크들은 여기 있습니다."

Skill은 다음과 같이 답합니다: "이 저자가 구축한 12가지 프레임워크가 여기 있습니다. 바로 추론 (reasoning)에 사용할 준비가 되어 있습니다."

작업의 형태에 따라 선택하세요:

넓고 얕은 (Wide and shallow)— 수십 권의 책으로 이루어진 라이브러리, "X를 언급하는 부분을 찾아줘" → RAG 도구 (예: CandleKeep)가 승리합니다.
좁고 깊은 (Narrow and deep)— 한 권의 책 또는 밀접하게 관련된 소스들의 집합, 작업 중에 적용하는 프레임워크 → book-to-skill이 승리합니다.

이 둘은 경쟁 관계가 아니라 상호 보완적입니다: RAG가 책장을 인덱싱 (indexing)한다면, book-to-skill은 책 한 권을 마스터 (master)합니다.

"인기 있는 책들은 이미 Claude의 학습 데이터에 있습니다. 왜 굳이 이걸 하나요?"