제1회·제2회에서 기존의 .NET 자산을 Skill화하고, 제5회에서 업무 플로우 Skill을 추가해 나가면 Skill의 수가 계속해서 늘어납니다.

저희 시스템에서는 최종적으로 API 레벨 Skill이 약 6,400건, 업무 플로우 Skill이 약 170건이 되었습니다.

그리고 어느 날 이런 일이 일어났습니다.

세션을 열 때마다 응답이 느려지더니, 갑자기 컨텍스트가 압축(autocompact)됩니다.

조사해 보니, Skill의 정의 파일만으로 컨텍스트 윈도우(Context Window)의 144%를 소비하고 있었습니다.

Claude Code는 .claude/agents/ 하위 디렉토리를 재귀적으로 스캔하여, name과 description을 가진 YAML frontmatter를 포함한 Markdown 파일을 모두 Custom agent(Skill)로 등록합니다.

---
name: select_order_list
description: 발주 목록을 가져온다
...

등록된 Skill의 name + description은 매 세션의 컨텍스트에 자동으로 로드됩니다.

Skill이 10개라면 문제없습니다. 하지만 6,400개가 되면:

6,400건 × 평균 45 토큰 ≈ 288,000 토큰
컨텍스트 윈도우(200k)의 144%

Skill의 정의만으로 컨텍스트가 넘쳐버립니다.

문제의 근본 원인은 모든 Skill을 동일한 방법으로 '등록'하고 있었다는 점입니다.

두 종류의 Skill을 정리해 보면, 필요한 '등록' 방식이 달랐습니다.

"전부 등록한다"에서 "필요한 것만 등록한다"로 전환하는 방침을 세웠습니다.

API 레벨 Skill은 업무 플로우 Skill 내부에서 호출될 뿐입니다. AI가 자연어 요청에 직접 매칭시킬 필요는 없습니다.

따라서 frontmatter (---name/description---)를 제거함으로써 컨텍스트 로드 대상에서 제외합니다.

# 변경 전 (등록됨)
---
name: select_order_list
...

Skill로서의 정보는 본문에 남겨둔 채, frontmatter만 제거합니다. 발견 방식은 AI가 SUB_AGENT.md의 Skill 목록표를 온디맨드(On-demand)로 읽는 형태로 전환합니다.

# SUB_AGENT.md (업무 모듈 정의)
## Skill 목록
| Skill | 역할 |
...

AI는 "이 업무 모듈에는 어떤 Skill이 있는가"를 필요할 때만 읽으러 가는 동작을 하게 됩니다.

일괄 제거는 Python 스크립트(멱등성 보장)로 자동화했습니다. 실행 후:

제거 전: Custom agents 288,500 토큰 (144%)
제거 후: Custom agents 4,200 토큰 (2%)

업무 플로우 Skill은 frontmatter를 남겨두어야 합니다 (직접 매칭시키고 싶기 때문). 하지만 여기서도 170건 전부를 직접 등록하면 다시 비대해집니다.

그래서 Tier(우선순위)로 나누었습니다.

이용 빈도가 높고, "누구나 직접 요청할 것"이 명백한 것.

예시:
- 회의 설정 플로우 ← "회의를 설정해줘"라고 직접 요청받음
- 비품 구매 플로우 ← "비품을 사고 싶어"라고 직접 요청받음

이것들은 frontmatter를 가진 채로 직접 등록합니다.

업무 도메인(경비·재고·인사 등)마다 **하나의 얇은 라우터(Router)**를 배치하여, 하위의 업무 플로우 Skill은 라우터를 경유해 2홉(Hop) 만에 발견되도록 합니다.

요청: "발주 잔량을 확인해줘"
↓
라우터 (구매 도메인)가 매칭
...

라우터는 각 도메인당 1개씩만 등록됩니다.

# 구매 라우터 (frontmatter 있음 · 등록됨 · 본문에 목록 포함)
---
name: 구매
...

라우터의 description만 컨텍스트에 포함되며, 하위 Skill의 상세 내용은 라우터가 호출되었을 때 비로소 읽힙니다.

업무 플로우 Skill 170건 직접 등록 → 7만 토큰
Tier1(10건) 직접 + Tier2(160건) 라우터 경유 → 5,000토큰

두 가지 대책을 합친 결과:

대책 전
API Skill frontmatter 288,500 토큰
업무 플로우 Skill frontmatter 7,000 토큰
...

autocompact가 멈추고, 세션이 안정되었습니다.

Skill이 늘어날 때마다 수동으로 확인하는 것은 현실적이지 않기 때문에, 컨텍스트 사용량을 모니터링하는 스크립트를 준비했습니다.

python check_context_size.py
Custom agents: 4,980 tokens (2.5%) ─ OK
임계값 50,000 tokens 미만입니다

임계값을 초과하면 경고가 발생하는 구조로 만들어, 플로우 공장이 Skill을 양산하더라도 인지할 수 있도록 하고 있습니다.

이번 경험을 통해 얻은 설계 원칙입니다.

1. Skill은 「등록하는 것」과 「발견하는 것」을 분리한다

• 등록 (frontmatter 있음): 사용자의 요청에 직접 매칭시키고 싶은 것
• 발견 (frontmatter 없음): 내부에서 호출되는 것, SUB_AGENT.md를 통해 읽음

2. 도메인 라우터(Domain Router)로 상한선을 둔다

업무 플로우 Skill이 아무리 늘어나도, 라우터는 도메인 수만큼만 존재합니다. 도메인이 늘어나는 속도는 Skill의 증가 속도보다 완만합니다.

3. 자동화와 모니터링을 세트로 구성한다

Skill 생성을 자동화한다면, 컨텍스트 사이즈 모니터링도 자동화해야 합니다. "모르는 사이에 비대해지는 것"을 방지합니다.

• ✅ API 레벨 Skill(대량)은 frontmatter를 갖지 않음 ─ SUB_AGENT.md를 통해 발견
• ✅ 업무 플로우 Skill은 도메인 라우터로 계층화 ─ 라우터 수로 상한선 유지
• ✅ 모니터링 스크립트로 지속적으로 확인

"Skill을 늘릴수록 AI가 똑똑해진다"는 맞지만, 컨텍스트 설계를 동시에 고려하지 않으면 늘릴수록 느려지는 역효과가 발생합니다.

Skill 수와 컨텍스트 사용량을 분리하는 설계가 장기 운영에서는 필수적이라고 느낍니다.