본문으로 바로가기
Solo Dev AI
Lab

클로드 코드(Claude Code) 스킬 토큰, 20개 깔아 직접 해 보니

Claude Code 스킬 20개를 프로젝트에 넣으면 입력 토큰이 837개 늘었고, 본문을 4배로 늘려도 836개였습니다. 클로드 코드가 세션을 시작할 때 무엇을 싣는지와 스킬 설명을 쓰는 법을 정리했습니다.

· · 수정

얇은 카드 스무 장은 작은 상자에 담기고 두꺼운 책들은 바깥 선반에 남아 있는 개념 그림
클로드 코드(Claude Code) 스킬 토큰, 20개 깔아 직접 해 보니 표지 삽화

프로젝트에 Claude Code 스킬 20개를 넣고 한 턴짜리 요청을 보냈더니 입력 토큰이 빈 프로젝트보다 837개 늘었습니다. 스킬 본문을 4배로 늘려도 836개였죠. 클로드 코드가 세션을 시작할 때 스킬 설명만 싣고 본문은 스킬을 쓸 때 불러온다는 공식 문서의 설명과 맞는 결과입니다.

스킬 20개를 깔면 토큰이 얼마나 늘까요?

결론부터 말하면 스킬 5개는 238토큰, 20개는 837토큰이 늘었습니다. 20개일 때 스킬 하나당 평균 약 42토큰입니다. 빈 프로젝트도 이미 30,706토큰에서 시작하니 스킬 때문에 늘어난 몫은 크지 않습니다.

조건입력 토큰(3회 중앙값)빈 프로젝트 대비
빈 프로젝트30,706+0
스킬 5개30,944+238
스킬 20개31,543+837
스킬 20개, 본문 4배31,542+836

세션 시작 정보에 잡힌 스킬 목록도 함께 늘었습니다. 빈 프로젝트에서는 22개, 스킬 5개 조건에서는 27개, 20개 조건에서는 42개였어요. 그렇다면 본문을 스킬마다 307자에서 1,234자로 늘렸을 때는 왜 그대로였을까요?

스킬 5개, 20개, 본문을 4배로 늘린 20개가 빈 프로젝트보다 늘린 입력 토큰을 비교한 막대그래프
조건별로 직접 잰 입력 토큰 증가량(3회 중앙값)
도식출처: Claude Code 입력 토큰 측정

함께 읽을 글

본문을 4배로 늘려도 왜 그대로일까요?

스킬 공식 문서는 CLAUDE.md와 달리 스킬 본문은 쓸 때만 불러온다고 설명합니다. 그래서 긴 참고 자료도 필요해지기 전까지는 비용이 거의 들지 않는다고 하죠. 컨텍스트 창 문서도 입력하기 전에 CLAUDE.md, 자동 메모리, MCP 도구 이름과 함께 스킬 설명이 실린다고 적고 있습니다.

정리하면 세션을 시작할 때 들어가는 것은 스킬 설명이고, 본문은 그 뒤의 일입니다. 이번 측정은 스킬을 한 번도 부르지 않는 한 턴이었으니 본문 길이가 숫자에 드러나지 않은 것이죠. 대화가 길어져 압축(compaction)이 일어날 때는 다음처럼 다시 들어갑니다.

세션 시작, 스킬을 쓸 때, 압축 후, 압축 후 상한, 합계 초과 시로 나눠 스킬 설명과 스킬 본문이 어떻게 들어가는지 비교한 표. 압축 후 칸에는 호출한 본문만 다시 실린다고, 상한 칸에는 스킬당 5,000토큰과 합계 25,000토큰이, 합계 초과 시 칸에는 오래된 것부터 제외한다고 적혀 있다
공식 문서 기준으로 정리한 스킬 설명과 본문이 실리는 시점
도식출처: 근거를 바탕으로 코드가 그린 도식
  • 스킬 설명: 지금 가진 스킬로 다시 만들어 넣습니다(Claude Code v2.1.304 이상).
  • 이미 부른 스킬 본문: 스킬당 5,000토큰, 합계 25,000토큰까지 다시 넣고, 넘치면 오래된 것부터 뺍니다.
  • 잘릴 때는 파일 앞부분이 남으므로, 중요한 지시는 SKILL.md 위쪽에 두라고 문서는 권합니다.

클로드 코드 스킬 개수는 어떻게 판단할까요?

이 측정에서 스킬 하나는 설명 한 줄만큼의 비용이었습니다. 그래서 혼자 제품을 만들며 배포 점검, 마이그레이션, PR 요약처럼 반복하는 절차를 스킬로 나눠 두는 일은 개수만으로 크게 망설일 이유가 없어 보입니다. 다만 이것은 짧은 설명 20개에서 본 값이라, 설명이 길거나 개수가 훨씬 많을 때까지 그대로 늘어난다고 단정할 수는 없습니다.

작은 설명 카드 스무 장은 작업대에 모두 올라가 있고 두꺼운 설명서는 서랍에 있다가 한 권만 꺼내지는 개념 그림
세션 시작에는 짧은 설명만, 본문은 쓸 때 불러오는 구조를 그린 개념 그림

이럴 때는 자기 환경에서 직접 확인하는 편이 정확합니다. 세션 안에서 /context를 실행하면 지금 컨텍스트 사용량을 항목별로 보여 주고 줄일 방법도 제안합니다. /doctor의 확장 점검은 쓰지 않는 스킬, MCP 서버, 플러그인을 컨텍스트 비용과 함께 보여 주니 가끔 돌려 보세요.

스킬 설명은 어떻게 써야 할까요?

본문은 쓸 때만 실리지만 설명은 매 세션 들어갑니다. 게다가 문서에 따르면 Claude는 description을 보고 스킬을 자동으로 불러올지 정합니다. 그래서 설명에는 무엇을 하는지와 언제 쓰는지만 짧고 분명하게 담는 것이 좋겠습니다. 공식 문서의 예시가 이 짜임을 따릅니다.

yaml
---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

측정에 쓴 스킬 설명도 모두 "Stripe 웹훅 처리 코드를 만들거나 고칠 때 쓴다"처럼 언제 쓰는지를 말하는 한 문장이었습니다. 바로 해 볼 일은 이렇습니다.

  • 설명은 하는 일과 쓰는 때를 한두 문장으로 씁니다.
  • 긴 절차와 참고 자료는 설명이 아니라 본문에 둡니다.
  • 본문에서 꼭 지켜야 할 지시는 위쪽에 둡니다.
  • CLAUDE.md에 절차처럼 길어진 부분이 있다면 스킬로 옮길지 검토합니다. 문서도 이런 경우에 스킬을 만들라고 권합니다.
  • 스킬을 더한 뒤 /context로 실제 증가량을 확인합니다.

개인 스킬은 ~/.claude/skills/<이름>/SKILL.md, 프로젝트 스킬은 .claude/skills/<이름>/SKILL.md에 둡니다. 문서의 첫 예시처럼 폴더부터 만들면 됩니다.

bash
mkdir -p ~/.claude/skills/summarize-changes

측정 조건과 한계

측정 환경은 Claude Code 2.1.309, 모델 claude-opus-5-5, darwin arm64, Node.js v22.23.1이었습니다. 조건마다 새 임시 프로젝트 폴더에서 아래 명령을 한 턴 실행하고, 결과 JSON의 새 입력, 캐시 쓰기, 캐시 읽기 토큰을 더했습니다. 조건을 번갈아 3번씩 재 중앙값을 썼고, 뺀 회차는 없었습니다.

bash
claude -p "Reply with only: OK"

사용자 설정, 플러그인, 훅은 --setting-sources project로 불러오지 않았고, MCP는 --strict-mcp-config로 조건에 적은 서버만 붙였습니다. 스킬은 모두 프로젝트 위치에 두었고 본문은 20개가 같았습니다. 그래서 다음은 이 측정으로 알 수 없습니다.

  • 스킬을 실제로 불러 본문이 실렸을 때 늘어나는 토큰
  • 설명이 길 때, 개인 스킬이나 플러그인 스킬일 때의 차이
  • 다른 모델이나 버전에서의 값

본문 4배 조건의 -1개 차이도 마찬가지입니다. 같은 조건의 회차끼리도 값이 몇 토큰씩 달랐으니, 이 측정만으로는 의미 있는 차이라고 보기 어렵습니다. 자기 설정에서 숫자가 궁금하다면 같은 명령을 스킬 폴더만 바꿔 가며 직접 실행해 보세요.

참고 자료