Claude Code 사용법: /skill-doctor로 스킬 컨텍스트 비용 줄이기

이제 Claude Code 사용법에서 놓치기 쉬운 낭비까지 확인할 수 있습니다. 실제 작업에 도움이 되지 않으면서 컨텍스트를 차지하는 Claude Code 스킬을 찾아내고, 워크플로에 꼭 필요한 지침은 버리지 않은 채 그 비용만 걷어낼 수 있습니다. 새 /skill-doctor 보고서는 감에 의존하던 스킬 정리를 측정 가능하고 언제든 되돌릴 수 있는 운영 습관으로 바꿉니다.

핵심은 간단합니다. /skill-doctor를 실행하고, 사용되지 않은 각 스킬을 없앴을 때의 위험에 따라 분류한 다음, 가장 덜 파괴적인 공개 범위 변경을 적용해 새 세션에서 테스트합니다. 처음부터 폴더를 삭제해서는 안 됩니다. 일주일 동안 조용했던 스킬도 배포나 장애 대응을 안전하게 지켜 주는 장치일 수 있습니다.

2026년 9월 4일 출시된 Claude Code 2.1.261에는 로드됐지만 쓰이지 않는 스킬과 각 스킬의 컨텍스트 비용을 보여 주는 /skill-doctor가 추가됐습니다. Claude가 전체 지침을 한 번도 호출하지 않더라도, 목록에 오른 모든 스킬은 매 턴 이름과 대개 설명까지 컨텍스트에 보태기 때문에 중요한 변화입니다.

Claude Code 사용법의 핵심: 스킬 컨텍스트 비용이란?

스킬 컨텍스트에는 두 종류의 비용이 있습니다. 둘을 혼동하면 엉뚱한 스킬부터 정리하게 됩니다.

첫째는 목록 비용입니다. 사용자가 아무것도 입력하기 전부터 Claude는 요청에 맞는 스킬을 고를 수 있도록 사용 가능한 스킬의 이름과 설명을 봅니다. Anthropic은 기본적으로 이 목록을 모델 컨텍스트 창의 1%로 제한하며, 스킬마다 description과 when_to_use를 합친 텍스트의 기본 상한은 1,536자입니다.

둘째는 호출 비용입니다. SKILL.md의 전체 본문은 사용자나 Claude가 해당 스킬을 호출할 때만 로드됩니다. 한 번 로드되면 이후 턴에도 대화 안에 남습니다. 컨텍스트 압축 후에는 호출된 스킬마다 최대 5,000토큰을 Claude Code가 다시 붙일 수 있으며, 재첨부되는 전체 스킬의 합산 예산은 25,000토큰입니다.

목록은 쇼윈도, 스킬 본문은 손님이 요청한 뒤 카운터로 가져오는 재고라고 생각하면 쉽습니다. 거리의 간판은 하나마다 자리를 차지합니다. 재고는 훨씬 넓은 공간을 쓰지만, 누군가 찾은 뒤에야 비용이 발생합니다.

이 차이에 따라 해법도 달라집니다. 설명이 긴 미사용 스킬은 목록 비용을 계속 발생시킵니다. 자주 호출되는 데다 본문까지 큰 스킬은 세션 비용을 지속적으로 키웁니다. /skill-doctor는 첫 번째 문제를 찾는 데 특히 강하고, 두 번째 문제는 잘 설계된 스킬 구조로 해결해야 합니다.

비용 계산의 기준은 설치 횟수가 아니라 턴 수입니다

사용하지 않는 스킬은 한 번으로 끝나는 설치 비용이 아닙니다. 대화가 진행될 때마다 목록 텍스트가 다시 제공됩니다. 실무에서는 다음 식으로 낭비 규모를 가늠할 수 있습니다.

하루에 줄일 수 있는 컨텍스트 = 턴당 미사용 목록 토큰 × 하루 Claude 턴 수

예를 들어 보고서에서 미사용 목록 컨텍스트가 2,000토큰이고 하루 업무 중 모델 턴이 40회 발생한다면, 하루 동안 입력으로 제시되는 토큰은 80,000개입니다. 이는 예시이지 벤치마크가 아닙니다. 프롬프트 캐싱은 반복 텍스트에 청구되는 요율을 낮출 수 있지만, 컨텍스트 자체를 없애 주지는 않습니다.

API나 클라우드 공급자를 통해 사용하는 경우 이 추가 토큰이 청구액에 반영됩니다. 구독 사용자는 플랜 한도를 더 빨리 소모하고, 압축 전까지 활용할 작업 공간도 줄어듭니다. Anthropic에 따르면 기업용 Claude Code 배포의 평균 비용은 개발자당 실제 사용일 기준 약 $13, 월 $150~$250입니다. 스킬 낭비는 전체 지출의 일부에 불과하지만, 이제는 이름별로 분리해 볼 수 있는 몇 안 되는 항목이 됐습니다.

문제는 모델 비용에만 그치지 않습니다. 개발 처리량도 영향을 받습니다. 목록이 붐비면 Claude Code는 가장 적게 사용된 스킬부터 설명을 제외할 수 있습니다. 공간은 절약되지만, Claude가 해당 스킬을 자동으로 선택하기는 더 어려워집니다.

정리하고 다시 실행한 뒤 복원하는 워크플로

가장 안전한 절차는 일곱 단계입니다.

1. 최신 버전의 터미널 세션에서 시작합니다

Claude Code를 2.1.261 이상으로 업데이트하고 claude --version으로 설치 버전을 확인합니다. Anthropic 레퍼런스에는 /skill-doctor가 2.1.252 이상에서 필요하다고 적혀 있고, 이 명령을 발표한 변경 로그의 출시 버전은 2.1.261입니다.

세션이 실행되는 시스템의 터미널에서 /skill-doctor를 실행합니다. 대화형 세션에서는 /plugin 관리자의 Stats 탭에 보고서가 열립니다. -p를 쓰는 비대화형 모드에서는 텍스트로 출력되므로 로컬 감사 기록을 남기기 좋습니다. Remote Control에서는 이 보고서를 받아올 수 없습니다.

2. 기준값을 기록합니다

변경 전에 세 가지를 저장합니다. 전체 스킬 목록 비용, 사용되지 않은 항목 중 비용이 가장 큰 것들, 그리고 바꾸려는 스킬이나 플러그인입니다. /context도 실행해 예산 적용 후의 Skills 행을 확인하고, /doctor로 목록 비용의 최대 기여 항목을 찾습니다.

사용 모델과 캐시 동작, 계약 요율을 모른다면 토큰 수를 곧바로 달러로 환산하지 마십시오. 토큰을 일관된 기준으로 삼고 비용은 별도로 계산하는 편이 정확합니다.

3. 없앴을 때의 위험에 따라 후보를 분류합니다

각 후보를 다음 세 범주 중 하나에 넣습니다.

이 단계에서는 보고서만큼 사람의 판단도 중요합니다. “호출된 적 없음”은 빈도를 나타낼 뿐, 가치를 뜻하지 않습니다. 소화기는 한 번도 쓰지 않았어도 비치할 가치가 있습니다.

4. 가장 덜 파괴적인 제어 수단을 선택합니다

로컬·개인·프로젝트·동기화 스킬은 /skills 메뉴에서 .claude/settings.local.json에 되돌릴 수 있는 skillOverrides 변경을 기록할 수 있습니다.

• 스킬의 존재는 Claude가 알아야 하지만 목록에 전체 설명까지 필요하지 않다면 name-only를 사용합니다.
• /skill-name은 남겨 두되 자동 선택은 막고 싶다면 user-invocable-only를 사용합니다.
• 사용자와 Claude 모두 해당 스킬을 볼 필요가 없을 때만 off를 사용합니다.
• 원래 동작으로 되돌릴 때는 on을 사용합니다.

직접 소유한 스킬이라면 disable-model-invocation: true가 사용자 전용 정책을 작성자 수준에서 이식 가능하게 구현하는 방법입니다. Claude의 목록에서는 설명을 빼면서 직접 호출 기능은 유지합니다.

플러그인 스킬은 다릅니다. skillOverrides가 적용되지 않습니다. 삭제하지 않고 플러그인을 끄려면 /plugin disable plugin-name@marketplace-name을 사용하고, 복원할 때는 /plugin enable plugin-name@marketplace-name을 실행합니다. 플러그인은 에이전트, 훅, MCP 서버, 언어 도구도 함께 제공할 수 있으므로 끄기 전에 구성 요소를 확인해야 합니다.

5. 기능은 유지하면서 본문을 줄입니다

유용한 스킬의 본문이 크다면 SKILL.md는 라우팅 카드로 남기고, 자세한 예시와 API 레퍼런스, 예외 상황은 지원 파일로 옮깁니다. Anthropic은 SKILL.md를 500줄 미만으로 유지하도록 권장합니다. 지원 파일은 Claude가 필요로 할 때만 로드되며, 헬퍼 스크립트는 소스 전체를 프롬프트에 넣지 않고도 실행할 수 있습니다.

작업, 트리거, 반드시 지켜야 할 규칙, 지원 파일 안내는 문서 앞부분에 둡니다. 압축 후 다시 붙는 각 스킬에서 첫 5,000토큰만 유지되는 상황에도 중요한 내용을 보호할 수 있습니다.

6. 새 세션에서 테스트합니다

스킬 설정을 바꿔도 현재 대화에 이미 로드된 지침은 사라지지 않습니다. 새 세션을 시작해 해당 스킬을 호출해야 하는 프롬프트 몇 개를 실행하고, 스킬을 숨긴 상태에서 같은 프롬프트를 실행한 결과와 비교합니다. 작업 성공 여부를 먼저, 토큰을 그다음에 측정합니다.

Anthropic이 새 세션 비교를 권장하는 이유는 기존 작성 과정이나 스킬 컨텍스트가 해당 스킬의 실제 기여도를 가릴 수 있기 때문입니다. 플러그인 변경에 /reload-plugins가 필요하다면 다음 요청에서 토큰 비용이 발생할 수 있으며, 플러그인이 지연 로드되지 않는 MCP 툴을 노출할 경우 프롬프트 캐시가 다시 만들어질 수도 있습니다.

7. 문제가 생기면 복원하고 감사를 다시 실행합니다

품질이 떨어지면 한 단계만 되돌립니다. off에서는 user-invocable-only로, 사용자 전용에서는 name-only로 바꾸거나, 비활성화했던 플러그인을 다시 활성화합니다. 품질이 유지된다면 가벼워진 상태를 보존하고, 실제 업무를 충분히 대표하는 기간이 지난 뒤 /skill-doctor를 다시 실행합니다.

마지막 확인은 꼭 필요합니다. 목표는 스킬 목록을 가능한 한 짧게 만드는 것이 아닙니다. 반복 업무를 정확히 라우팅하면서도 비용이 가장 적게 드는 목록을 만드는 것입니다.

효과가 가장 큰 사용자

다음 활용 사례는 예상되는 경제적 효과가 큰 순서로 정리했습니다.

1. 공용 Claude Code 환경을 관리하는 플랫폼 팀

개발자가 수십 명인 조직의 플랫폼 리드는 파일럿 그룹에 로컬 /skill-doctor 보고서 내보내기를 요청할 수 있습니다. 어디에나 표시되지만 전혀 호출되지 않는 스킬을 찾아 선택형 워크플로를 사용자 전용이나 프로젝트 전용으로 옮기는 방식입니다. 절감 효과는 개발자의 모든 턴에 걸쳐 누적되고, 복원 파일 덕분에 실험도 되돌릴 수 있습니다. 기업에서 관리하는 스킬은 보고서에서 제외되므로, 완전한 정책 감사가 아니라 로컬 환경 전체를 가늠하는 표본으로 활용해야 합니다.

2. 플러그인을 많이 쓰는 엔지니어링 팀

한 번의 마이그레이션 때문에 플러그인을 설치한 뒤 그 안의 스킬, 에이전트, 훅, MCP 툴을 몇 달씩 켜 둘 수 있습니다. /skill-doctor는 최근 사용되지 않은 플러그인을 드러내고, 플러그인 관리자는 삭제 없이 비활성화할 수 있게 해 줍니다. 사용하지 않는 플러그인이 컨텍스트를 차지하는 여러 구성 요소를 추가할 수 있으므로 효과는 스킬 설명 하나보다 큽니다. 주의할 점도 같은 만큼 큽니다. 비활성화하면 유용한 비스킬 구성 요소까지 사라질 수 있습니다.

3. 고객사 기술 스택을 오가는 컨설턴트

현재 고객에게 맞는 것은 한 종류뿐인데도 프런트엔드, 데이터, 이커머스, 인프라 스킬을 전역으로 들고 다니는 경우가 있습니다. 로컬 설정에 이름 있는 프로필을 만들고 관련 그룹만 노출하며, 드물게 쓰는 안전 워크플로는 사용자 전용으로 둘 수 있습니다. 매주 월요일마다 툴킷을 다시 만들지 않아도 프로젝트마다 깔끔한 시작 컨텍스트를 확보할 수 있습니다.

4. 대규모 모노레포 관리자

Claude Code는 더 깊은 디렉터리를 읽으면서 중첩된 스킬을 발견할 수 있고, 그렇게 찾은 스킬은 세션이 끝날 때까지 사용 가능한 상태로 남습니다. 모노레포 관리자는 여러 패키지에 걸친 작업이 끝난 뒤 감사를 실행하고, 패키지별 지침은 알맞은 하위 디렉터리로 옮기며, 루트 수준 설명은 줄일 수 있습니다. 라우팅도 더 정확해집니다. 백엔드 작업에 프런트엔드 워크플로 설명이 줄줄이 따라붙지 않습니다.

5. 드물지만 위험도가 높은 명령을 쓰는 팀

배포, 롤백, 데이터 마이그레이션, 장애 대응 스킬은 몇 주 동안 한 번도 호출되지 않을 수 있습니다. 보고서에 미사용으로 표시됐다는 이유만으로 삭제해서는 안 됩니다. 수동 전용으로 지정하면 Claude의 반복 목록에서 설명은 사라지지만 정확한 /skill-name 비상구는 남습니다. 평상시 세션의 컨텍스트는 줄이면서도 긴급 상황에 런북을 다시 만들 필요가 없습니다.

6. 레퍼런스가 많은 지침을 만드는 스킬 작성자

스킬 작성자는 보고서에서 비용이 큰 스킬을 찾은 뒤 긴 예시와 명세를 지원 파일로 분리할 수 있습니다. 메인 파일은 간결한 의사결정 지도가 됩니다. 세부 내용은 작업이 필요한 분기에 도달했을 때만 들어오므로 컨텍스트 비용 발생 시점을 늦출 수 있습니다.

7. 구독 한도 안에서 작업하는 개인 개발자

Pro와 Max는 구독에 사용량이 포함되므로 직접적인 달러 절감이 보이지 않을 수 있습니다. 대신 같은 한도에서 더 많은 일을 처리하고, 압축 전까지 더 넓은 작업 공간을 쓸 수 있습니다. /skill-doctor를 깔끔한 Claude Code 설정과 함께 활용하고, 관련 없는 작업으로 전환할 때는 세션을 비웁니다.

만들어 볼 가치가 있는 제품 세 가지

새 검색어만 보면 놓치기 쉽지만 관련 검색 시장은 더 큽니다. DataForSEO에 따르면 미국에서 claude code skills의 월간 검색량은 12,100회이고 CPC는 $8.26입니다. 스킬 컨텍스트 절감에 관한 좁은 검색어에는 추천 결과가 없었습니다. 이미 형성된 스킬 시장 안에서 신선한 기회가 열린 것이지, 독립된 성숙 카테고리가 생긴 것은 아닙니다.

1. 가장 유망한 선택, Skill Budget Guard

저장소의 스킬과 공개 범위 설정, 내보낸 /skill-doctor 보고서를 읽어 각 풀 리퀘스트의 컨텍스트 증감을 보여 주는 로컬 우선 CLI 및 CI 검사를 만듭니다. 한 개발자의 정리 작업을 반복 가능한 팀 예산으로 바꿀 수 있으므로 플랫폼 팀이 비용을 지불할 만합니다.

수요 신호는 이례적으로 분명합니다. claude code skills는 월 12,100회 검색되고 CPC는 $8.26이며, Anthropic이 밝힌 기업용 Claude Code의 평균 비용은 개발자당 월 $150~$250입니다. 판매 가능한 최소 버전에는 로컬 파서, 저장소에 체크인하는 예산 파일, GitHub Action, 그리고 “사용자 전용으로 전환”이나 “레퍼런스 분리”처럼 되돌릴 수 있는 제안이 필요합니다.

분명한 약점은 플랫폼 리스크입니다. Anthropic이 /skill-doctor 기능을 확장할 수 있고, 자격을 갖춘 조직에는 Analytics API도 이미 무료입니다. 방어력을 만들 수 있는 층은 정책 변경 이력, 저장소 간 비교, 컨텍스트를 줄여도 작업 성공률이 떨어지지 않았다는 증거입니다.

2. Project Skill Profile Switcher

frontend, data, incident, release처럼 이름을 붙인 프로필을 만들어 skillOverrides와 플러그인 활성화·비활성화 변경을 함께 적용하고, 한 명령으로 이전 상태를 복원하게 합니다. 구매자는 컨설턴트와 모노레포 팀입니다.

DataForSEO에 따르면 best claude code skills의 월간 검색량은 590회이며, 상업적 검색 의도와 $11.91의 CPC를 보입니다. MVP에는 매니페스트, 변경 사항 미리보기, 로컬 설정을 안전하게 쓰는 기능, 플러그인 명령, 복원 체크포인트가 필요합니다. 단점은 얕은 진입 장벽입니다. Claude Code 자체 메뉴가 이미 기반 제어 기능을 제공하며, 플러그인을 다시 로드하면 한 턴의 캐시 비용이 추가될 수 있습니다.

3. Skill Outcome Lab

같은 현실적인 프롬프트를 스킬을 켠 새 세션과 끈 새 세션에 각각 보내고 성공률, 시간, 토큰 사용량을 비교하는 테스트 러너를 만듭니다. 스킬 작성자와 사내 역량 강화 팀은 지침이 차지하는 컨텍스트만큼 실제 가치가 있다는 증거에 비용을 지불할 수 있습니다.

DataForSEO에 따르면 claude code skills best practices의 월간 검색량은 110회이며, 상업적 검색 의도와 $4.14~$6.01의 페이지 상단 입찰가를 보입니다. 쓸 만한 MVP에는 프롬프트 픽스처, 예상 출력 검사, 새 세션 격리, 간단한 전후 비교 보고서가 필요합니다.

결정적인 한계가 있습니다. Anthropic의 공식 skill-creator 플러그인은 이미 스킬 사용 여부에 따른 벤치마크를 제공합니다. 따라서 독립 회사로 만들기보다 Skill Budget Guard 안의 기능으로 넣는 편이 맞습니다.

팀이 여러 제품이나 에이전트에 스킬을 배포한다면 Notion Skills와 Claude Skills API 비교에서 의사결정의 거버넌스 측면까지 확인할 수 있습니다.

/skill-doctor로 해결할 수 없는 것

/skill-doctor는 스킬 목록의 낭비를 분석하는 프로파일러이지, Claude Code 비용 전체를 최적화하는 도구는 아닙니다.

• 번들 스킬이나 기업용 스킬을 감사하지 않습니다.
• 현재 대화에 이미 로드된 스킬 본문을 제거하지 않습니다.
• CLAUDE.md, 이전 대화 기록, 모델 선택, thinking 토큰, 장황한 툴 출력, MCP 오버헤드는 측정하지 않습니다.
• Remote Control을 통해 사용량 보고서를 반환할 수 없습니다.
• 드물게 쓰이는 스킬이 값비싼 실수를 막았는지는 판단할 수 없습니다.
• 캐시된 컨텍스트를 무료로 만들지 않습니다. 캐시 가격과 컨텍스트 점유는 별개의 문제입니다.

처음부터 skillListingBudgetFraction을 낮추지 마십시오. 목록이 예산을 넘으면 Claude Code는 이름은 유지하되 가장 적게 사용된 스킬부터 설명을 제외합니다. 목록 텍스트는 줄어들지만, 필요한 스킬이 자동으로 호출될 가능성도 낮아질 수 있습니다. 가치가 낮은 항목을 직접 판단해 제거하거나 숨기는 편이 낫습니다.

플러그인이 보이자마자 삭제하는 것도 잘못된 접근입니다. 먼저 비활성화하고 테스트한 뒤, 다른 구성 요소까지 불필요하다는 사실을 확인했을 때만 삭제합니다.

월요일에 바로 실행할 일

실제 저장소 하나와 Claude Code를 자주 쓰는 개발자 한 명을 정합니다. /skill-doctor를 실행해 비용이 가장 큰 미사용 항목 다섯 개를 기록하고, 그중 두 개만 바꿉니다. 드문 워크플로 하나는 사용자 전용으로 전환하고, 정말 관련 없는 플러그인 하나는 비활성화합니다. 새 세션에서 평소 작업 세 개를 반복한 뒤 결과가 달라진 항목은 모두 복원합니다. 그러면 에이전트 성능을 조용히 떨어뜨린 깔끔한 설정이 아니라, 금요일까지 근거를 갖춘 컨텍스트 절감 정책을 만들 수 있습니다.

Claude Code의 컨텍스트 사용량을 줄이는 방법은 무엇인가요?

/skill-doctor로 사용되지 않는 스킬 목록 비용을 찾고, /context로 전체 내역을 확인합니다. 관련 없는 스킬은 숨기고, 드문 워크플로는 사용자 전용으로 바꾸며, 긴 레퍼런스는 지원 파일로 옮깁니다. 서로 관련 없는 작업 사이에는 /clear를 사용합니다.

Claude Code 비용을 최소화하려면 어떻게 해야 하나요?

먼저 반복되는 컨텍스트를 줄인 다음 모델 선택, 긴 세션, thinking 설정, 장황한 툴 출력, 사용하지 않는 MCP 서버를 점검합니다. /skill-doctor가 다루는 것은 전체 비용 중 스킬 부분뿐입니다.

Claude Code 스킬은 무료인가요?

Anthropic의 스킬 문서에는 로컬 SKILL.md에 별도 요금이 있다고 적혀 있지 않습니다. 다만 이름과 설명은 매 턴 컨텍스트를 사용할 수 있고, 전체 본문은 호출된 뒤 컨텍스트를 차지합니다. API 사용자는 토큰 사용량에 따라 비용을 내고, 구독 사용자는 포함된 한도를 소모합니다.

Claude Code 컨텍스트를 압축하는 방법은 무엇인가요?

긴 작업의 흐름을 이어 가야 할 때는 /compact를, 관련 없는 작업으로 바꿀 때는 /clear를 사용합니다. 호출된 스킬 본문은 압축 후 다시 첨부될 수 있으며, 한도는 스킬당 5,000토큰, 전체 25,000토큰입니다.

Claude Code 컨텍스트를 비워야 하나요?

관련 없는 작업으로 이동할 때는 비우는 것이 좋습니다. 스킬 정리 테스트에서는 새 세션이 특히 중요합니다. 기존 대화에 이미 로드된 스킬 본문이 비활성화 효과를 가릴 수 있기 때문입니다.

엔지니어링 팀에 맞춰 측정 가능한 스킬 거버넌스 워크플로를 구축하려면 AI 프로덕션 시스템을 확인하세요.