영상에서 단테는 책이나 문서를 에이전트가 작업 중에 참고할 수 있는 스킬로 정리해 주는 도구인 book-to-skill을 직접 써 봤습니다. 예제로 개역개정 성경 출애굽기 14장을 스킬로 만들고, 이를 근거로 홍해 장면 애니메이션을 제작했습니다. 책 내용을 코드 리뷰나 글쓰기, 영상 제작 같은 실제 작업 기준으로 쓰고 싶은 분, 그리고 그냥 책을 업로드하는 것과 무엇이 다른지 궁금한 분께 맞는 내용입니다.
book-to-skill이 만드는 구조
book-to-skill은 제작자의 공식 GitHub 저장소에서 배포되는 변환 도구입니다. 공식 안내의 생성 파일 목록을 보면 안내 파일, 장별 파일, 용어집이 나뉘어 있습니다. 에이전트가 질문에 필요한 장만 골라 읽게 하는 구조입니다.
여기서 두 가지를 구분하면 이해가 쉽습니다. book-to-skill 자체는 변환 도구이고, 그 결과로 만들어진 책별 폴더(이번 예제에서는 출애굽기 참조 폴더)가 실제로 작업에 쓰는 스킬입니다. 다른 책은 다른 이름의 폴더로 만들면 되고, 여러 문서를 한 스킬로 묶을 수도 있습니다.
설치 위치와 변환 과정
먼저 변환 도구인 book-to-skill을 터미널 명령으로 설치합니다. 설치 위치는 도구마다 다릅니다.
- Codex: 프로젝트 기준
.agents/skills아래 - Claude Code: 프로젝트 기준
.claude/skills아래
두 도구를 모두 쓴다면 각각 설치해야 합니다. 개인 폴더에 설치하면 여러 작업에서 공통으로 쓰고, 프로젝트 폴더에 설치하면 그 프로젝트에서만 씁니다. 이번에는 두 도구의 프로젝트 스킬 폴더에 실제 파일을 배치했습니다.
예제 자료는 성경 전체가 아니라 홍해 장면에 필요한 출애굽기 14장만 준비했습니다. 공식 본문에서 정리한 텍스트를 추출기로 처리했습니다. 자기 책으로 따라 할 때는 변환 스킬 이름 뒤에 책 파일 경로와 만들 스킬 이름을 넣으면 됩니다. PDF나 EPUB도 입력할 수 있고, 성경처럼 서술형 텍스트라면 그렇다고 알려 주면 됩니다.
이번 성경 사례에서는 기본 구조를 그대로 쓰지 않고 성경에 맞게 조정했습니다. AI가 추출한 내용을 사건 순서와 절별 근거로 정리했고, 각색 지침을 따로 작성했습니다. 완성된 책별 폴더도 앞서 말한 스킬 위치에 넣어야 하며, 등록이 보이지 않으면 새 세션에서 확인하면 됩니다.
명시적 호출과 암묵적 호출
질문할 때는 변환 도구가 아니라 완성된 책별 스킬을 부릅니다. Codex CLI에서는 $ 기호 뒤에, Claude Code에서는 / 뒤에 스킬 이름을 씁니다. 영상에서는 본문 근거와 각색을 나눠서 세 개의 숏을 만들어 달라고 요청했습니다.
이렇게 이름을 직접 쓰는 것이 명시적 호출입니다. 이름 없이 성경 장면을 부탁해도 스킬 설명과 요청이 맞으면 에이전트가 스킬을 고를 수 있는데, 이것이 암묵적 호출이며 항상 발동한다는 보장은 없습니다. 단테는 이번 제작에서 참조 파일을 직접 지정해 내용을 확인하고 장면에 적용했으며, 두 도구의 자동 발동을 비교한 실험은 아니라고 밝혔습니다. 따라 해 볼 때는 에이전트가 어떤 파일을 읽었는지, 본문 근거가 무엇인지까지 확인하라고 권했습니다.
본문 근거와 각색을 나누기
스킬을 쓴 이유는 결과물이 본문에 충실한지 확인하기 위해서였습니다. 영상 속 5초짜리 홍해 장면은 긴 과정을 짧게 압축한 연출이므로, 본문에 바다가 순간적으로 갈라졌다고 적혀 있다고 설명하면 안 됩니다. 사람들이 어디로 걸었는지도 중요합니다. 22절과 29절은 이들이 마른 땅으로 지나갔고 물이 좌우에 벽이 되었다고 설명합니다.
모세가 지팡이로 바다를 때렸을까요? 16절에는 지팡이를 들고 손을 내밀라는 지시가 있지만, 바다를 때렸다는 행동은 이 장에 나오지 않습니다. 물벽의 높이나 옷 색깔도 이 장만으로는 정할 수 없습니다. 외모, 색깔, 카메라 구도는 제작자가 정하는 각색 영역입니다. 스킬에 근거와 각색 지침을 분리해 두었기 때문에 이런 구분을 일관되게 지킬 수 있었습니다.
영상 생성에는 ComfyUI의 MiniMax H3 템플릿을 사용했습니다. 해상도 선택 노드에서 가로세로 비율과 크기를 정해 생성 노드로 넘기고, 생성 노드에는 마른 통로, 좌우의 물, 손을 내미는 동작을 적었습니다. 시작 이미지와 끝 이미지는 연결하지 않고 텍스트만으로 생성했으며, 실제 생성은 MCP로 실행했습니다.
책 업로드, RAG와 무엇이 다른가
그냥 책을 업로드해도 AI가 자료를 참고할 수 있고, 서비스에 따라 필요한 부분을 검색해 가져오기도 합니다. RAG는 질문에 맞는 자료를 검색해 답변에 제공하는 방식입니다. 스킬은 어떤 자료를 읽고 어떻게 적용할지에 대한 지침을 함께 묶어 둔다는 점이 다르며, 둘을 함께 쓸 수도 있습니다.
스킬이 메타데이터만 저장하는 것도 아닙니다. 장 파일에는 실제 내용이 들어 있고, 필요한 파일만 읽게 하면 매번 책 전체를 넣는 일을 줄일 수 있습니다. 다만 한 장짜리 예시에서는 스킬이 원문보다 길어질 수도 있으니, 처음 정리하는 비용까지 포함해 비교해야 합니다. 이 영상은 본문을 대조한 활용 사례이며, 토큰 절감률이나 스킬 사용 전후의 성능을 측정한 실험은 아닙니다.
정리
- book-to-skill은 변환 도구이고, 실제로 호출하는 것은 그 결과로 만든 책별 스킬 폴더입니다.
- Codex는
.agents/skills, Claude Code는.claude/skills아래에 두고, 호출은 각각$이름,/이름으로 합니다. - 이름 없이 부르는 암묵적 호출은 항상 발동하지 않으므로, 어떤 파일을 읽었는지 확인하는 습관이 필요합니다.
- 본문 근거와 각색 지침을 나눠 두면 결과물이 원문과 어긋나는지 검수하기 쉽습니다.
- 기술 서적의 설계 원칙을 코드 리뷰에, 글쓰기 책의 기준을 원고 수정에 적용하는 식으로도 쓸 수 있습니다.