증상: 기술서를 통째로 요약했지만 에이전트가 조건과 예외를 놓치고, 답변의 근거 위치도 찾지 못합니다.
가장 빠른 해결법: 권한과 목표 작업을 먼저 확정한 뒤 장별 추출, 지식 분류, 단계형 스킬 생성, 실제 작업 검증 순서로 진행해야 합니다.
이 글을 읽어야 하는 사람
개인 기술서를 업무 보조 스킬로 정리하려는 개발자에게 적합합니다.
내부 교육 자료를 팀 작업 절차로 바꾸려는 지식 엔지니어와, 긴 책을 압축하면서 조건과 예외가 사라질까 걱정하는 스킬 작성자도 바로 적용할 수 있습니다.
기술서를 인공지능 스킬로 바꾸는 작업은 단순한 요약이 아닙니다. 책을 에이전트가 특정 업무에서 재사용할 수 있는 지식 제품으로 다시 설계하는 과정입니다.
시작 전에 권한과 목표 작업을 고정합니다
먼저 파일을 처리할 권한을 확인해야 합니다. 직접 구매했거나 조직이 사용 권한을 보유한 자료라도, 원문을 팀 외부에 배포하거나 서비스에 공개할 권한까지 자동으로 생기는 것은 아닙니다. 저작권 예외는 사용 목적과 방식 등 여러 조건을 함께 판단하며, 정해진 분량까지 자유롭게 복제할 수 있다는 단순한 규칙도 없습니다. 자세한 기준은 미국 저작권청의 공정 이용 안내와 저작권 자주 묻는 질문에서 확인해야 합니다.
권한 확인 뒤에는 “이 책을 읽은 에이전트”가 아니라 “어떤 작업을 수행하는 에이전트”인지 정의합니다.
- 특정 장의 개념을 바탕으로 설계안을 검토하는가
- 코드 예제를 참고해 구현 순서를 제안하는가
- 오류 원인을 조건별로 분류하는가
- 교육용 질문을 만들고 답안을 채점하는가
목표가 넓을수록 불필요한 지식이 늘고, 스킬이 작동해야 하는 조건도 모호해집니다. 처음에는 한 가지 작업군만 정하고, 나중에 별도 참고 자료를 추가하는 편이 운영하기 쉽습니다.
주의: 책의 원문을 그대로 넣은 파일을 팀 저장소나 외부 서비스에 배포하지 마십시오. 스킬에는 작업에 필요한 규칙과 요약을 넣고, 원문은 권한이 확인된 제한된 저장 위치에 별도로 보관해야 합니다. 관련 기준은 Macstripe 문서 처리 안내에서도 확인할 수 있습니다.
원문을 장과 위치 단위로 추출합니다
두 번째 단계의 목표는 “읽을 수 있는 텍스트”가 아니라 “다시 확인할 수 있는 텍스트”입니다. 다음 정보를 함께 저장합니다.
- 책의 파일 식별자와 판본 정보
- 장, 절, 소제목
- 쪽 번호 또는 파일 위치
- 코드 블록과 표의 시작·끝 위치
- 그림이나 스캔 이미지에서 추출한 문장 표시
- 추출 실패나 불확실한 부분
문자 레이어가 있는 문서는 pdftotext 같은 도구로 먼저 추출할 수 있습니다. 이 도구는 쪽 범위, 문자 인코딩, 배치 보존, 단어 위치 정보 같은 옵션을 제공하지만, 글꼴 인코딩이 깨졌거나 이미지로만 구성된 문서는 별도 인식 과정이 필요합니다. pdftotext 명령어 문서를 기준으로 추출 옵션을 확인하십시오.
추출 결과는 다음처럼 분리하는 것이 좋습니다.
source/
book.pdf
chapter-index.yaml
pages/
001-introduction.txt
002-memory-model.txt
figures/
extraction-issues.md
코드와 표는 일반 문장처럼 합치지 마십시오. 열 순서가 바뀐 표, 줄바꿈이 사라진 코드, 쪽 번호가 빠진 문장은 이후 요약 단계에서 잘못된 규칙으로 변하기 쉽습니다. 스캔 자료라면 인식된 문장마다 “원문 확인 필요” 표시를 남기고, 핵심 규칙은 사람이 직접 대조해야 합니다.
개념과 절차를 서로 다른 지식으로 분류합니다
지식 추출 단계에서 모든 문장을 같은 종류로 저장하면 스킬이 과도하게 단정적인 답을 냅니다. 최소한 다음 범주를 분리하십시오.
- 정의: 용어가 무엇을 뜻하는지
- 원칙: 여러 상황에 적용되는 일반 기준
- 조건: 특정 버전, 환경, 입력을 전제로 하는 내용
- 절차: 순서대로 수행해야 하는 작업
- 예외: 일반 규칙이 적용되지 않는 상황
- 예시: 개념을 설명하기 위한 사례
- 반례: 규칙을 잘못 적용했을 때 생기는 결과
특히 “일반적으로”, “이 경우에는”, “단, 특정 환경에서는” 같은 표현을 삭제하지 않아야 합니다. 장을 압축하면서 이런 조건어가 사라지면 저자의 제한적인 조언이 무조건적인 규칙으로 바뀝니다.
실무에서는 다음과 같은 지식 기록을 만들면 검수가 쉽습니다.
id: memory-rule-014
type: condition
statement: 특정 접근 패턴에서는 캐시 지역성이 성능에 영향을 줄 수 있음
preconditions:
- 접근 순서가 반복됨
exceptions:
- 데이터 크기가 캐시에 들어가지 않음
source:
chapter: 4
location: page-087
confidence: review-required
이 구조는 책을 그대로 복사하지 않으면서도, 어떤 문장이 어떤 판단에 사용되는지 추적하게 해줍니다. 장별 지식 목록을 만든 뒤 장문 지식 보관 환경 안내를 참고해 원문과 가공본의 접근 권한도 분리하십시오.
작업 범위에 따라 저장 위치를 결정합니다
기술서 내용을 어디에 넣을지는 파일 크기가 아니라 에이전트가 수행할 작업의 성격으로 정해야 합니다. 다음 결정 조건 목록을 먼저 적용하면 하나의 거대한 파일을 만드는 실수를 줄일 수 있습니다.
결정 조건 목록
- 만약 사용 시점과 핵심 절차만 필요하다면,
SKILL.md에 트리거 조건, 입력 전제, 실행 순서, 결과 형식을 넣습니다. 장문의 설명은 별도 참고 자료로 분리합니다. - 만약 여러 장의 개념과 예외를 요청에 따라 불러와야 한다면,
references에 장별 설명, 용어 색인, 반례, 출처 목록을 둡니다.SKILL.md에는 해당 자료를 불러오는 조건만 적습니다. - 만약 입력 형식과 검사 결과가 반복될 때마다 일정하다면, 출처 누락, 위치 연결 오류, 파일 형식 오류를 확인하는
scripts를 추가합니다. - 만약 책의 내용이 서로 다른 업무에 걸쳐 있다면, 하나의 스킬에 전부 넣지 말고 업무별 스킬로 나눕니다. 공통 개념만 별도 참고 자료로 관리합니다.
- 만약 원문 처리 권한이 불명확하거나 외부 공유가 필요하다면, 변환을 중단하고 권한을 다시 확인합니다. 권한이 확인되지 않은 자료를 요약해 배포해서는 안 됩니다.
- 만약 스킬이 설명과 판단만 제공하고 자동 실행은 하지 않는다면,
scripts를 억지로 만들지 않습니다. 판단 기준과 출처 추적 규칙을SKILL.md와references에 둡니다.
제작 전 선택 체크리스트
아래 항목을 실제 작업 문서에 복사해 사용하십시오.
- [ ] 처리할 자료를 합법적으로 보유했으며, 변환과 저장 범위를 확인했습니다.
- [ ] 에이전트가 수행할 대표 작업을 한 문장으로 정의했습니다.
- [ ] 핵심 절차와 실행 조건을
SKILL.md에 넣기로 결정했습니다. - [ ] 장별 개념, 예외, 반례, 출처 위치를
references로 분리했습니다. - [ ] 반복 검사가 일정한 경우에만
scripts를 추가하기로 했습니다. - [ ] 원문 위치를 다시 찾을 수 있도록 장과 쪽 또는 파일 위치를 기록했습니다.
- [ ] 여러 업무가 섞여 있다면 하나의 스킬로 합치지 않고 업무별로 나눴습니다.
- [ ] 권한이 불명확한 자료는 추출하거나 배포하지 않기로 했습니다.
체크하지 못한 항목이 있으면 다음 단계로 넘어가지 않는 편이 안전합니다. 특히 첫 번째와 마지막 항목을 확인하지 못한 상태에서 요약 파일을 팀에 공유하면, 나중에 스킬 품질이 아니라 자료 사용 권한 문제가 전체 작업을 중단시킬 수 있습니다.
실제 선택은 다음 순서로 진행합니다.
- 권한 조건을 충족하지 못하면 변환을 보류합니다.
- 작업 범위가 하나라면 핵심 절차를
SKILL.md에 둡니다. - 여러 장의 상세 지식이 필요하면
references로 나눕니다. - 동일한 검사를 반복한다면
scripts를 추가합니다. - 서로 다른 업무를 지원한다면 스킬을 업무별로 분할합니다.
반대로 SKILL.md에 장문의 배경 설명을 모두 넣는 방식은 피해야 합니다. 핵심 지침이 길어지면 실제 요청에 필요한 단계가 묻히고, 스킬이 언제 적용되어야 하는지도 불분명해집니다.
SKILL.md에는 실행 지침만 남깁니다
에이전트 스킬의 기본 구조는 스킬 폴더 안에 SKILL.md를 두는 방식입니다. 공식 저장소의 스킬 예제와 템플릿에는 이름과 설명을 담은 앞부분, 그리고 작업 지침을 담는 본문 구조가 제시되어 있습니다. 표준 문서에서도 SKILL.md를 최소 구성 요소로 정의합니다.
기술서 기반 스킬은 다음처럼 계층을 나누는 것이 좋습니다.
book-review-skill/
SKILL.md
references/
chapter-map.md
concepts.md
procedures.md
exceptions.md
source-index.md
scripts/
validate-source-links.py
SKILL.md에는 다음만 남깁니다.
- 어떤 요청에서 스킬을 사용할지
- 입력 자료의 범위와 권한 전제
- 작업을 수행하는 핵심 순서
- 판단이 필요한 조건
- 어느 참고 자료를 불러올지
- 답변에 근거 위치를 표시하는 방식
반면 장별 상세 설명, 긴 예시, 예외 목록, 용어 색인은 references로 옮깁니다. 공식 스킬 제작 안내도 트리거에 영향을 주는 사용 조건은 설명 영역에 명확히 쓰고, 긴 지침은 필요할 때 불러오는 구조를 권장합니다. 공식 스킬 제작 지침을 함께 확인하십시오.
반복 실행할 때 결과가 일정해야 하는 검사는 scripts로 분리할 수 있습니다. 예를 들어 모든 참고 자료 항목에 장과 위치가 있는지 검사하는 스크립트는 자동화 가치가 높습니다. 반대로 해석과 요약처럼 판단이 필요한 작업을 무리하게 코드로 고정하면 오류 원인을 찾기 어려워집니다.
압축한 지식을 장별로 다시 검증합니다
요약 결과를 만들었다면 원문과 대조하는 검수 단계를 둡니다. 이때 전체를 다시 읽기보다 오류가 발생하기 쉬운 항목을 먼저 표본 검사합니다.
- 숫자와 단위
- 버전이나 운영체제 전제
- “항상”, “대부분”, “예외적으로” 같은 조건어
- 코드의 입력과 출력
- 단계의 선후 관계
- 저자가 제시한 반례
- 서로 다른 장에서 다르게 정의된 용어
요약문에 원문에 없는 결론이 추가되지 않았는지도 확인해야 합니다. 에이전트가 더 친절한 답변을 만들도록 배경 지식을 보충하는 것은 가능하지만, 그것은 책에서 추출한 지식과 별도의 외부 지식으로 표시해야 합니다.
장별 검수 결과는 세 등급으로 나누십시오.
- 확인됨: 원문 위치와 내용이 일치함
- 부분 확인: 표현은 맞지만 조건이나 예외가 부족함
- 재검토 필요: 추출 오류, 번역 오류, 위치 불명확
실제 작업으로 스킬을 시험합니다
스킬 검증은 단순한 지식 퀴즈로 끝내면 안 됩니다. 다음 네 가지 유형을 섞어야 합니다.
- 책 안에 직접 답이 있는 질문
- 서로 다른 장의 내용을 연결해야 하는 작업
- 조건 하나가 빠진 경계 사례
- 해당 스킬을 사용하면 안 되는 질문
예를 들어 기술서가 시스템 설계를 다룬다면 용어를 설명하게 하는 데서 끝내지 말고, 특정 조건의 설계안을 검토하게 해야 합니다. 답변에는 결론뿐 아니라 사용한 기준과 원문 위치가 함께 표시되는지 확인합니다.
검증 기록에는 다음 항목을 남기십시오.
- 스킬을 켜기 전과 후의 답변 차이
- 핵심 조건 누락 여부
- 원문 위치를 다시 찾을 수 있는지
- 절차의 순서가 매번 유지되는지
- 적용하지 말아야 할 질문을 거절하는지
- 사람이 수정한 횟수와 수정 이유
공식 스킬 제작 지침은 실제 사용자와 가까운 테스트 입력을 만들고, 스킬이 없는 상태와 비교하는 평가 흐름을 설명합니다. 공식 평가 흐름을 참고하면 테스트가 지식 암기 시험으로 축소되는 것을 막을 수 있습니다.
현재 방식과 맥 환경을 비교해 선택합니다
현재 사용 중인 개인용 컴퓨터나 공유 서버에서 책 전체 추출과 반복 평가를 처리하면 저장 공간을 계속 확보해야 하고, 스캔 자료의 인식 작업과 여러 테스트 실행이 한 환경에 섞이며, 팀 자료와 임시 산출물의 권한을 분리하기도 어렵습니다. 반대로 Macstripe의 맥 환경을 임시로 사용하면 문서 처리와 스킬 평가를 분리된 작업 공간에서 진행하고, 필요한 기간에만 테스트 환경을 운영하는 선택지가 생깁니다.
장기간 같은 자료를 계속 처리하고 물리 장치나 특수 인터페이스가 필요하다면 직접 장비를 운영하는 편이 맞습니다. 그러나 합법적으로 보유한 기술서를 한 차례 변환하거나, 팀 배포 전에 여러 평가 입력을 반복 실행하는 목적이라면 한국용 맥 구성 주문 안내를 확인해 임시 환경부터 검토하는 편이 현실적입니다. 비용과 보관 정책, 자료 삭제 절차를 먼저 확인한 뒤 사용해야 합니다.
