SKILL.md 작성 방법 — Progressive Disclosure를 이용해 방대한 업무 지식을 압축하는 법 [실제 운영 13개 스킬 설계]

당사(Join Class LLC)는 도서 출판, 기사 집필, Kindle 등록 준비 등의 업무를 Claude Code의 Skills로 처리하고 있습니다. 현재 .claude/skills/

하위 폴더에는 13개의 스킬이 있으며, /publish-kindle나 /write-qiita와 같이 호출하여 사용하고 있습니다.

처음에 실패했던 방법은 '모든 업무 지식을 CLAUDE.md에 적는' 방식이었습니다. Kindle의 규약, EPUB의 조판 규칙, 기사의 스코어링 기준 등 계속해서 내용을 추가하다 보니, 어떤 대화에서도 관련 없는 지식이 컨텍스트를 압박하여 정작 중요한 지시 사항이 묻히기 일쑤였습니다.

본 글에서는 이러한 반성을 통해 도달한 **progressive disclosure(단계적 개시)**를 이용한 SKILL.md 설계 방식을 실제로 작동하는 파일과 스크립트를 기반으로 설명합니다.

Skills는 내용을 3단계로 나누어 로드합니다.

핵심은 계층 1은 모든 스킬에 대해 항상 로드된다는 점입니다. 이곳이 길면 13개 스킬 × description 분량의 토큰을 매번 지불해야 합니다. 반대로 계층 3은 실행될 때까지 단 하나의 토큰도 소비하지 않습니다. 즉, 설계 원칙은 하나입니다.

무거운 지식일수록 낮은 계층으로 밀어내기.

실제 /write-qiita의 프론트매터는 다음과 같습니다.

---
name: write-qiita
description: Qiita 기사를 작성합니다. LGTM 최대화 스코어링 기준(100점 만점)에 기반하여 80점 이상의 기사만 출력합니다. 사용법 /write-qiita "테마"
...

description에는 다음 세 가지 정보만을 넣었습니다.

무엇을 하는지 (Qiita 기사를 작성한다)
판단 기준 요약 (80점 이상만 출력한다)
호출 방법 (/write-qiita "테마")

스코어링 기준의 상세 내용(100점 만점 내역)은 적지 않았습니다. 그것은 계층 2 본문의 역할입니다.

당사에서는 write-zenn / write-qiita / write-note와 같이 유사한 스킬들이 나란히 있습니다. 초기에는 description이 '기술 기사를 작성한다' 정도였기 때문에, 의도와 다른 스킬이 작동하는 경우가 있었습니다. 플랫폼 이름과 고유의 판단 기준을 description에 반드시 포함함으로써 이 문제를 해결했습니다.

/publish-kindle의 SKILL.md는 214줄에 달합니다. 그럼에도 불구하고 비대해지지 않는 이유는, 기계적으로 판별 가능한 모든 지식을 스크립트로 빼냈기 때문입니다. 본문의 해당 단계는 이 정도입니다.

### Step 2: EPUB 품질 검사 (기계 검사가 우선)
python3 ~/workspace/one-ceo/.company/scripts/check-kindle-epub.py <EPUB 경로>
python3 ~/workspace/one-ceo/.company/scripts/check-kindle-epub.py --all
...

SKILL.md에는 '어떤 스크립트를, 어떤 순서로, 무엇을 합격 조건으로 실행할지'만 작성합니다. 금지 도메인 목록이나 표지 비율 같은 지식 자체는 본문에 쓰지 않습니다.

호출되는 쪽의 check-kindle-epub.py 파일 상단입니다(실제 파일에서 발췌).

#!/usr/bin/env python3
"""Kindle 등록 전 EPUB 검사 — KDP 규약 위반과 조판 깨짐을 등록 전에 제거합니다.
2026-09-25, AI-DLC의 교재를 KDP에 등록하기 직전에 외부 링크 13개가 발견되었습니다.
...
"""

이 파일은 Claude가 실행만 하면 되고, 내부 내용을 읽을 필요가 없습니다. 금지 도메인이 10개로 늘어나도 SKILL.md의 토큰 수는 단 하나도 증가하지 않습니다. 이것이 progressive disclosure가 가장 효과적으로 사용되는 방식입니다.

설계상의 요령은 두 가지가 있습니다.

• 종료 코드로 합격/불합격을 반환합니다 (0=합격 / 1=위반). Claude는 출력을 전부 읽지 않고도 분기할 수 있습니다.
• docstring에 "왜 이 검사가 존재하는지"를 작성합니다. 나중에 Claude가 스크립트를 수정할 때만 읽히는, 일종의 '레이어 4' 지식입니다.

이전에는 SKILL.md에 "외부 링크가 없는지 확인하는 것"이라고 문장으로 작성했습니다. 그 결과, 6권 중 1권에서 위반 사항을 놓쳤고, 등록 직전에 Amazon 제휴 링크를 포함한 외부 링크 13건이 발견되었습니다. 자연어의 "확인하는 것"은 LLM에게도 사람에게도 누락될 수 있습니다. 판별 가능한 것은 코드로 구현하기로 결정한 것이 이때입니다.

기존의 길었던 CLAUDE.md나 SKILL.md를 분할하는 절차입니다.

• SKILL.md의 각 단락을 "절차", "판단 기준", "사실 데이터(리스트/임계값)"로 색상 구분합니다.
• "사실 데이터"를 스크립트의 상수(예: BANNED_DOMAINS)로 이동시키고, "판단 기준" 중 기계 판별이 가능한 것을 스크립트의 검사 로직으로 만들고 종료 코드로 반환합니다.
• SKILL.md에는 "스크립트명, 실행 순서, 합격 조건"만 남깁니다.
• description을 "무엇을/기준 요약/호출 방법"의 1~2문장으로 줄입니다.

분할 후에는 다음 명령어로 레이어별 크기를 확인합니다.

cd ~/workspace/one-ceo
# 레이어 2: 본문의 행 수 (당사의 기준은 300행 이내)
wc -l .claude/skills/*/SKILL.md
...

당사의 실측 결과, write-qiita는 98행, publish-kindle는 214행입니다. 300행을 초과하면 "스크립트로 옮길 수 있는 지식이 남아있지 않은가"를 재검토하는 신호로 삼고 있습니다.

마지막으로, 실제로 슬래시 커맨드로 스킬을 호출하여 의도한 스킬이 선택되는지, 스크립트가 실행된 후에 판단하는지를 트랜스크립트로 확인합니다. 스크립트를 호출하지 않고 "확인했습니다"라고 말하는 경우에는, SKILL.md의 해당 단계에 "필수", "합격 조건"을 명기하면 개선되었습니다.

• 레이어 1(description)은 상시 로드됩니다. 짧지만, 다른 스킬과 구별할 수 있는 고유어를 포함합니다.
• 레이어 2(본문)는 절차와 합격 조건만 기재합니다. 지식 자체는 적지 않습니다.
• 레이어 3(스크립트)에 업무 지식을 코드로 봉인하고, 종료 코드로 합격/불합격을 반환합니다.
• "확인하는 것"이라는 자연어는 누락될 수 있습니다. 판별 가능한 것은 코드로 만듭니다.

업무 지식이 늘어날수록, AI에게 "모두 읽게 하는" 것이 아니라 "필요할 때만 읽게 하는" 설계가 효과적입니다. 13개의 스킬을 운영해 온 당사의 결론은, SKILL.md는 지식의 저장소가 아니라, 지식으로 가는 색인(Index)이라는 것입니다.

Skills의 설계 패턴, 부속 리소스 구성, 플러그인으로서의 배포 방법까지 체계적으로 정리한 것이 『Claude Skills 완전 가이드』입니다. 본 기사의 3층 설계를 더욱 깊이 다루고 있습니다.

도서 목록은 여기에서 확인하세요: https://zenn.dev/joinclass?tab=books