스킬을 만들다 보면 늘 같은 지점에서 막힌다. 케이스를 추가할수록 SKILL.md가 부풀고, 부풀수록 에이전트가 둔해진다. 그래서 대부분 “얼마나 담을까”를 고민한다. 잘못된 질문이다. 진짜 변수는 얼마나 담느냐가 아니라 언제 읽히느냐다.
근거
diagram-design은 참조 파일이 34개다. 그런데 상시 컨텍스트에 있는 건 SKILL.md 하나뿐이고, 그 파일이 하는 일은 내용을 담는 것이 아니라 어디를 볼지 알려주는 것이다. 타입 선택 가이드와 체크리스트만 들고 있고, 실제 문법은 references/type-*.md에 흩어져 있다가 해당 타입이 선택될 때만 딸려 들어온다.
| 요청 | 로드되는 것 |
|---|---|
| ”플로우차트 만들어줘” | SKILL.md + type-flowchart.md |
| ”손그림 버전으로” | SKILL.md + primitive-sketchy.md |
타입이 아무리 많아져도 Claude는 필요한 하나만 읽는다. 내일 새 타입을 추가해도 나머지는 아무것도 바뀌지 않는다.
이 구조의 진짜 값은 성능이 아니라 확장 비용이 상수라는 데 있다. type-<name>.md를 하나 떨궈 선택 가이드에 한 줄 연결하면 끝이고, 기존 27종은 영향받지 않는다. 반대로 SKILL.md에 모든 케이스를 적어둔 스킬은 항목을 하나 추가할 때마다 이미 잘 되던 모든 케이스가 조금씩 나빠진다 — 회귀가 항상 전역이다.
나도 .claude/skills/ 아래 스킬들을 이 기준으로 다시 볼 필요가 있다. 인덱스와 내용이 한 파일에 섞여 있다면, 그건 아직 확장할 준비가 안 된 스킬이다.
연결된 생각
- 20260811-editorial-diagram-skill-system — 이 로딩 전략을 포함한 전체 설계
- 20260515-context-surpasses-intelligence-as-scarce-resource — 컨텍스트가 희소 자원이라는 전제가 이 설계의 뿌리
- 20260531-ai-agent-skill-packaging-prompt — 스킬 패키징 패턴 일반론