문서를 스킬로 바꾸기

튜토리얼 · 6분 분량

에이전트에게 주고 싶은 지식은 대개 이미 어딘가에 적혀 있습니다. 온보딩 PDF, Word로 된 스타일 가이드, Markdown으로 쓴 런북처럼요. 부족한 것은 지식이 아닙니다. 문서는 처음부터 끝까지 읽는 사람을 위해 쓰이지만, 스킬은 작업 도중에 그것을 불러와 곧바로 행동해야 하는 에이전트를 위해 작동해야 한다는 점이 다릅니다.

Skilnu는 그 변환의 첫 번째 패스를 대신해 줍니다. 문서를 올리면 SKILL.md 초안이 돌아옵니다. 핵심 개념 틀, 주요 정의, 실행 가능한 지침이 지시문으로 재구성된 형태입니다. 아무것도 공개되지 않습니다. 읽고, 잘못된 부분을 고치고, 만족스러울 때 공개하세요. 다른 어떤 스킬과도 똑같습니다.

1. 문서 올리기

앱에서 + New skill을(를) 열고 「SKILL.md 업로드」 옆의 Draft from a document을(를) 누르세요. 파일을 고른 뒤 잠시 기다려 주세요. 문서 전체를 읽고 다시 써야 하므로 앱의 다른 작업보다 오래 걸립니다.

지원 형식: .pdf, .docx, .txt, .md, .markdown, .rst, .adoc.

그 밖의 형식은 업로드 전에 거부됩니다. 목록에 없는 형식이라면 먼저 PDF로 내보내세요. 그 경로는 충분히 잘 지원됩니다.

2. 서재가 아니라 한 절을 보내세요

추출된 텍스트에는 약 40,000자라는 길이 제한이 있으며, 대략 긴 장 하나에 해당합니다. 그보다 길면 조용히 잘리는 대신 업로드가 거부됩니다. 300쪽짜리 책의 앞 40,000자만으로 만든 스킬 초안을 그 책에서 만든 것처럼 건네받는 편이 오류보다 나쁘기 때문입니다.

들리는 것만큼 제약이 크지는 않습니다. 좋은 스킬을 만드는 조건과 이 제한에 들어맞는 조건이 같기 때문입니다 — 하나의 일관된 주제 말이죠. 「우리의 코드 리뷰 기준」은 스킬이지만, 「엔지니어링 핸드북 전체」는 스킬이 담긴 폴더입니다. 문서가 크다면 장별로 나누어 각각 초안을 만드세요. 어차피 전체를 한 번에 훑는 것보다 더 나은 스킬이 나옵니다.

3. 스캔한 PDF는 먼저 OCR이 필요합니다

실제로는 페이지를 찍은 사진인 PDF에는 추출할 텍스트가 없으므로, 빈 스킬 대신 그 사실을 알리는 메시지가 돌아옵니다. 먼저 아무 OCR 도구로 처리한 뒤 — 대부분의 PDF 앱에 「텍스트 인식」이 들어 있습니다 — 검색 가능한 버전을 올리세요.

빠르게 확인하는 법: PDF를 열고 문장 하나를 선택해 보세요. 선택되지 않으면 이미지입니다.

4. 초안을 제대로 읽기

초안은 작성 양식에 나타나며, 이름과 설명은 자체 frontmatter에서 채워집니다. 당신의 문서를 한 번 읽은 모델이 만든 첫 번째 패스이므로, 완성된 결과물이 아니라 유능한 동료의 첫 시도를 읽듯 읽어 주세요.

매번 확인할 가치가 있는 세 가지:

구체적인 내용을 지켰는가? Commands, thresholds, names of internal tools, the actual numbers. These are the most useful part of a skill and the easiest thing to lose when prose gets condensed.

없는 이야기를 지어내지 않았는가? The draft is told to stay inside what the document supports, but if your document was vague somewhere, check that the draft was vague in the same place rather than confidently filling the gap.

지시문인가, 요약인가? The failure mode to watch for is a draft that describes what the document says instead of telling the agent what to do. If a section reads like a book report, rewrite it as a rule.

5. 공개하기

만족스러울 때까지 양식에서 다듬은 뒤 평소처럼 공개하세요. 그때부터는 평범한 스킬입니다. 버전을 매기고, 다른 스킬이 의존하게 하고, 팀과 공유하고, MCP 라이브러리에 추가할 수 있습니다.

에이전트에서 실행하기

같은 흐름을 MCP에서도 두 개의 도구로 쓸 수 있습니다. 그 사이에 파일이 저장소에 도달해야 하기 때문입니다. 업로드 URL을 요청하고, 바이트를 보낸 뒤, 초안을 요청하세요.

get_document_upload_url(filename="handbook.pdf")
  -> { upload_url, document_key }

PUT the file's bytes to upload_url
  (no auth header -- the URL is already signed)

draft_skill_from_document(document_key=...)
  -> { name, description, skill_md }

에이전트 버전에는 웹 양식에 없는 instructions 인자가 하나 더 있고, 여기서는 정말 유용합니다 — 「3장에 집중해 줘」, 「이 주제를 처음 접하는 사람을 위해 써 줘」, 「모든 코드 예시를 남겨 줘」처럼요. 상시 컴파일 지침을 대체하는 것이 아니라 그 위에 더해집니다.

다른 곳과 마찬가지로 draft_skill_from_document은(는) 초안만 만듭니다. 내보내는 것은 별도의 publish_skill 호출이므로, 당신이 초안을 먼저 보지 않은 채 에이전트가 문서를 공개된 스킬로 바꿀 수는 없습니다.

비용

초안 하나당 일일 컴파일 할당량을 한 단위 사용하며, 모델은 설정에서 고른 것을 씁니다 — 컴파일과 함께 공개할 때와 같은 예산입니다. 지원하지 않는 파일이나 길이 제한을 넘은 파일처럼 모델까지 가지 못한 채 실패한 초안은 아무것도 쓰지 않습니다.

올린 문서는 임시 공간입니다. 성공하든 실패하든 초안이 생성되는 즉시 삭제되며, 그래도 남는 것이 있다면 24시간 안에 사라집니다. 공개된 스킬의 일부가 되는 일은 결코 없습니다 — 당신이 검토한 초안만이 포함됩니다.

어떤 경우에 좋은가

가장 잘 맞는 것은 이미 일하는 방식이 담긴 문서입니다. 스타일 가이드, 리뷰 체크리스트, 장애 런북, 또는 에이전트가 인용이 아니라 적용하기를 바라는 기술서적의 한 장 같은 것들이죠. 절차가 들어 있지 않은 참고 자료 — API 덤프, 용어집, PDF로 내보낸 스프레드시트 — 는 원본에서 끌어낼 지침이 없기 때문에 빈약한 스킬이 됩니다.

올리기 전에 해볼 만한 좋은 검사: 누군가 이 문서를 읽고 나서 무언가를 다르게 하게 될까요? 그렇다면 스킬이 됩니다. 찾아보기만 하는 자료라면 아마 아닐 것입니다.