Claude Code의 Skills는 실행되지 않을 때도 토큰을 소모합니다. 7시간 동안 5가지 Skills를 측정해 본 결과, 비용이 18%

저는 Skills가 커스텀 명령(custom commands)보다 무료로 업그레이드된 기능이라고 생각했습니다. 하지만 무료가 아닙니다. 그것은 임대료입니다.

이 문장이 이 기사의 전체 내용을 15단어로 요약한 것입니다. 나머지는 제가 영수증을 보여드리는 과정입니다.

저는 화요일에 7시간 동안 하나의 Claude Code 세션에 다섯 가지 Skills를 로드해 두었습니다: PR 리뷰어(PR reviewer), TypeScript 마이그레이션 도우미(TypeScript migration helper), 데이터베이스 마이그레이션 검증기(database migration validator), 로그 추적기(log tracer), 그리고 CSV 클리너(CSV cleaner)입니다. 그중 세 가지는 세션 내내 단 하나의 프롬프트와도 일치하지 않았습니다. 믿기지 않아서 호출 로그(invocation log)를 두 번이나 확인했습니다. 그것들은 조용하고 얌전하게 그 자리에 있었지만, 그럼에도 불구하고 그날 **전체 토큰의 약 18%**를 차지했습니다. 실행되지 않은 세 가지가 단독으로 **비용의 약 11%**를 차지했습니다.

저는 팀원들에게 Skills는 실행될 때만 토큰을 소모한다고 말해왔습니다. 저는 측정 가능한 방식으로 틀렸습니다.

Skills가 실제로 로드되는 방식 (제가 대충 훑어봤던 부분)

여기에 제가 읽었지만 내재화하지 못했던 사양(spec)이 있습니다.

세션이 시작되면 Claude Code는 범위(scope) 내의 모든 Skill을 읽습니다. 각 SKILL.md의 프론트매터(frontmatter)에 있는 name과 description이 시스템 컨텍스트(system context)에 들어갑니다. Skill의 본문(body)은 아직 로드되지 않습니다. 그 부분은 Claude가 설명(description)이 현재 프롬프트와 일치한다고 판단하거나, 사용자가 명시적으로 /skill-name을 입력할 때만 로드됩니다. 본문이 로드되면 세션이 종료되거나 압축(compaction)이 작동할 때까지 컨텍스트 윈도우(context window)에 남아있게 됩니다.

이것은 Anthropic이 의도적으로 Skills에 적용한 점진적 공개 (progressive disclosure) 디자인입니다. 시작 시 Claude는 YAML 프론트매터 (frontmatter)만 읽으며, Skill당 이름과 설명에 약 60개의 토큰을 사용하고, 전체 본문은 필요할 때만 로드됩니다. Anthropic의 자체 예시에 따르면: 8개의 Skill이 있는 프로젝트는 시작 시 약 500개의 토큰이 소모되지만, 모든 본문을 미리 로드하면 약 70,000개의 토큰이 소모됩니다. 그 140배의 격차가 바로 이 아키텍처의 핵심이며, 이는 진정으로 훌륭한 디자인입니다.

제가 놓친 함의는 그 격차의 반대편에 있습니다: 설명(description)이 매 턴(turn)마다 컨텍스트(context)에 포함된다는 점입니다. 세션 시작 시뿐만이 아닙니다. 당신이 보내는 모든 사용자 메시지, Claude가 생성하는 모든 응답에서 그 설명은 프롬프트(prompt)의 일부로 그 자리에 머물러 있습니다. 300토큰 길이의 설명이 있는 5개의 Skill은

저는 토큰 소모량을 세 가지 방식으로 합산했습니다: 전체(total), "Skills가 로드되지 않았을 때의 예상치" (설명만 있는 오버헤드와 실제로 실행된 두 개의 본문을 제외하여 추정), 그리고 그 차이(diff)입니다. 로그의 수치는 다음과 같습니다:

카테고리	토큰	비중
대화, CLAUDE.md, 코드 읽기	1,720K	82%
...

제 값을 다 한 두 개의 Skills는 7%의 비용을 발생시켰습니다. 이는 괜찮습니다. 워크플로 프롬프트(workflow prompts)를 다시 입력할 필요가 없었기에 아마 그 두 배 이상의 비용을 아꼈을 것입니다.

그 어떤 것과도 매칭되지 않은 세 개의 Skills는 11%의 비용을 발생시켰습니다. 이들은 단 1%의 비용도 회수하지 못했습니다. 프롬프트 캐싱 (prompt caching)을 사용하면 턴(turn)당 설명 비용이 부분적으로 흡수되지만, 오직 부분적으로만 그렇습니다. 프롬프트가 변경될 때마다 설명 주변의 캐시가 무효화(invalidate)되며, 입력 토큰(input-token) 항목에 대해 입력 토큰이 다시 토큰화되어 비용이 청구됩니다. 11%입니다.

감사 (The audit)

저는 다음 날 아침, 전날 실제로 실행되었던 두 개의 Skills만 사용하여 동일한 워크로드(workload)를 실행했습니다. 동일한 파일, 동일한 PR 세트, 동일한 종류의 프롬프트를 사용했습니다. 총 소모량은 1,872K 토큰이었습니다. 이는 전날 대비 11% 감소한 수치로, 작동하지 않은 설명들이 저에게 발생시켰던 비용과 거의 정확히 일치합니다. 다른 날의 오차 범위를 고려하더라도 일치하는 결과입니다.

본인의 설정에서 이를 빠르게 확인하고 싶다면, JSON 응답을 캡처하는 claude 래퍼(wrapper)를 실행해 보세요:

claude -p "$YOUR_PROMPT" --output-format json --verbose \
  | jq '{input: .usage.input_tokens, cached: .usage.cache_read_input_tokens, output: .usage.output_tokens}'

input_tokens 라인은 턴마다 추적해야 할 수치입니다. 만약 Skill을 추가한 후 이 수치가 기준선(baseline)에서 위쪽으로 표류(drift)한다면, 당신은 설명에 대한 임대료(description rent)를 지불하고 있는 것입니다.

이것이 왜 저를 놀라게 했는가

저는 Skills를 프로그래밍 언어의 import(임포트)와 같은 방식으로 생각해 왔습니다. 즉, 호출되기 전까지는 비용이 제로(zero cost)라고 말이죠. import는 컴파일러가 참조되지 않는 모든 것을 버릴 수 있기 때문에 비용이 들지 않습니다. 하지만 Claude Code는 그렇지 못합니다. 설명(description)은 Claude에게 언제 Skill을 호출해야 할지를 알려주는 요소이므로, 매 턴(turn)마다 프롬프트(prompt)에 포함되어야 합니다. 만약 이를 지연 로딩(lazy loading) 방식으로 불러온다면, 모델은 애초에 해당 Skill을 호출할지 여부를 결정할 수 없을 것입니다.

이것은 설계상의 트레이드오프(tradeoff)이며, 올바른 결정입니다. 하지만 이는 "Skill을 설치해 두었지만 전혀 사용하지 않는 경우"의 한계 비용(marginal cost)이 제로가 아님을 의미합니다. 이는 긴 세션 동안 누적되는 매 턴마다 발생하는 작은 세금과 같습니다.

이것은 Hooks(훅)와는 다릅니다. Hooks는 Claude Code가 특정 이벤트(pre-tool, post-tool, session-end)에 도달했을 때 실행됩니다. Hooks는 매칭을 위해 시스템 프롬프트(system prompt)에 기술되지 않으며, settings.json에 설정되어 하네스(harness)에 의해 트리거됩니다. 사용되지 않는 Hook의 비용은 진정으로 제로입니다. 반면 사용되지 않는 Skill의 비용은 매 턴 발생하는 설명(description) 비용입니다.

또한 사용하지 않는 MCP 서버와도 다릅니다. MCP 서버는 세션 시작 시 전체 도구(tool) 목록을 시스템 프롬프트에 추가하며, 이는 Skill 설명보다 훨씬 클 수 있습니다. 하지만 이는 서버당 한 번 발생하는 수치이며, 이미 일부 팀에서 측정한 바 있습니다(한 공개 감사 결과에 따르면 서버당 약 27,000 토큰). Skills는 MCP 서버보다 항목당 비용은 더 작지만, 더 많이 보유하는 경향이 있으며, 매 턴 발생하는 패턴이 이 비용을 배수로 늘립니다.

5단계 Skill 감사

저는 이제 이것을 매달 수행합니다. 10분 정도 걸립니다.

1. 범위 내의 모든 Skill을 나열합니다. ls ~/.claude/skills/와 프로젝트 레벨의 .claude/skills/, 그리고 플러그인에서 제공하는 모든 것을 확인하세요. 이를 기록해 둡니다.
2. 각 Skill에 대해 마지막으로 실행된 시점을 찾습니다. --output-format json 옵션으로 세션을 실행하고 로그로 파이프(pipe)를 연결했다면, 도구 사용(tool-use) 항목에서 Skill 이름을 grep으로 검색하세요. 구조화된 출력(structured output)을 로깅하지 않는다면 기억에 의존해 추측해야 하는데, 이는 대개 틀립니다.
3. 지난 30일 동안 호출(invocation)이 없는 항목을 후보로 표시합니다. 아직 삭제하는 것이 아닙니다. 플래그(flag)를 지정하는 것입니다.
4. 후보 항목들을 일주일 동안 범위 밖으로 이동시킵니다. 저는 말 그대로 디렉토리를 ~/.claude/skills-attic/로 mv 합니다. 일주일 동안 그 상태로 지내보세요. 만약 그 Skill이 생각나지 않는다면, 그것은 불필요한 비용(rent)이었습니다.
5. 입력 토큰(input token) 기준선(baseline)을 다시 측정합니다. 후보 항목들을 로드하지 않은 상태에서 동일한 종류의 작업 부하(workload)를 수행합니다. 만약 입력 토큰 라인이 유의미하게 작아졌다면, 절약할 수 있는 부분을 찾아낸 것입니다.

피해야 할 함정: 후보를 즉시 삭제하지 마세요. 때로는 30일 동안 실행되지 않은 Skill이, 당신이 잊고 있었던 분기별 작업에 실제로 필요한 것일 수도 있습니다. 'attic(다락방)'으로 옮기는 것이 안전한 방법입니다.

내 설정에서 변경한 점

세 개의 Skill을 attic으로 옮겼습니다. 그중 하나는 다음 달에 예정된 데이터베이스 마이그레이션(database migration) 때문에 다시 돌아올 예정입니다. 나머지 두 개는 아마 영원히 사라질 것입니다. 활성화된 두 개의 Skill은 그대로 유지되었습니다.

이 글을 쓰는 동안 실행한 세션 역시 두 개의 Skill로 줄어들었습니다. 턴당 로그(per-turn log)의 입력 토큰 라인이 이전과는 다르게 평탄해졌습니다. 11%라는 수치는 입 밖으로 내뱉으면 그리 극적으로 들리지 않을 수도 있습니다. 하지만 헤비한 Claude Code Max 플랜을 사용한다면, 월 예산의 11%는 실제 돈입니다. API 종량제(metered) 플랜에서도 다른 방식으로 실제 돈입니다. 어느 쪽이든, 이는 단지 세 개의 텍스트 파일을 컨텍스트(context)에 유지하기 위해 지불하고 있는 돈이며, 이 문장을 타이핑하는 것조차 부끄럽습니다.

만약 당신이 많은 Skills를 실행하고 있다면, 그 편리함을 좋아하는 것은 틀린 일이 아닙니다. 다만 그 편리함에는 턴(turn)당 세금이 붙으며, 그 세금은 직접 찾아보기 전까지는 보이지 않는다는 사실을 알아야 합니다.

제가 모니터 위에 포스트잇으로 붙여둘 문구는 다음과 같습니다: 로드(loaded)되었다고 해서 활성화(active)된 것은 아니며, 활성화(active)되었다고 해서 호출(invoked)된 것도 아니고, 호출(invoked)되었다고 해서 유지할 가치가 있는 것도 아니다.

이제 당신의 usage.input_tokens 라인을 확인해 보세요. 그 숫자가 바로 JSON 안에 있습니다. 그것은 내내 당신에게 이 이야기를 해주고 있었습니다.

Skills가 Hooks, MCP 서버, 그리고 서브 에이전트(sub-agents)와 함께 어떻게 조화를 이루는지에 대한 전체적인 멘탈 모델(mental model)과, 누군가 1년 전에 저에게 건네주었으면 좋았을 메커니즘별 비용 표를 알고 싶다면, Claude Code Mastery에 정리해 두었습니다. 설명 임대(description-rent) 트릭을 처음부터 눈에 보이게 만드는 컨텍스트 윈도우(context-window) 경제학에 대해서는 kenimoto.dev에서 다루고 있습니다.