[Agent Skills 완전정복 #5] 스킬이 '제 때' 불려오게 하는 법 — description 최적화

Agent Skills 시리즈 다섯 번째 편. 아무리 잘 만든 스킬도 호출되지 않으면 무용지물입니다.
호출 여부를 결정하는 단 하나의 필드 — description을 체계적으로 다듬는 법을 정리합니다.

---

🎯 호출(triggering)은 어떻게 일어나나

에이전트는 시작 시 모든 스킬의 name·description만 읽어둡니다. 사용자 작업이 어떤 description과 맞아떨어지면 그 스킬의 본문을 로드하죠. 즉 호출의 모든 책임은 description이 집니다.

한 가지 뉘앙스: 에이전트는 보통 스스로 처리하기 버거운 작업에만 스킬을 찾습니다. "이 PDF 읽어줘" 같은 단순 요청은 description이 딱 맞아도 스킬 없이 처리해버릴 수 있어요. 낯선 API·도메인 워크플로우·드문 형식처럼 전문성이 필요한 작업에서 좋은 description이 빛납니다.

---

✍️ 좋은 description의 원칙

• 명령형으로 — "이 스킬은 ~한다"가 아니라 "~할 때 이 스킬을 써라". 에이전트는 '행동 여부'를 결정 중이니 언제 행동할지 알려주세요.
• 구현이 아니라 사용자 의도에 집중 — 내부 동작이 아니라 사용자가 이루려는 것을 묘사. 매칭 대상은 "사용자가 요청한 것"입니다.
• 약간 들이대듯이(pushy) — 적용되는 맥락을 명시적으로 나열. 사용자가 도메인을 직접 안 말하는 경우까지: "CSV나 분석이라고 명시하지 않더라도..."
• 간결하게 — 몇 문장~짧은 단락. 하드 리밋은 1024자.

---

🧪 트리거 평가용 쿼리 설계

테스트하려면 "호출돼야 함/안 돼야 함"을 라벨링한 현실적인 사용자 프롬프트 세트가 필요합니다. 약 20개(트리거 8~10 / 비트리거 8~10)를 권장.

[
  { "query": "~/data/q4_results.xlsx 스프레드시트에 수익 C열, 비용 D열이 있는데
               이익률 컬럼 추가하고 10% 미만은 강조해줄래?", "should_trigger": true },
  { "query": "이 json 파일 yaml로 제일 빠르게 바꾸는 법?", "should_trigger": false }
]

• 트리거 쿼리는 표현·명시성·길이·복잡도를 다양하게. 특히 "스킬이 도움되지만 연결이 뻔하지 않은" 쿼리가 가장 유용합니다.
• 비트리거 쿼리는 아슬아슬한 near-miss가 핵심. "fibonacci 함수 짜줘"처럼 명백히 무관한 건 의미 없어요. CSV 스킬이라면 "엑셀 예산 수식 업데이트"(스프레드시트지만 편집 작업), "csv 읽어 postgres에 업로드"(CSV지만 ETL)처럼 키워드는 겹치되 작업이 다른 것을 넣으세요.
• 파일 경로·개인 맥락("팀장이 시켜서...")·구체적 디테일·오타까지 넣어 현실성을 높입니다.

---

📊 호출 여부 측정 — 트리거율

각 쿼리를 스킬 설치 상태로 돌려, 에이전트가 스킬을 로드했는지 관찰합니다. 모델은 비결정적이라 같은 쿼리도 매번 다를 수 있어요. 그래서 각 쿼리를 여러 번(3회 권장) 돌려 트리거율(호출된 비율)을 구합니다.

• 트리거돼야 할 쿼리 → 트리거율 0.5 초과면 통과
• 안 돼야 할 쿼리 → 트리거율 0.5 미만이면 통과

---

🔀 과적합 방지 — 학습/검증 분할

모든 쿼리에 맞춰 description을 깎으면 그 표현들에만 동작하는 과적합이 생깁니다. 쿼리를 나누세요.

• 학습셋(~60%) — 실패를 찾고 개선을 이끄는 데 사용
• 검증셋(~40%) — 개선이 일반화되는지 확인용으로만 따로 보관

양쪽에 트리거/비트리거를 비례 배분하고, 분할은 반복 내내 고정합니다.

---

🔄 최적화 루프

• ① 현재 description을 학습·검증셋 모두에서 평가
• ② 학습셋의 실패 분석 — 트리거 실패는 설명이 너무 좁음 → 범위·맥락 확장 / 오트리거는 너무 넓음 → "무엇을 하지 않는지"를 명시
• ③ description 수정. 단, 실패 쿼리의 특정 키워드를 그대로 넣지 말 것(과적합). 그 쿼리가 대표하는 일반 범주를 다루세요. 막히면 점진적 수정 대신 구조가 다른 새 문장으로 시도.
• ④ 학습셋이 다 통과하거나 개선이 멈출 때까지 반복 (보통 5회면 충분)
• ⑤ 검증셋 통과율로 최선 버전 선택 — 마지막 버전이 최선이 아닐 수 있음(후반이 과적합됐을 수도).

Anthropic의 skill-creator 스킬은 이 루프를 자동화합니다 — 평가셋 분할, 병렬 트리거율 측정, Claude로 설명 개선, 실시간 HTML 리포트 생성까지.

---

🔧 적용 — Before / After

# Before
description: Process CSV files.

# After
description: >
  Analyze CSV and tabular data files — compute summary statistics,
  add derived columns, generate charts, and clean messy data. Use this
  skill when the user has a CSV, TSV, or Excel file and wants to explore,
  transform, or visualize the data, even if they don't explicitly
  mention "CSV" or "analysis."

개선본은 무엇을 하는지 더 구체적(요약통계·파생컬럼·차트·정제)이고, 언제 적용되는지 더 넓게(CSV·TSV·Excel, 키워드 없이도) 만들었습니다. 적용 후엔 1024자 제한을 넘지 않는지, 처음 보는 새 쿼리로 일반화되는지 꼭 확인하세요.

---

✍️ 마무리

description은 "명령형 + 사용자 의도 + 약간 들이대듯 + 간결". 그리고 감이 아니라 트리거율 측정 → 학습/검증 분할 → 반복으로 다듬습니다.

👉 다음 편 → [#6] 스킬 품질 평가하기 (eval로 검증)

---

📎 출처: 이 글은 Agent Skills 공식 문서 — Optimizing skill descriptions (© Anthropic, CC BY 4.0)를 한국어로 번역·재구성한 것입니다.

---