앞 편 Skills가 해결하는 과제에서 "무엇을 Skill로 만들지"를 정했다면, 이 편은 "그 안에 어떻게 담을지"입니다. 정책자금 컨설팅, 이커머스 도소매, CRM 운영처럼 각자의 전문 분야 지식을 Claude가 쓸 수 있는 형태로 옮기는 기준을 다룹니다. 다음 편 SKILL.md 작성법에서 실제 파일을 만듭니다.
핵심 요약
- 담는 형태는 셋입니다. 참고 지식은 문서로, 절차는 번호 목록으로, 기계적 검사는 스크립트로.
- 본문에는 "무엇을 할지"만 적고, 예외와 금지를 명시합니다.
- 자동 호출 여부는
description한 줄이 결정합니다. SKILL.md는 500줄 이하로 유지하고 긴 자료는 지원 파일로 뺍니다.
세 가지 담는 형태
공식 문서는 Skill 내용을 "참조 콘텐츠"와 "작업 콘텐츠"로 나눕니다. 우리는 여기에 스크립트를 더해 셋으로 봅니다.
- 참조 지식: 용어, 기준표, 양식. 원구연 과정 4주차의 "고객 DB 표준 10항목"이 여기 해당합니다. 문서로 적습니다.
- 절차: 순서가 있는 작업. "전사본 받기, 안건 추출, 결정 사항 정리, 실명 가리기". 번호 목록으로 적습니다.
- 스크립트: 사람이 눈으로 판단하면 틀리는 일. 파일 개수 세기, 응답 코드 확인, 화면 캡처.
scripts/폴더에 두고 본문에서${CLAUDE_SKILL_DIR}/scripts/check.sh처럼 경로를 지정해 실행시킵니다. 스크립트는 실행되지, 컨텍스트에 로드되지 않습니다.
문서로 담을 때: 절차로 쓰기
"고객 응대는 친절하게"는 지식이 아닙니다. Claude가 무엇을 해야 할지 알 수 없습니다. "문의가 오면 ① 상품명과 주문번호를 확인하고 ② 재고 표를 조회한 뒤 ③ 답변 초안을 존댓말로 쓴다"는 절차입니다. 가장 흔한 실패가 설명문을 쓰는 것입니다. 신입에게 첫날 알려 주는 순서 그대로 번호를 붙이세요.
예외 처리를 명시하기
실무 지식의 절반은 예외에 있습니다. "주문번호가 없으면 이름과 전화번호 뒷자리로 조회한다", "재고가 0이면 입고 예정일을 답한다"처럼 "~이면 ~한다" 문장을 절차 뒤에 붙입니다. 우리 배포 Skill에는 "재시작이 실패하면 3초 기다렸다가 한 번 더 시도한다"는 예외가 있습니다. 이 한 줄이 없으면 Claude는 첫 실패에서 멈추거나 엉뚱한 원인을 찾습니다.
하지 말 것을 적기
금지 규칙은 절차보다 짧고 효과가 큽니다. 7주차 교재의 "운영 DB는 성역"이 그 예입니다. 본문에 "운영 DB에 직접 쓰기 금지, 로컬 복사본에서만 실험" 한 줄을 두면 어느 단계에서도 그 선을 넘지 않습니다. 금지 목록은 본문 맨 위나 맨 아래에 따로 모읍니다.
description이 전부다
Claude는 description만 보고 이 Skill을 펼칠지 결정합니다. 본문이 좋아도 설명이 나쁘면 호출되지 않습니다. 좋은 설명은 무엇을 하는지, 사용자가 어떤 말을 할 때 쓰는지 두 부분입니다. 우리 채점 루프 Skill의 설명은 "생성물을 레퍼런스와 맞대고 목표 점수까지 채점·수정 루프를 돌리는 검증 워크플로우. '채점 루프', '95%까지', '디자인 벤치마크' 요청 시 사용" 형태입니다. 사용자가 실제로 입에 올릴 단어를 넣는 것이 핵심입니다. 설명은 when_to_use와 합쳐 1,536자에서 잘리므로 주요 용도를 앞에 둡니다.
크기 관리
공식 문서는 SKILL.md를 500줄 이하로 권합니다. 호출된 본문은 세션 내내 컨텍스트에 남으므로 모든 줄이 반복 비용입니다. 긴 기준표, 예시 모음은 reference.md, examples.md 같은 지원 파일로 빼고 본문에서 링크합니다. 본문에는 "어떻게·왜"를 빼고 "무엇을"만 남깁니다.
검증하기
호출되는 것과 의도대로 작동하는 것은 다릅니다. 새 세션에서 현실적인 요청 세 개를 Skill 있음·없음으로 실행해 비교합니다. 새 세션이어야 작성 중 대화의 잔여 컨텍스트가 본문의 빈틈을 가리지 않습니다. 공식 skill-creator 플러그인은 이 비교를 자동화해 통과율·토큰·시간을 benchmark.json에 집계합니다. 사용법은 다음 편에서 다룹니다.
다음 레슨
SKILL.md 작성법에서 배치 장소, 필드 규칙, allowed-tools, 그리고 skill-creator로 디자인 Skill을 만드는 실습을 진행합니다.
정리
- 담는 형태는 셋입니다. 참고 지식은 문서로, 절차는 번호 목록으로, 기계적 검사는 스크립트로.
- 본문에는 "무엇을 할지"만 적고, 예외와 금지를 명시합니다.
- 자동 호출 여부는
description한 줄이 결정합니다. SKILL.md는 500줄 이하로 유지하고 긴 자료는 지원 파일로 뺍니다.
자주 묻는 질문
도메인 지식이 수십 쪽인데 다 넣어야 하나요?
넣지 않습니다. 본문에는 절차와 금지만 두고, 긴 자료는 지원 파일로 나눠 링크합니다. Claude가 "이 파일은 언제 열어야 하는지"를 알 수 있도록 링크 옆에 용도를 한 줄 적습니다.
스크립트와 문서 중 어느 쪽이 먼저인가요?
사람 눈으로 판단하면 틀리는 것은 스크립트, 판단이 필요한 것은 문서입니다. 응답 코드가 200인지는 스크립트, 답변 초안이 고객에게 적절한지는 문서 기준으로 Claude가 판단합니다.
description을 길게 쓰면 더 잘 호출되나요?
길이보다 단어 선택입니다. 사용자가 실제로 쓰는 표현 서너 개를 넣는 편이 문장을 늘리는 것보다 효과적입니다. 너무 자주 호출되면 설명을 더 구체적으로 좁힙니다.