• description을 Pushy 3단계 공식(동식 나열, 트리거 상황, 경계 조건)으로 작성하는 방법을 익히고, 컨텍스트를 아끼면서도 정보를 충분히 담는 Progressive Disclosure 구조를 이해한다.
  • 규칙이 아닌 이유를 본문에 담는 Why-First 원칙을 실제 예시로 확인한다.

스킬을 썼는데 왜 호출이 안 될까

  • 클로드는 스킬을 호출 할 지 결정할 때 본문을 읽지 않고, name과 description 만 보고 판단한다.
  • 클로드 코드는 세션이 열릴 때 전체 컨텍스트 윈도의 약 1%만 스킬 목록에 쓴다.
    • 1% 예산은 SLASH_COMMAND_TOOL_CHAR_BUDGET 환경 변수로 조정할 수 있으며, 기본 대체 한도는 약 8,000자이다.
  • 이 장에서 다루는 세 가지 원리
    1. Pushy 3단계 공식: “왜 호출되어야 하는가"가 드러나도록 descriptoin을 쓰는 방법
    2. Progressive Disclosure(단계적 정보 공개): 전체 스킬을 세 층으로 나눠, 꼭 필요한 것만 먼저 보여 주고 나머지는 필요할 때만 불러오는 방식
    3. Why-First 원칙: 본문에 규칙 대신 이유를 싣는 방법

원리 1 - Description이 호출을 결정한다

  • 클로드는 스킬을 보수적으로 호출한다.
  • 효과적인 description을 작성하는 공식
    • 동사를 나열한다
      • 스킬이 실제로 수행하는 동작을 동사로 적는다.
      • 예시: “읽기, 추출, 병합, 분할, 회전, 워터마크 삽입, 암호화, 복호화, OCR 처리”
    • 트리거 상황을 명시한다
      • “사용자가 ~을 언급하면 이 스킬을 사용할 것"처럼 직접적인 조건문을 넣는다.
      • 예시: 배포 스킬이라면 deploy, 배포, 릴리스, release처럼 한국어와 영어 표현을 함께 넣는 편이 좋다.
    • 경계 조건을 긋는다.
      • 이 스킬이 적합한 경우뿐 아니라 적합하지 않읂 경우도 함께 적는다.
      • 예시: PDF 내용을 분석하거나 요약하는 것이 주목적이면 document-analysis 스킬을 사용하고, 병합, 분할, 회전처럼 구조를 편집하는 작업이면 이 스킬을 사용한다.
  • 클로드 코드 공식 문서 기준으로 description 과 when_to_use를 합친 텍스트가 스킬 목록에서 1536자 지점에서 잘린다.

원리 2 - Progressive Disclosure 3단계

  • 컨텍스트는 내 것이 아니라 공공재이다.
    • Progressive Disclosure로 lazy loading으로 스킬을 로드하도록 한다.
  • 3단계 구조
    • Layer 1: “이 스킬을 호출할 것인가.” 클로드가 본문을 읽기 전에 판단하는 데 필요한 최소 정보만 담는다.
    • Layer 2: “호출했다면 어떻게 수행하는가.” 모든 호출에 공통으로 적용되는 절차와 원칙을 담는다.
    • Layer 3: “특정 조건에서 무엇을 추가로 참고하는가.” 조건부 상세, 도메인별 분기, 대형 템플릿을 남는다.
  • 본문 분리 신호 세 가지
    • 신호: 크기 신호
      • 판단 기준: SKILL.md가 500줄에 근접
      • 대응: 가장 큰 섹션을 references로 이동
    • 신호: 도메인 분기 신호
      • 판단 기준: “매출이면 A, 재고면 B” 같은 도멩니 분기가 본문에 등장
      • 대응: 도메인별로 references 파일 분리
    • 신호: 조건부 상세 신호
      • 판단 기준: “추적 변경이 필요하면 REDLINING.md 참조” 같은 조건부 링크를 쓰고 싶을 때
      • 대응: 해당 상세를 references로 분리하고 본문에는 조건부 참조만 남김

원리 3 - Why-First 원칙

  • 규칙만 쓰지말고 이유도 쓰는게 좋다.
  • 규칙만 쓰면 규칙이 과도하게 작동해 불필요하게 우회하는 결과를 낳는다.
  • 반면 이유를 알면 클로드는 새로운 상황에서도 스스로 판단할 수 있다.
  • 본문을 작성할 때 오버피팅되지 않고 일반화해서 작성하도록 해야된다.
  • 컨텍스트 절약 3원칙
    • 클로드가 이미 아는 내용은 작성 금지
    • 이 설명이 없으면 클로드가 실수하는 것만 작성
    • 구체적 예시 하나가 긴 설명보다 효과적

안티패턴

  • 안티패턴1: SKILL.md의 내용이 너무 길다
    • 내용: 하나의 SKILL.md에 모든 절차, 도메인별 템플릿, 예시. 체크리스트가 전부 들어 있다. 본문이 500줄을 한참 넘는다.
    • 문제점: 스킬이 호출될 때마다 전체 내용이 컨텍스트에 올라간다. ‘컨텍스트는 공공재’라는 원칙 위반이다.
    • 해결 방법: 분리 신호 세 가지(크기, 도메인 분기, 조건부 상세) 중 하나라도 해당하면 references로 쪼갠다. 본문은 라우터로 줄이고, 상세 내용은 조건부 링크로 연결한다.
  • 안티패턴2: references 없이 본문만 있다.
    • 내용: SKILL.md는 짧고 깔끔한데 디렉터리에 references/가 아예 없다. 모든 도메인과 모든 조건을 본문이 직접다룬다.
    • 문제점: 당장은 괜찮아 보이지만 문제는 스킬이 커질 때 드런난다. 새 도메인이나 조건이 추가될 때마다 본문에 분기문이 늘어나고, 반년 뒤에는 안티패턴 1로 이어진다. 또한 특수 케이스에만 필요한 내용까지 항상 컨텍스트에 올라온다.
    • 해결 방법: 본문을 쓸 때부터 “이 섹션이 커지면 references로 뺼 수 있는가"를 습관적으로 물어본다. 처음부터 조건부 참조 문장을 한두개 심어두고, 실제로 내용이 쌓이면 그때 채워 넣는다.
  • 안티패턴3: 이유 없는 규칙만 나열한다
    • 내용: 본문이 “반드시 X”, “절대 Y 금지” 같은 명령만 줄줄이 나열한다. 왜 그래야 하는지 이유가 없다.
    • 문제점: Why-First 원칙 위반이다. 규칙만 있으면 클로드는 그 규칙이 정확히 맞는 상황에서만 적용하고, 엣지 케이스에서는 어떻게 판단해야 할지 근거가 없어 오작동한다.
    • 해결 방법: 모든 규칙에 “왜냐하면"을 붙인다. 붙일 이유가 떠오르지 않으면 그 규칙 자체를 의심한다. 이유가 있더라도 지나치게 특정 예시에 오버피팅한 규칙이라면 패턴 차원으로 일반화한다.