AI 코딩

Claude Code Skills 설계: 컨텍스트 낭비 없이 필수 기능 유지하기

Claude Code skills 최적화 가이드: 상주 지침과 작업 트리거 기능 분리, frontmatter 트리거 튜닝 및 도구 탐색 검증 방법.

BetterToken

편집팀

2026년 8월 21일3 분 분량

Claude Code를 프로젝트에 맞게 구성하다 보면 코딩 스타일, 린터, 테스트 자동화 스크립트 등 커스텀 지침과 도구가 빠르게 늘어납니다. 모든 도구를 기본 지침으로 상주시킬 경우, 첫 번째 작업을 입력하기도 전에 세션의 기본 컨텍스트 용량이 크게 소모됩니다. 본 가이드에서는 skills를 목록화하고, 상주 규칙과 온디맨드 리소스를 분리하며, 모델이 필요한 시점에 도구를 정확히 인식하도록 검증하는 방법을 다룹니다.

Skills가 초기 세션 창에 미치는 영향

Claude Code에서 skills는 에이전트의 작업 역량을 확장하기 위한 구조화된 디렉터리와 Markdown 문서(주로 SKILL.md)입니다. 작업 세션이 시작될 때 에이전트는 사용 가능한 skills의 이름과 간단한 설명을 스캔하여 어떤 전문 워크플로를 호출할 수 있는지 파악합니다.

Skill이 차지하는 컨텍스트 비용은 크게 세 가지 영역으로 나뉩니다:

시스템 알림 (설명 및 trigger): SKILL.md의 frontmatter에 정의된 name과 description입니다. 에이전트가 사용자 입력을 적절한 도구로 연결할 수 있도록 항상 활성 메모리에 유지됩니다.
메인 지침 본문: 상세한 실행 단계, 규칙 및 코드 예시입니다. 해당 skill이 실제로 트리거될 때만 모델에 로드됩니다.
보조 스크립트 및 참조 자료: scripts/ 폴더의 실행 파일이나 references/의 문서로, 터미널 명령을 통해 확정적으로 실행됩니다.

흔히 발생하는 문제는 방대한 API 문서나 긴 가이드라인을 description 또는 최상위 CLAUDE.md에 그대로 포함시키는 것입니다. 이는 모든 대화 턴에 불필요한 토큰 부담을 유발합니다.

BetterToken과 같은 외부 API 라우팅 서비스를 이용할 경우, 대시보드(Dashboard)를 통해 호출별 input, output, cache tokens 사용량을 직관적으로 모니터링할 수 있습니다. 하지만 서버 측 모니터링은 전송된 트래픽을 측정할 뿐이며, 로컬 구성 파일 자체의 최적화를 대신하지는 않습니다. 상세 연결 설정 및 엔드포인트 정보는 BetterToken Docs에서 확인할 수 있습니다.

사용 빈도에 따른 Skills 정리

작업 환경을 최적화하기 위해 프로젝트와 사용자 전역 설정(~/.claude/skills/)에 등록된 모든 skills를 정리합니다.

실제 사용 빈도에 따라 다음과 같이 분류합니다:

빈도 분류	주요 작업 예시	권장 배치 위치
상시 활성 (Always-on)	기본 코드 스타일, 테스트 실행, git 관리 규칙	`CLAUDE.md`의 간결한 규칙 또는 기본 skill
작업 기반 트리거	DB 마이그레이션, OpenAPI 클라이언트 생성, 배포 체크리스트	명확한 `description`을 가진 전용 skill
저빈도 / 특수 작업	초기 보안 감사, 신규 인프라 프로비저닝	명시적 명령어로 실행하는 외부 스크립트

일반적인 원칙으로, 10~15회의 작업 세션 중 한 번 정도만 사용되는 기능이라면 상시 메모리에 둘 필요가 없습니다.

핵심 규칙과 온디맨드 리소스 분리

초기 토큰 소모를 줄이고 실행 신뢰성을 높이려면, 각 skill을 가벼운 진입점과 확정적 스크립트 구조로 설계해야 합니다.

1. YAML Frontmatter 최적화

description 필드에는 장황한 서술 대신 명확한 트리거 조건과 목적만 작성합니다:


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

헤더 안에 긴 코드 예시를 넣지 말고, 복잡한 테이블이나 스키마는 references/ 디렉터리로 분리합니다.

2. 확정적 스크립트로 로직 위임

자연어 지침을 통해 복잡한 명령어를 매번 생성하도록 요구하는 대신, 검증 로직을 실행 파일로 패키징합니다:


<!-- SKILL.md 내부 -->
스키마 무결성을 검증하려면 다음 명령을 실행합니다:
```bash
python3 scripts/validate_schema.py --strict



이렇게 하면 `SKILL.md`의 본문 길이를 크게 줄이면서도 일관된 결과를 얻을 수 있습니다. 토큰을 절약하기 위해 필수 린터나 타입 검사를 비활성화해서는 안 되며, 확정적 검사는 철저히 유지되어야 합니다.

도구 탐색 및 호출 검증

Skills 구조를 개편한 후, 에이전트가 필요한 시점에 도구를 정상적으로 탐색하고 실행하는지 확인합니다.

1단계: 문법 및 파일 경로 확인

모든 SKILL.md 파일의 YAML 문법이 유효하고 스크립트 경로가 올바른지 확인합니다:


# skill 파일 및 스크립트 실행 권한 확인
test -f .claude/skills/db-migrator/SKILL.md && echo "SKILL.md OK"
test -x .claude/skills/db-migrator/scripts/validate_schema.py && echo "Script executable OK"

2단계: 신규 세션에서 트리거 테스트

새 세션을 시작하고, skill 이름을 직접 언급하지 않고 작업 내용을 입력합니다:

"Prisma 스키마의 User 모델을 수정하고 마이그레이션을 확인해 주세요."

에이전트가 다음과 같이 동작하는지 확인합니다:

db-migrator의 설명을 바탕으로 작업을 식별합니다.
SKILL.md 본문 지침을 로드합니다.
준비된 검증 스크립트 실행을 제안합니다.

3단계: 초기 컨텍스트 상태 평가

정리 후 세션 진행 상황을 관찰합니다. 이 작업의 목표는 불필요한 노이즈를 제거하여 대화 히스토리 공간을 확보하는 것이며, 단순 수치 절감에 얽매일 필요는 없습니다. 현재 진행 중인 마일스톤에 필요한 skills만 활성화하여 사용하세요.

LLM 워크플로를 최적화할 준비가 되셨나요?

하나의 API로 모델을 연결하고 키와 AI 비용을 관리하세요.