Claude Code 스킬 관리: /skill-doctor로 안 쓰는 스킬과 컨텍스트 비용 줄이기

Claude Code에 스킬(Skill)을 하나씩 설치하다 보면 어느 순간 목록이 길어집니다. 문제는 모델에 노출한 Skill은 실제로 실행하지 않아도 이름과 목록 예산 안에 남은 설명이 매 턴 컨텍스트에 들어간다는 점입니다.[1] 자주 쓰는 기능을 지울 필요는 없지만, 한 번도 호출하지 않은 Skill까지 계속 모델에 알릴 이유도 없습니다.

Claude Code의 /skill-doctor 명령은 이 판단에 필요한 스킬별 컨텍스트 비용과 사용 빈도를 보여줍니다. 이 글에서는 2.1.263 환경에서 미사용 Skills를 찾고, skillOverrides로 16개를 비활성화한 뒤 /context의 Skills 비용이 6.3k에서 4.7k 토큰으로 줄어드는 과정을 확인합니다.

/skill-doctor가 필요한 이유

Claude Code Skill은 반복 작업 방법을 SKILL.md에 담아 두고 필요할 때 불러오는 기능입니다. 모델이 어떤 Skill을 쓸 수 있는지 판단하려면 세션 시작부터 사용 가능한 이름과 설명을 알아야 합니다.

여기서 비용은 두 단계로 나뉩니다.

• Skill 목록: 모델에 노출된 이름과 목록 예산 안에서 유지된 설명이 매 턴 컨텍스트를 차지
• Skill 본문: 실제 호출할 때 SKILL.md 내용이 추가로 로드

Skill을 실행하지 않았으니 비용이 0이라고 생각하기 쉽지만, 목록 비용은 이미 발생합니다. /skill-doctor는 각 항목의 목록 비용과 실제 사용 기록을 함께 보여줘 비용은 있는데 사용은 없는 Skill을 먼저 찾게 해줍니다.[1]

/context만으로도 Skills 전체 비용은 볼 수 있습니다. 다만 어느 Skill이 원인인지, 마지막으로 언제 실행했는지는 알기 어렵습니다. 두 명령의 역할은 다음처럼 나누면 됩니다.

명령	확인할 내용	사용할 때
/skill-doctor	스킬별 컨텍스트 비용, 호출 횟수, 마지막 사용 시점	정리할 후보 선택
/skills	각 Skill의 노출 상태 변경	on·name-only·user-only·off 적용
/context	현재 세션에서 Skills 전체가 차지하는 토큰	변경 전후 검증

버전과 실습 환경

/skill-doctor는 Claude Code 2.1.261 변경 기록에 추가됐고, 공식 Skills 문서는 2.1.252 이상에서 사용할 수 있다고 안내합니다.[1][2] 이 글은 기능 추가 다음 패치 버전인 2.1.263에서 확인했습니다.

claude --version

실제 출력은 다음과 같습니다.

2.1.263 (Claude Code)

버전이 낮다면 세션을 종료한 뒤 업데이트합니다.

claude update
claude --version

이번 실습 환경은 다음과 같습니다.

항목	확인 환경
운영체제	Linux
Claude Code	2.1.263
모델 컨텍스트	1M 토큰
변경 방식	별도 --settings 파일의 skillOverrides
정리 대상	7일 사용 기록과 호출 횟수를 확인한 미사용 Skill 16개

개인 설정을 바로 바꾸지 않기 위해 테스트에서는 임시 설정 파일을 추가로 연결했습니다. 실제로 계속 적용하려면 /skills가 저장하는 .claude/settings.local.json 또는 본인 범위에 맞는 settings.json을 사용하면 됩니다.

변경 전 /context 확인

Claude Code를 새로 실행한 뒤 먼저 /context를 입력합니다.

/context

변경 전 화면에서 Skills · /skills는 43 skills · 6.3k tokens로 표시됐습니다.

Claude Code 2.1.263 실제 tmux 세션 출력. 이미지를 누르면 원본 크기로 볼 수 있습니다.

/context의 전체 사용량은 시스템 프롬프트, 도구, 에이전트, 메시지까지 합친 값입니다. 이번 정리에서 비교할 기준은 화면 전체 토큰이 아니라 Estimated usage by category의 Skills 행입니다. 다른 세션에서는 MCP 연결 상태나 대화 길이가 달라질 수 있기 때문입니다.

미사용 Skills 진단

Claude Code 입력창에서 다음 명령을 실행합니다.

/skill-doctor

2.1.263에서는 별도 결과 화면 대신 /plugin 관리자의 Stats 탭이 열립니다. 상단 표에서 다음 열을 확인합니다.

• skill: Skill 이름
• source: 사용자 설정, 프로젝트, 플러그인 등 출처
• context: 매 턴 목록에 들어가는 대략적인 토큰 비용
• 7d tokens: 최근 7일 동안 해당 Skill에 귀속된 토큰
• uses: 호출 횟수
• last used: 마지막 사용 시점

비용이 표시되면서 0×, never인 항목부터 정리 후보로 볼 수 있습니다. 계정 토큰이나 인증 정보는 화면에 포함하지 않았습니다.

이번 화면에서는 목록에 로드됐지만 한 번도 호출되지 않은 Skill이 16개였습니다. 반면 blog-image, bk-start, humanize-korean처럼 과거 사용 기록이 있는 항목도 함께 보였습니다. 호출 횟수가 적다는 이유만으로 바로 끄지 않고, 앞으로 직접 실행할 가능성까지 따로 판단해야 합니다.

표의 context가 대시(-)인 Skill은 현재 목록에 들어가지 않아 비용이 없습니다. 이미 숨겨진 항목까지 다시 정리할 필요는 없습니다.

정리 기준

미사용 표시가 곧 삭제 명령은 아닙니다. 다음 순서로 상태를 고르면 과하게 끄는 일을 줄일 수 있습니다.

계속 자동으로 쓰는 Skill

모델이 요청을 보고 알아서 선택해야 하는 핵심 작업은 on을 유지합니다. 설명까지 모델에 보여야 트리거 조건을 판단할 수 있습니다.

이름만 남길 Skill

용도는 분명하지만 긴 설명을 매 턴 보낼 필요가 없다면 name-only를 검토합니다. 모델에는 이름만 보이고 / 메뉴에도 남습니다. 이름만으로 용도를 추측하기 어려운 Skill은 자동 호출 정확도가 낮아질 수 있습니다.

직접 실행할 Skill

가끔 쓰지만 항상 /skill-name으로 직접 실행하는 기능은 /skills 화면의 user-only가 맞습니다. 설정 파일 값은 "user-invocable-only"입니다. 모델 목록에서는 숨겨져 호출 전 목록 비용이 없고, 사용자의 / 메뉴에는 남습니다. 직접 실행하면 해당 Skill 본문은 컨텍스트에 로드됩니다.[1]

쓰지 않는 Skill

현재도 앞으로도 사용하지 않을 항목은 off로 둡니다. 모델 목록과 / 메뉴에서 모두 숨겨집니다. 나중에 필요하면 같은 화면에서 다시 켤 수 있으므로 파일부터 삭제할 필요는 없습니다.

상태	모델에 노출	/ 메뉴	적합한 경우
on	이름과 설명	표시	Claude가 요청을 보고 자동 선택해야 함
name-only	이름만	표시	목록 설명 비용을 줄이되 이름은 알리고 싶음
user-invocable-only	숨김	표시	사용자가 직접 실행할 때만 필요
off	숨김	숨김	사용하지 않아 완전히 비활성화

/skills에서 비활성화

설정 파일을 직접 편집하지 않으려면 /skills를 엽니다.

/skills

정리할 Skill을 선택하고 Space를 누르면 상태가 순서대로 바뀝니다. 필요한 상태를 고른 뒤 Esc로 닫으면 프로젝트 로컬 설정인 .claude/settings.local.json에 저장됩니다.[1]

이 방법은 JSON 쉼표나 키 이름을 직접 다루지 않아도 된다는 장점이 있습니다. 팀 저장소에 공유할 설정이 아니라 개인 판단으로 끄는 항목이라면 로컬 파일이 안전합니다.

비활성화 뒤에는 Claude Code를 완전히 종료하고 새 세션을 시작합니다. 이미 열린 세션의 컨텍스트만 보고 적용 여부를 판단하지 않습니다.

skillOverrides 직접 설정

여러 항목을 한 번에 관리하거나 설정을 검토 가능한 형태로 남기고 싶다면 skillOverrides를 사용합니다.

{
  "skillOverrides": {
    "bk-approve": "off",
    "bk-credential": "off",
    "find-skills": "off",
    "heygen-avatar-video": "off",
    "remotion-best-practices": "off"
  }
}

키는 /skill-doctor에 표시된 Skill 이름과 정확히 같아야 합니다. skillOverrides에 없는 Skill은 on으로 처리됩니다.[1]

이번 실습에서는 같은 형식으로 미사용 사용자 Skill 16개를 off로 지정한 임시 JSON을 만들고 다음처럼 추가 설정으로 연결했습니다.

claude --settings /tmp/claude-skill-doctor-demo-settings.json

--settings는 실험 범위를 한 세션용 파일로 분리하기 편합니다. 정상 동작을 확인한 뒤 사용자 전체에 적용하려면 ~/.claude/settings.json, 현재 프로젝트에만 적용하려면 .claude/settings.local.json처럼 범위를 선택합니다. 조직 관리 설정이 같은 키를 강제한다면 개인 설정이 우선하지 않을 수 있습니다.[3]

플러그인 Skill은 별도 관리

/skill-doctor 결과에는 사용자·프로젝트 Skill뿐 아니라 플러그인이 제공한 Skill도 나타날 수 있습니다. 다만 공식 문서 기준 플러그인 Skill에는 skillOverrides가 적용되지 않습니다. 개별 항목만 off로 바꾸는 대신 /plugin에서 플러그인 전체를 관리해야 합니다.[1]

/plugin

Installed 탭에서 플러그인이 제공하는 기능과 최근 사용 여부를 확인한 뒤 비활성화합니다. 하나의 플러그인 안에 자주 쓰는 Skill과 쓰지 않는 Skill이 함께 있다면 컨텍스트 비용만 보고 전체를 끄기보다 유지하는 편이 나을 수 있습니다.

변경 후 /context 검증

16개 항목을 off로 둔 설정을 연결하고 Claude Code를 새로 시작한 뒤 /context를 다시 실행했습니다.

/context

Skills 행은 다음처럼 바뀌었습니다.

비교 항목	변경 전	변경 후	감소
Skills 수	43개	27개	16개
Skills 컨텍스트	6.3k	4.7k	1.6k 토큰
목록 비용 비율	기준	약 75%	약 25% 감소

같은 Claude Code 2.1.263 환경에서 별도 settings 파일로 16개를 off한 뒤 확인한 결과입니다.

전체 Context Usage 숫자는 메시지, 시스템 도구, MCP 상태에 따라 세션마다 달라졌습니다. 따라서 전체 1M 중 몇 토큰이 줄었다고 단정하지 않고 Skills 카테고리의 6.3k → 4.7k를 비교 기준으로 삼았습니다.

/skill-doctor를 다시 열면 끈 항목의 context가 대시(-)로 바뀝니다. 이름은 진단 표에 남아 설정 결과를 확인할 수 있지만 현재 Skill 목록 비용은 발생하지 않는다는 뜻입니다.

줄지 않을 때 확인할 것

기존 세션을 그대로 사용함

Skill 목록은 세션 컨텍스트의 일부입니다. 설정을 바꾼 뒤에는 Claude Code를 종료하고 새로 실행해 /context를 확인합니다.

이름이 정확하지 않음

skillOverrides 키를 표시 이름처럼 임의로 바꾸면 적용되지 않습니다. /skill-doctor나 /skills에 나온 이름을 그대로 사용합니다. 플러그인 Skill은 이름을 맞춰도 개별 override 대상이 아닙니다.

설정 범위가 다름

사용자 전체, 프로젝트 공유, 프로젝트 로컬, 관리형 설정은 적용 범위와 우선순위가 다릅니다. /status로 어떤 설정 파일이 로드됐는지 확인하고, 설정 오류는 다음 명령으로 점검합니다.

claude doctor

전체 컨텍스트만 비교함

새 세션마다 도구 수와 메시지 토큰이 달라질 수 있습니다. 전체 사용량보다 /context의 Skills 행과 /skill-doctor의 context 열을 확인합니다.

사용 기록이 바로 쌓이지 않음

7d tokens는 최근 7일의 로컬 세션 기록을 기준으로 합니다. 다른 컴퓨터나 삭제한 세션의 사용 이력이 그대로 합쳐지는 통계가 아닙니다. 기록이 없다는 이유만으로 업무에 필요한 Skill을 끄지 않습니다.

정기 점검 순서

Skills를 자주 설치한다면 다음 흐름만 반복해도 목록이 무한히 늘어나는 것을 막을 수 있습니다.

1. claude --version으로 /skill-doctor 지원 버전 확인
2. 새 세션에서 /context의 Skills 수와 토큰 기록
3. /skill-doctor에서 비용이 있고 0×, never인 후보 확인
4. 자동 선택이 필요한지, 직접 실행할지, 완전히 끌지 결정
5. /skills 또는 skillOverrides로 상태 변경
6. 플러그인 Skill은 /plugin에서 별도 판단
7. Claude Code 재시작 후 /context와 /skill-doctor로 검증

Skills는 많을수록 무조건 나쁜 기능이 아닙니다. 반복 작업을 안정적으로 수행하게 해주는 대신, 모델이 알아야 할 목록도 함께 늘어납니다. /skill-doctor는 이 목록을 감이 아니라 실제 비용과 사용 기록으로 정리하게 해주는 도구입니다.

한 번에 모두 끄기보다 on → name-only 또는 user-only → off 순서로 노출을 낮추고, /context의 Skills 행이 실제로 줄었는지 확인하면 됩니다. Claude Code 설치부터 필요하다면 Claude Code 처음 설치하고 실행해보기를, 컨텍스트와 계정 사용량의 차이는 Claude Code·Codex CLI 사용량 확인에서 이어서 볼 수 있습니다.

참고 자료

[1] https://code.claude.com/docs/en/skills — Claude Code Skills 공식 문서
[2] https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md — Claude Code CHANGELOG (2.1.261)
[3] https://code.claude.com/docs/en/settings — Claude Code settings 공식 문서
[4] https://www.npmjs.com/package/@anthropic-ai/claude-code — npm: @anthropic-ai/claude-code