기술 서적을 코딩 에이전트 스킬로 변환하는 방법

기술 서적을 에이전트 스킬로 변환하기: 결과물

기술 서적을 에이전트 스킬로 변환하려면 PDF, EPUB, DOCX 내보내기 파일 또는 이미 보유한 내부 문서 폴더를 변환기에 지정하면 됩니다. 변환기는 스킬 디렉터리를 생성합니다. 여기에는 명명된 프레임워크와 챕터 색인을 담은 진입 파일 하나와, 질문이 필요할 때만 에이전트가 읽어 들이는 챕터별 파일들이 포함됩니다. 책 전체가 컨텍스트 윈도우에 들어가는 일은 없으며, 색인만 포함됩니다.

이는 처음부터 에이전트 스킬 작성하기와는 정반대의 작업입니다. 처음부터 작성할 때는 이미 알고 있는 절차를 코드로 구현하지만, 여기서는 지식은 존재하지만 아무도 접근할 수 없는 상태입니다. 예를 들어 800페이지 분량의 벤더 PDF나, 작성자가 퇴사한 이후 한 번도 열어보지 않은 핸드북 같은 경우입니다. 이 작업의 핵심은 압축과 색인화입니다. '스킬'이라는 용어가 생소하다면 먼저 에이전트 스킬의 실제 정의를 읽어 보시기 바랍니다.

여기서 사용하는 변환기는 MIT 라이선스를 따르는 book-to-skill이며, 사용자 본인의 머신에서 실행됩니다. 2026년 8월 기준 현재 태그는 v1.4.0입니다. 도구 자체보다 도구가 생성하는 구조가 더 중요하며, FAQ 이전의 마지막 섹션에서는 동일한 구조를 수동으로 구축하는 방법을 설명합니다.

토큰 예산이 전체 설계의 핵심인 이유

컨텍스트 윈도우에 전체 내용을 붙여넣은 책은 대화가 이어질 때마다 해당 크기만큼의 비용을 발생시킵니다. 반면 스킬은 진입 파일(entry file)의 비용만 한 번 지불하며, 질문과 관련된 챕터의 비용만 추가로 발생합니다. 프로젝트 문서는 생성되는 각 파일에 대한 예산을 정의합니다.

[
  {
    "label": "SKILL.md entry file",
    "tokens": "4,000"
  },
  {
    "label": "One chapter file",
    "tokens": "1,000"
  },
  {
    "label": "glossary.md",
    "tokens": "1,500"
  },
  {
    "label": "patterns.md",
    "tokens": "2,000"
  },
  {
    "label": "cheatsheet.md",
    "tokens": "1,000"
  }
]

진입 파일인 SKILL.md은 4,000 토큰으로 제한되며, 명시된 프레임워크와 챕터 인덱스를 포함합니다. 각 챕터 파일은 약 1,000 토큰이며, 호출되기 전까지는 디스크에 머무릅니다. 지원 파일들의 예산도 이와 유사합니다. glossary.md는 1,500 토큰, patterns.md은 2,000 토큰, cheatsheet.md는 1,000 토큰입니다.

이러한 예산은 Claude Code가 실제로 컨텍스트를 소비하는 방식과 일치합니다. 스킬의 description는 스킬 목록에 포함되어 모델이 해당 스킬의 존재를 인식하게 합니다. 스킬이 호출되면 본문이 로드되며, 한 번 로드된 내용은 세션이 끝날 때까지 컨텍스트에 유지되므로 진입 파일의 모든 줄은 반복적인 비용을 발생시킵니다. 지원 파일은 에이전트가 읽을 때만 로드되므로, 챕터별로 파일을 분리하는 것이 비용 효율적입니다.

진입 파일의 토큰 수 뒤에는 더 엄격한 제한이 존재합니다. 자동 압축(auto-compaction) 기능이 긴 대화를 요약할 때, Claude Code는 요약본 뒤에 각 스킬의 가장 최근 호출 내용을 다시 첨부합니다. 이때 각 스킬의 첫 5,000 토큰을 유지하며, 재첨부된 모든 스킬을 합쳐 25,000 토큰이라는 통합 예산을 적용합니다. 5,000 토큰 이내의 진입 파일은 압축 후에도 전체가 유지되지만, 20,000 토큰짜리 진입 파일은 앞부분 4분의 1만 남게 되며, 나머지 4분의 3이 무엇인지 알려주는 정보는 없습니다.

이것이 바로 점진적 공개(progressive disclosure)의 원리입니다. 항상 비용을 지불할 가치가 있는 작은 인덱스를 유지하고, 나머지 방대한 자료는 에이전트가 필요할 때만 여는 문 뒤에 두는 방식입니다. Claude Code가 컨텍스트 윈도우를 관리하는 방법에서 이러한 계산 방식의 나머지 부분을 다룹니다.

VPS에 컨버터를 설치하고 특정 릴리스로 고정하기

이 스킬은 git 저장소로 제공됩니다. 사용하는 에이전트의 스킬 디렉터리에 복제하십시오. 디렉터리 이름이 슬래시 명령어가 되므로, 복제 경로는 임의로 정해서는 안 됩니다.

git clone --depth 1 --branch v1.4.0 \
  https://github.com/virgiliojr94/book-to-skill.git \
  ~/.claude/skills/book-to-skill

--branch은 태그를 인자로 받으므로, 이 명령은 v1.4.0 버전까지만 체크아웃하며 이후의 변경 사항은 포함하지 않습니다. 스킬은 에이전트가 따르는 일련의 지침이므로, 검토되지 않은 변경 사항은 서버에서 실행되는 동작을 바꿀 수 있습니다. 따라서 버전을 고정해야 합니다. GitHub Copilot CLI는 대신 ~/.copilot/skills/을 읽으며, Amp는 ~/.agents/skills/를 읽습니다.

한 줄로 설치하는 npx skills add virgiliojr94/book-to-skill 명령도 있습니다. 이 명령은 최신 버전을 가져옵니다. 도구를 시험해 볼 때는 이 명령을 사용하십시오. 반복해서 실행해야 하는 작업에는 고정된 복제본을 사용하십시오.

이제 서버에 어떤 추출기가 있는지 확인하십시오:

cd ~/.claude/skills/book-to-skill
python3 scripts/extract.py --check

--check은 설치된 추출기를 보고하고, 누락된 각 추출기에 대한 설치 명령어를 출력합니다. 이 패키지는 Python 3.9 이상이 필요합니다.

복제 후 자동 완성 목록에 /book-to-skill가 나타나지 않으면 에이전트를 재시작하십시오. Claude Code는 세션 시작 시점에 존재하던 스킬 디렉터리만 감시하므로, 2분 전에 생성한 ~/.claude/skills/은 아직 감시 대상에 포함되지 않았을 수 있습니다.

실제로 필요한 추출기는 무엇입니까?

모든 형식에 표준 라이브러리 대체 수단이 포함되어 있으므로 Python 외에 별도로 필요한 것은 없습니다. 대체 수단의 성능은 다소 떨어지지만, 소규모 서버에서는 사용하지 않는 추출기를 설치하느라 시간을 낭비할 필요가 없습니다.

• pdftotext는 poppler-utils 패키지에 포함되어 있으며, 텍스트가 많은 PDF를 즉시 처리합니다. sudo apt install poppler-utils 명령어로 설치하십시오.
• pypdf 및 pdfminer.six은 PDF를 위한 Python 대체 수단입니다.
• docling는 표와 코드 목록이 중요한 기술 문서 PDF를 위한 도구입니다. 이 프로젝트에서는 페이지당 약 1.5초가 소요되는 것으로 측정되었습니다.
• ebooklib과 beautifulsoup4은 EPUB을 올바르게 읽어들입니다. 이 도구가 없으면 표준 라이브러리인 zipfile 리더를 사용합니다.
• python-docx은 DOCX를, striprtf는 RTF를 읽습니다.
• MOBI 및 AZW 파일에는 Calibre의 ebook-convert가 필요합니다.
• ocrmypdf은 텍스트 계층이 전혀 없는 스캔된 도서에 대해 OCR(광학 문자 인식)을 수행합니다.

Ubuntu 24.04에서 일반적인 pip3 install pypdf 명령을 실행하면 다음과 같은 오류가 발생하며 중단됩니다.

error: externally-managed-environment

이는 pip가 고장 난 것이 아닙니다. Ubuntu와 Debian은 시스템 Python을 apt가 관리하도록 설정하므로, pip가 시스템 영역에 쓰기 작업을 수행하는 것을 거부합니다. 두 가지 해결 방법이 있습니다. sudo apt install poppler-utils은 바이너리를 설치하므로 pip가 전혀 필요 없으며, pdftotext는 대부분의 일반적인 PDF를 단독으로 처리할 수 있습니다. Python 추출기를 사용하려면 가상 환경을 구축하고 그 안에서 에이전트를 실행하십시오. 그러면 스킬이 호출하는 python3이 패키지가 설치된 인터프리터가 됩니다.

python3 -m venv ~/.venvs/book-to-skill
source ~/.venvs/book-to-skill/bin/activate
pip install "$HOME/.claude/skills/book-to-skill[pdf,epub,docx]"
claude

저장소는 pdf, epub, docx, rtf, technical 및 all과 같은 추가 기능을 선언하며, 여기서 technical은 docling입니다. 프로젝트 설치 페이지에는 pip install "book-to-skill[pdf,epub,docx]"도 표시되어 있으나, 2026년 8월 기준으로 해당 이름은 PyPI에 게시되지 않았으므로 위와 같이 직접 체크아웃하여 설치하십시오.

docling은 도서 처리에 필요할 때까지 설치하지 마십시오. 이 도구는 머신 러닝 스택을 함께 설치하므로, 소규모 플랜을 사용하는 경우 설치 전에 여유 디스크 공간을 확인하십시오.

문서 폴더를 대상으로 실행하기(헤드리스 모드 포함)

이 명령어는 파일, 폴더, 따옴표로 묶인 glob 패턴, 또는 여러 경로를 한꺼번에 인자로 받을 수 있으며, 뒤에 선택적으로 스킬 이름을 지정할 수 있습니다. 한 디렉터리에 넣을 수 있는 모든 것이 작동하며, 인터넷 프로토콜을 정의하는 문서인 RFC(Request for Comments) 세트도 포함됩니다.

/book-to-skill ~/library/platform-docs/ platform-handbook
/book-to-skill "~/books/*.epub" my-library
/book-to-skill ~/papers/paper1.pdf ~/notes/export.txt unified-research

셸이 스킬에 전달하기 전에 glob 패턴을 확장하지 않도록 따옴표로 묶으십시오. 기존 스킬 디렉터리를 명령어로 지정하면 새로운 스킬을 생성하는 대신 기존 스킬에 새로운 소스를 병합합니다.

대화형 실행 모드에서는 몇 가지 질문을 합니다. 자료가 기술적인지 텍스트 위주인지에 따라 추출기가 결정됩니다. 참조 깊이(reference depth)를 원하는지 학습 깊이(study depth)를 원하는지에 따라 챕터별 예산이 결정됩니다. 스킬의 이름은 무엇으로 할지, 어떤 스킬 루트에 저장할지도 결정해야 합니다. 또한 생성 전에 토큰과 예상 소요 시간을 출력하고 사용자의 확인을 기다립니다.

헤드리스 실행 모드에는 질문에 답할 사용자가 없습니다. 사용자가 호출 가능한 스킬은 claude -p에서 작동합니다. 프롬프트 문자열에 슬래시 명령어를 넣으면 Claude Code가 실행 시작 전에 이를 확장합니다. 따라서 동일한 프롬프트 내에서 질문에 답하십시오.

claude -p "/book-to-skill ~/library/platform-docs/ platform-handbook
The sources are technical. Use reference depth. Write the skill to
~/.claude/skills/. Do not publish it to GitHub. Proceed without asking me." \
  --allowedTools "Bash,Read,Write,Edit"

--allowedTools는 실행에 필요한 도구를 미리 승인합니다. 터미널이 연결되지 않은 상태에서 권한 승인 프롬프트가 나타나면 실행이 완료되지 않기 때문입니다. --output-format json을 추가하면 결과에 total_cost_usd가 포함되는데, 이는 실제 청구 금액이 아닌 클라이언트 측의 예상치입니다.

추출 과정에서는 모델이 읽기 전에 모든 소스를 /tmp 아래의 임시 작업 디렉터리로 통합하며, 실행의 마지막 단계에서 해당 디렉터리를 삭제합니다. 추출에 실패한 소스는 건너뛰어 배치 작업이 중단되지 않도록 합니다. 즉, 실행 결과는 성공으로 보고되더라도 실제로는 제공한 파일보다 적은 수의 파일을 읽었을 수 있습니다. 최종 보고서의 파일 목록과 폴더 내의 파일을 비교하십시오. 누락된 챕터는 대개 소스 파일이 누락된 경우입니다.

에이전트에게 맡겨도 괜찮은 서버에서 실행하십시오. VPS에서 안전하게 Claude Code 실행하기에서 권한 관련 내용을 다룹니다.

출력물이 저장되는 위치와 코딩 에이전트의 탐색 방법

생성된 스킬은 스킬 루트 디렉터리에 저장됩니다. 이 중 두 곳이 중요합니다.

• ~/.claude/skills/<skill-name>/은 개인용이며, 해당 머신의 모든 프로젝트에서 사용할 수 있습니다.
• .claude/skills/<skill-name>/은 리포지토리 내부에 위치하며 리포지토리와 함께 이동합니다.

어느 경로를 선택하든 그 안에는 SKILL.md이 있으며, 챕터별로 파일이 하나씩 들어 있는 chapters/ 디렉터리와 지원 파일들이 존재합니다. 디렉터리 이름이 곧 명령어가 되므로, ~/.claude/skills/platform-handbook/을 실행하면 /platform-handbook이 호출되며, 그 뒤에 주제나 일반적인 질문을 덧붙일 수 있습니다.

편의성보다는 라이선스 정책에 따라 루트를 선택하십시오. 구매한 도서로 만든 스킬은 개인 디렉터리에 두어야 합니다. 팀이 직접 작성한 문서로 만든 스킬은 리포지토리에 두어야 하며, 이 경우 여러 리포지토리에서 하나의 스킬 공유하기가 다음 해결 과제가 됩니다.

스킬을 추가할 때마다 발생하는 비용이 있습니다. 각 스킬의 설명은 모델이 사용 여부를 결정할 수 있도록 스킬 목록에 유지되는데, 결합된 설명 텍스트는 항목당 1,536자로 제한되며 전체 목록에도 예산이 정해져 있습니다. 도서 스킬이 10개라면 10개의 설명이 이 예산을 두고 경쟁하게 됩니다. 항상 이름으로 호출하는 스킬의 경우, 생성된 프론트매터에 다음 한 줄을 추가하십시오.

---
name: platform-handbook
description: Frameworks and chapter index from the internal platform handbook.
disable-model-invocation: true
---

disable-model-invocation: true를 사용하면 설명이 컨텍스트에서 완전히 제외되지만, /platform-handbook을 입력하면 스킬은 여전히 전체가 로드됩니다. 자동 탐색 기능을 포기하는 대신 더 조용한 컨텍스트 윈도우를 얻게 됩니다.

라이선스: MIT는 변환기에 적용되며 도서에는 적용되지 않음

이 부분은 기술적인 문제가 아닌 법적 문제이므로 정확히 이해해야 합니다.

• MIT 라이선스는 변환기 코드와 스킬 정의에만 적용됩니다. 변환기에 입력하는 문서와는 무관합니다.
• 구매한 도서를 직접 제어하는 하드웨어에서 변환기를 실행하는 것은 본인 소유의 복사본으로 노트를 만드는 행위입니다.
• 결과물을 게시하는 것은 배포에 해당하며, 도구에 적용된 MIT 라이선스는 타인의 도서에서 파생된 결과물을 배포할 권리를 부여하지 않습니다.
• 출력물은 2차 저작물입니다. 프레임워크와 챕터 요약은 여전히 원문의 영향을 받으며, 2차 저작물은 원문의 저작권법을 따릅니다.
• 재배포가 불가능한 자료로 만든 스킬은 해당 스킬을 생성한 머신 내부에만 보관해야 합니다. 공개 저장소나 공유 팀 마켓플레이스에 올리지 마십시오.
• 본인이 저작권을 소유했거나 오픈 라이선스가 적용된 자료(팀이 작성한 문서나 재배포가 허용된 표준 등)인 경우에만 게시하십시오.

이 도구는 이러한 원칙을 바탕으로 설계되었습니다. 도서 콘텐츠를 포함하지 않으며, 추출은 로컬에서 실행됩니다. 게시 단계에서는 저장소 공개 여부를 별도로 질문하며, 시스템이 임의로 판단하지 않고 반드시 public 또는 private 중 하나를 직접 입력받습니다. 해당 프롬프트는 라이선스 결정과 직결되므로 신중하게 처리하십시오.

사내 핸드북은 또 다른 문제를 안고 있습니다. 핸드북에는 생각보다 자주 자격 증명 정보가 포함되어 있으며, 변환기는 아무도 열어보지 않던 PDF를 에이전트가 수시로 읽어 들이는 파일로 변환합니다. 생성된 파일을 커밋하기 전에 반드시 한 번 확인하고, AI 에이전트에서 비밀 정보 제외하기를 참조하십시오.

변환 비용은 얼마입니까?

아래 수치는 저희가 측정한 것이 아니라 프로젝트 측에서 직접 공개한 측정값입니다.

[
  {
    "label": "Think Python 2",
    "cost_usd": 0.88
  },
  {
    "label": "Working Backwards",
    "cost_usd": 0.96
  },
  {
    "label": "Pro Git",
    "cost_usd": 1.23
  },
  {
    "label": "Moby-Dick",
    "cost_usd": 1.42
  }
]

프로젝트에서 측정한 4권의 도서를 기준으로, 변환 1회당 비용은 0.88에서 1.42 미국 달러 사이이며, Pro Git의 경우 1.23입니다. 이 수치는 Claude Sonnet 4.5를 기준으로 측정되었고, 토큰 수는 tiktoken을 사용하여 cl100k_base에서 집계했으며, 2026년 8월 기준으로 프로젝트의 docs/performance.md에 게시되어 있습니다. 실제 비용은 사용하는 모델과 가격 정책에 따라 달라집니다.

또한 프로젝트 문서에 따르면, 전체 도서 내용을 컨텍스트에 붙여넣는 방식보다 기술(skill)을 통해 단일 질문에 답변하는 방식이 토큰을 24배에서 51배 더 적게 사용합니다. 이는 확정된 수치가 아니라 절감 효과의 경향성을 나타내는 것이며, 도서의 종류와 질문 내용에 따라 달라질 수 있습니다. 구조적인 핵심은 변환 비용은 1회만 발생하지만, 컨텍스트 덤프 방식은 해당 도서가 필요한 모든 대화마다 비용이 발생한다는 점입니다.

PDF를 붙여넣거나 RAG 인덱스를 구축하지 않는 이유는 무엇입니까?

텍스트를 붙여넣는 방식은 하나의 문서에 관한 하나의 질문에는 적합한 해결책입니다. 하지만 같은 책을 화요일에도 사용하고 금요일에도 다시 사용해야 한다면, 매번 전체 내용을 입력해야 하므로 비효율적입니다.

검색 기반 생성(RAG, retrieval augmented generation)은 질의 시점에 검색을 수행하여 사용자의 단어와 일치하는 구절을 반환합니다. 정확한 문장이 필요할 때는 강력하지만, 유용한 정보가 챕터 전체에 걸쳐 있는 프레임워크라면 단일 구절만으로는 내용을 파악하기 어려워 효과가 떨어집니다. 스킬(Skill)은 변환 시점에 이러한 정보를 한 번 추출하여 구절이 아닌 구조화된 형태로 저장합니다.

솔직한 한계점은 다음과 같습니다. 생성된 스킬은 모델이 작성한 손실이 있는 요약본입니다. 이는 학습 보조 도구일 뿐이며, 원본은 여전히 원본입니다. 정확한 문구가 법적 또는 프로토콜상 중요한 의미를 지닌다면 PDF를 보관하고 그 내용을 인용하십시오. MCP 서버 및 규칙 파일과 비교한 스킬에서 각 접근 방식이 적합한 상황을 다룹니다.

실패 유형 및 확인되는 메시지

스캔된 PDF에서 결과물이 나오지 않습니다. 추출기는 첫 페이지에서 텍스트 레이어를 확인하며, 텍스트가 없으면 400페이지에 달하는 이미지를 모두 처리하지 않고 설명을 출력하며 중단합니다. 먼저 ocrmypdf input.pdf output.pdf를 실행한 뒤, 해당 출력 파일을 입력으로 사용하십시오.

pip 설치가 거부됩니다. Ubuntu 24.04에서 발생하는 error: externally-managed-environment은 apt가 시스템 Python을 보호하기 때문입니다. 위에서 설명한 가상 환경을 사용하거나, poppler-utils을 설치하여 pip 사용을 완전히 배제하십시오.

챕터가 잘못 나뉩니다. 챕터 감지는 Chapter 7와 같은 명시적인 제목이나 해당 언어의 변형을 찾습니다. 일반적인 섹션 제목이나 로마 숫자를 사용하는 책은 분할이 정확하지 않으며, 이 경우 도구가 추측하게 두기보다 챕터 시작 위치를 직접 지정해야 합니다.

명령어를 찾을 수 없습니다. 자동 완성에서 /book-to-skill이 보이지 않는다면, 세션 시작 후에 skills 디렉터리가 생성된 것입니다. 에이전트를 재시작하십시오.

Docling 처리가 너무 오래 걸립니다. 페이지당 약 1.5초가 소요되므로 긴 책은 CPU 시간이 수 분간 필요하며, 공유 서버에서는 호스팅 중인 다른 작업과 자원을 경쟁하게 됩니다. 실행 시 콘텐츠 유형을 묻는 질문에 "text-heavy"라고 답하거나, scripts/extract.py를 직접 실행할 때 --mode text 옵션을 전달하십시오. --mode technical은 docling을 선택하는 답변입니다.

소스 파일이 조용히 사라집니다. 읽을 수 없는 파일은 배치 작업이 완료될 수 있도록 건너뜁니다. 작업이 완료되면 입력한 것보다 적은 수의 소스에 대해 성공했다고 보고하며, 이 내용은 최종 보고서의 파일 목록에서만 확인할 수 있습니다.

수동으로 동일한 패턴 적용하기

이 도구는 편의를 위한 것입니다. 구조 자체가 이전 가능한 부분이며, 텍스트 편집기를 사용하면 보유한 모든 참고 자료에 대해 이 구조를 구축할 수 있습니다.

1. 항목 파일 하나를 작성하여 변환기가 대상으로 하는 4,000 토큰 근처에 둡니다. 명명된 개념을 정확한 공식과 함께 파일에 넣고, 모든 세부 파일과 해당 파일이 담고 있는 주제를 나열하는 색인을 추가합니다.
2. 자료를 약 1,000 토큰 단위의 파일로 분할합니다. 각 파일은 하나의 주제를 다루며, 파일 이름만 보고도 내용을 알 수 있도록 이름을 지정합니다.
3. 항목 파일에서 각 파일을 언제 읽어야 하는지 설명하는 문장을 작성합니다.

3단계는 사람들이 가장 많이 건너뛰는 부분이지만, 이 패턴이 작동하게 만드는 핵심입니다. 에이전트는 색인을 읽고 무엇을 열지 선택하므로, 색인에 설명되지 않은 파일은 에이전트가 절대 열지 않습니다. 색인이 곧 결과물이며, 챕터 파일은 저장소 역할을 합니다.

항목 파일을 압축 예산 내에 유지하면 긴 세션 동안 전체 구조가 유지됩니다. 이 규칙은 변환기가 파일을 작성했든 사용자가 직접 작성했든 동일하게 적용됩니다.

FAQ

구매한 도서로 빌드한 스킬을 배포할 수 있습니까?

아니요, 해당 도서의 라이선스가 재배포를 허용하지 않는 한 불가능합니다. 변환기에 적용된 MIT 라이선스는 변환기 코드에만 적용되며, 입력한 자료에는 적용되지 않습니다. 생성된 스킬은 해당 도서의 2차 저작물입니다. 본인의 컴퓨터에 있는 ~/.claude/skills/에 보관하십시오. 직접 작성한 문서나 오픈 라이선스가 적용된 소스는 배포해도 괜찮습니다. 이 도구는 저장소 공개 여부를 별도로 질문하며, 오직 public 또는 private만 허용하므로 사용자가 신중하게 결정해야 합니다.

docling이 필요한가요, 아니면 pdftotext만으로 충분한가요?

산문 위주의 문서라면 poppler-utils의 pdftotext만으로도 충분하며, 처리 속도도 즉각적입니다. 도서의 가치가 표나 코드 목록에 있다면 docling를 설치하십시오. 일반 텍스트 추출기는 이러한 요소를 누락하기 때문입니다. 대신 속도를 희생해야 합니다. 이 프로젝트는 docling의 처리 속도를 페이지당 약 1.5초로 측정하므로, 300페이지 분량의 매뉴얼은 VPS에서 수 분의 CPU 시간을 소모합니다.

VPS에서 pip가 externally-managed-environment 오류로 실패하는 이유는 무엇입니까?

Ubuntu 24.04 및 최신 Debian은 시스템 Python을 apt가 관리하는 것으로 간주합니다. 따라서 pip는 시스템 경로에 패키지 설치를 거부하고 error: externally-managed-environment 메시지를 출력합니다. python3 -m venv ~/.venvs/book-to-skill로 가상 환경을 생성하고 활성화한 뒤, 해당 환경에 추출기를 설치하고 동일한 셸에서 에이전트를 시작하십시오. 스킬은 python3를 호출하므로 PATH에 있는 인터프리터를 사용하게 되며, 이제 가상 환경의 인터프리터가 사용됩니다.

생성한 스킬이 슬래시 명령어로 나타나지 않는 이유는 무엇입니까?

두 가지 원인이 있습니다. 명령어 이름은 디렉터리 이름에서 가져오므로, 스킬은 ~/.claude/skills/<name>/SKILL.md 또는 .claude/skills/<name>/SKILL.md에 위치해야 하며 SKILL.md의 철자가 정확해야 합니다. 경로가 올바르다면 에이전트를 재시작하십시오. Claude Code는 이미 감시 중인 스킬 디렉터리 내부의 수정 사항은 반영하지만, 세션 시작 후에 생성된 스킬 디렉터리는 전혀 감시하지 않습니다.