SKILL.md는 생각보다 3배 더 비쌀 수 있습니다 - 내용보다 아키텍처가 중요합니다
Your SKILL.md is likely 3x more expensive than it needs to be - architecture matters more than the content
핵심 요약
SKILL.md를 모놀리식 대신 Spine-and-references 구조로 리팩토링하여 컨텍스트 비용을 3배 절감하는 팁을 공유합니다.
- 구조 최적화 — 모놀리식 파일 대신 Spine-and-references 구조를 사용하여 불필요한 토큰 로드를 방지함.
- 로딩 레벨 구분 — Frontmatter, Body, Reference를 분리하여 필요한 시점에만 데이터가 로드되도록 설계함.
- 모델 대응 전략 — 모델마다 지시사항 해석이 다르므로 골든 테스트 셋을 통해 성능 저하를 방지함.
- 컨텍스트 효율성 — 불필요한 토큰 사용을 줄여 더 긴 세션 유지와 복잡한 작업 수행이 가능해짐.
대부분의 사람들은 SKILL.md를 에이전트가 읽는 긴 프롬프트처럼 취급합니다. 사실 이건 로더 사양(loader specification)입니다. 이 차이를 이해하면 지시사항을 하나도 바꾸지 않고도 컨텍스트 비용을 3배 절감할 수 있습니다.
로딩 레벨은 세 가지가 있습니다. Frontmatter(이름과 설명)는 스킬의 관련 여부와 상관없이 매 턴마다 항상 컨텍스트에 포함됩니다. 설치된 스킬당 약 100토큰 정도입니다. Body는 에이전트가 스킬을 호출하기로 결정했을 때만 로드됩니다. 참조(References)와 스크립트는 Body가 명시적으로 가리킬 때만 로드됩니다.
대부분의 스킬 파일은 모든 것을 Body에 때려 넣습니다. 1,200줄짜리 모놀리식 파일은 트리거가 발생할 때마다 전체를 로드하게 만듭니다. 에이전트가 아무 작업도 하기 전에 컨텍스트 윈도우의 20%를 잡아먹는 셈이죠. 이를 180줄짜리 Spine과 3개의 참조 파일로 리팩토링하면, 에이전트는 현재 작업에 필요한 파일만 로드하게 됩니다. 컨텍스트 비용은 7%로 줄어듭니다. 같은 지시사항, 같은 결과물, 3배 더 저렴해진 비용입니다.
절감 효과는 복리로 작용합니다. 20% 대신 7%의 비용으로 스킬을 사용하면, 같은 예산으로 3개를 설치할 수 있고, 압축(compaction)이 발생하기 전까지 더 긴 세션을 실행할 수 있으며, 장기적인 작업에서 컨텍스트 부족 현상을 덜 겪게 됩니다.
분명하지 않은 함정: 모델 업그레이드는 공짜가 아닙니다. Sonnet 3.5에서 튜닝된 스킬이 Opus에서는 성능이 저하될 수 있습니다. 버그가 아니라, 더 뛰어난 모델은 지시사항을 문자 그대로 따르기보다 해석하기 때문입니다. "짧은 문장"이라는 지시가 Sonnet에서는 적절히 적용되었지만, Opus에서는 읽기 힘든 뚝뚝 끊기는 문장을 만드는 강한 제약 조건이 되어버렸습니다. 해결책은 모델이 업데이트될 때마다 다시 실행할 수 있는 작은 골든 테스트 셋을 갖추는 것입니다.
현재 여러분의 SKILL.md 구조는 어떤가요? 모놀리식인가요, 아니면 Spine-and-references인가요?
