Claude Code Skills: 필요한 기능을 유지하며 컨텍스트 관리하기

Claude Code를 꾸준히 사용하면 전용 스크립트, 서식 규칙, 타입 검사, 프레임워크별 템플릿이 늘어납니다. 모든 도구를 상시 지침으로 연결하면 첫 요청 전에 컨텍스트를 소모합니다. 스킬 목록을 점검하고 상시 규칙과 필요할 때 실행할 절차를 분리한 뒤, 모델이 필요한 스킬을 제대로 찾는지 확인해 보겠습니다.

세션 시작 시 어떤 내용이 로드되는가

일반 세션에서 on인 스킬은 이름과 description이 모델에 전달됩니다. name-only는 이름만 남깁니다. user-invocable-only 또는 disable-model-invocation: true는 모델에게 설명을 숨기며, off는 스킬을 숨깁니다. SKILL.md 본문은 호출 후 로드되어 해당 세션에 남습니다. 보조 파일은 필요할 때 읽고 스크립트는 도구로 실행합니다. 자세한 동작은 공식 Skills 문서를 참고하세요.

컨텍스트 비용은 목록의 이름·설명·트리거, 호출 후 읽는 지침 본문, 필요할 때 사용하는 참조 자료와 스크립트로 나누어 봅니다. 방대한 API 문서나 코드 생성 규칙을 description 또는 전역 CLAUDE.md에 넣으면 작업을 시작하기 전부터 컨텍스트가 커집니다.

자신의 BetterToken API Key로 시험한다면 Dashboard에서 모델, 시간, 상태, input·output·cache Token을 대조할 수 있습니다. 실제 API 요청을 확인하는 데 도움이 되지만 어느 로컬 스킬이 컨텍스트를 차지했는지는 알 수 없으므로 /context를 대체하지 않습니다. 현재 연결 설정은 BetterToken Docs에서 확인하세요.

스킬이 너무 많다면 /skill-doctor부터 실행하기

목록을 수작업으로 판단하기 어려우면 로컬 Claude Code 세션에서 /skill-doctor를 실행합니다. 컨텍스트 비용과 호출 빈도를 보여 주고, 로드되었지만 사용되지 않은 스킬을 찾을 수 있습니다. 대화형 보고서는 /plugin 관리자의 Stats 탭에서 열립니다. 내장 스킬과 기업 스킬은 포함하지 않습니다. 보고서 설명을 확인하세요.

1. 자주 사용하는 프로젝트를 골라 목록과 대표적인 작업을 대조합니다. 호출 기록이 없다고 불필요한 것은 아닙니다. 복구 절차는 몇 달에 한 번만 필요할 수도 있습니다.
2. 가끔 사용하는 개인·프로젝트 스킬은 /skills에서 user-invocable-only로 바꿉니다. 메뉴에는 user-only로 표시됩니다. 해당 환경에서 더 이상 필요하지 않으면 off를 선택할 수 있습니다. 플러그인 스킬은 /plugin에서 관리합니다.
3. 새 세션에서 /context를 비교하고 일상 작업 하나와 남겨 둔 저빈도 스킬의 명시 호출을 시험합니다. 필요한 작업을 계속 수행할 수 있어야 컨텍스트 감소에도 의미가 있습니다.

이 명령은 v2.1.261 릴리스 노트에 소개되지만, 현재 문서는 최소 버전을 v2.1.252로 안내합니다. claude --version으로 버전을 확인하세요. 기능 사용 여부는 feature flags를 가져오는지에도 달려 있습니다. Remote Control 연결에서는 보고서를 사용할 수 없으므로 세션이 실행되는 컴퓨터의 터미널에서 실행합니다. 명령이 없다면 아래 수동 점검을 계속합니다.

사용 빈도와 위치로 목록 정리하기

프로젝트의 .claude/skills/와 개인용 ~/.claude/skills/를 확인합니다. 중첩 스킬은 해당 하위 디렉터리의 파일을 처음 읽거나 수정한 뒤 사용할 수 있어 시작 시점에 모두 보이지 않을 수 있습니다. 플러그인 스킬에는 이름 공간이 있으며 skillOverrides로 관리하지 않습니다. 동기화된 스킬의 발견 방식도 로컬, Cowork, cloud에서 다릅니다. 실제 사용하는 환경마다 파일 목록을 /skills와 대조하세요.

빈도	작업 예시	배치 방법
매일	코드 스타일, 테스트, git status 확인	짧은 CLAUDE.md 규칙 또는 기본 스킬
작업에 따라	DB 마이그레이션, OpenAPI 생성, 릴리스 점검	범위가 명확한 description을 가진 스킬
드물게·설계 작업	초기 보안 감사, 신규 서비스 배포	user-only 스킬, 명시 명령, scripts

보안·복구·릴리스 절차는 드물게 쓰더라도 명시적으로 호출할 수 있게 유지합니다. 실제 사용 시나리오를 확인한 후에 비활성화 여부를 결정하세요.

상시 규칙이 필요 없는 작업은 어디에 둘까

생성 문서를 원본과 생성기로 갱신하는 작업을 예로 들면 다음처럼 역할을 나눌 수 있습니다.

필요한 동작	사용할 수단	확인할 결과
매번 갱신 방법을 상기시키기	짧은 CLAUDE.md 규칙	새 세션에서 파일을 읽었는지
문서 갱신 때만 절차 실행	전용 스킬	명시 호출로 원본과 생성 명령을 찾는지
실행 전 특정 쓰기 거부	PreToolUse Hook	도구가 거부되고 파일은 바뀌지 않는지
결과를 독립적으로 검증	필요한 도구를 가진 Subagent	검증 보고서가 있고 권한이 작업 범위 내인지
외부 시스템 데이터 조회	MCP 연결	필요한 서버에서 허가된 요청 하나가 가능한지

CLAUDE.md와 스킬은 모델에 지침을 줍니다. “generated를 수정하지 말라”는 문구만으로 쓰기가 차단되었다고 할 수 없습니다. Hook의 이벤트, matcher, 실제 거부 동작을 검사해야 합니다. Write를 막아도 Bash를 통한 쓰기까지 제한하지는 않습니다. 별도 컨텍스트를 가진 Subagent도 자동으로 read-only가 되지 않습니다. 기능 개요와 Hooks 참고 문서에 차이가 설명되어 있습니다.

같은 절차를 다섯 곳에 복사하지 말고 CLAUDE.md에는 짧은 규칙과 스킬 참조를 남기세요. 구체적인 예시는 CLAUDE.md 규칙, Stop Hook 완료 검사, MCP와 명령 선택을 참고할 수 있습니다. Stop Hook은 작업이 끝나는 시점을 확인하므로 쓰기 전 검사인 PreToolUse를 대체하지 않습니다.

간결한 진입점과 보조 리소스로 분리하기

1. YAML frontmatter 다듬기

description에는 목적과 분명한 트리거 조건을 적습니다. 다음 설정 예시는 Prisma 스키마 변경 시 마이그레이션을 검사하고 적용하는 용도를 설명합니다.

---
name: db-migrator
description: >-
  Prisma 데이터베이스 스키마 변경 시 마이그레이션을 검사하고 적용할 때 사용한다.
---

설명란에 긴 코드 예시를 넣지 말고 자세한 표와 예시는 references/로 옮기세요.

2. 반복 검사 로직을 스크립트에 두기

모델이 긴 자연어 지침에서 복잡한 파싱·검증 명령을 매번 만들게 하는 대신 스킬의 scripts/ 디렉터리에 shell 또는 Python 스크립트를 둡니다. SKILL.md에는 실행 경로와 판단 기준을 남깁니다.

<!-- SKILL.md 내부 -->
스키마 무결성을 검사하려면 다음을 실행한다:
```bash
python3 "${CLAUDE_SKILL_DIR}/scripts/validate_schema.py" --strict
```

스크립트 자체를 테스트하고 같은 입력으로 실행하면 재현성을 높일 수 있습니다. Token을 줄이기 위해 필수 보안 검사, 린터, 타입 검사를 끄지 마세요.

네 단계로 발견과 호출 검증하기

1. 네 가지 검사를 구분하기

test -f는 YAML 검사가 아닙니다. SKILL.md 존재 여부, 비어 있지 않은 description을 포함한 frontmatter의 YAML 파싱, 스킬 디렉터리를 기준으로 한 references/·examples/·scripts/ 경로, 안전한 입력에서 스크립트가 반환하는 종료 코드를 각각 확인합니다. python3로 실행하는 Python 파일에 실행 비트가 반드시 필요한 것은 아닙니다.

2. 표시 상태와 명시 호출 확인하기

새 세션에서 /skills를 열어 이름, 출처, 호출 모드를 확인합니다. 이어서 안전한 시험 작업으로 /db-migrator를 명시적으로 호출합니다. 발견 실패와 지침 자체의 오류를 분리하는 과정입니다.

3. 자동 트리거 시험하기

다른 새 세션에서 스킬 이름을 언급하지 않고 “데이터베이스 사용자 모델을 갱신하고 마이그레이션을 검사해 주세요”라고 요청합니다. 모델이 description으로 작업을 식별하고, db-migrator 본문을 로드한 뒤 준비된 검사 스크립트 실행을 제안하는지 확인합니다.

4. 목록과 시작 컨텍스트 측정하기

미사용 스킬은 앞서 설명한 /skill-doctor로 찾습니다. /doctor로 목록 비용과 큰 기여 항목을 확인하고 /context의 Skills 항목 크기를 기록합니다. 설명을 줄이거나 저빈도 스킬을 user-only로 바꾸는 등 한 번에 하나만 변경하고 새 세션에서 비교합니다.

Token뿐 아니라 필요한 요청에서는 올바른 스킬이 호출되고, 관련 없는 요청에서는 호출되지 않으며, 작업 검사도 통과하는지 확인하세요. always-on, auto-triggered, user-only, name-only, off를 구분하고, 보안·복구 스킬을 빈도만으로 삭제하지 않습니다.