특정 모델에 종속되지 않고, 여러 프론티어 LLM(Claude, GPT, Gemini 등)과 AI 에이전트 프레임워크(함수/도구 정의, 커스텀 GPT, LangChain·LlamaIndex 류, RAG 파이프라인 등)에서 공통으로 통용되는 스킬/지시문 구조 설계 원칙

0. 용어 정리

이름이 무엇이든, "모델 컨텍스트에 항상 올라가는 글"과 "필요할 때만 끌어오는 자료"를 어떻게 나눌 것인가가 핵심 질문입니다.

이 문서의 표현 각 생태계에서의 대응
스킬 본문 / 매니페스트 SKILL.md, 시스템 프롬프트, 도구 설명(description), 커스텀 인스트럭션
레퍼런스 자료 첨부 문서, 지식 베이스, RAG 문서, reference.md
실행 자산 함수/툴, 코드 인터프리터 스크립트, 외부 API 호출

1. 간결한 SKILL.md 작성? 왜 본문 길이가 중요할까

모든 LLM은 유한한 컨텍스트 윈도우를 가집니다. 항상 로드되는 지시문이 길수록:

문제 설명
토큰 예산 잠식 지시문이 차지하는 만큼 실제 작업(입력·추론·출력)에 쓸 공간이 줄어듦
비용·지연(latency) 증가 매 호출마다 그 토큰을 다시 처리 → 호출당 비용과 응답 시간 상승
신호 희석 (lost in the middle) 정작 중요한 지시가 장황한 설명에 묻혀 모델이 핵심을 놓침

긴 컨텍스트를 지원하는 모델이라도 "넣을 수 있다 ≠ 넣어야 한다" 입니다. 본문은 매 호출마다 비용을 치르는 고정 지출입니다.

2. 핵심 원리: 점진적 공개 (Progressive Disclosure)

모든 걸 본문에 넣지 말고, 필요할 때 가져갈 수 있게 분리해 둔다.

SKILL.md (매니페스트/시스템 프롬프트) [항상 로드]  ← 짧게. 핵심 절차 + "자세한 건 → 참조"
  ├── [필요시 로드] reference 문서   ← 모델이 필요하다 판단할 때만 조회
  ├── [필요시 로드] examples 모음     ← 마찬가지로 필요시에만
  └── [필요시 실행] 도구 / 스크립트   ← 본문에 코드를 넣지 말고 호출 가능한 자산으로

이 패턴은 도구마다 메커니즘이 다를 뿐, 발상은 동일합니다.

비유: 매니페스트는 책 전체가 아니라 목차 + 요약. 상세 내용은 필요한 페이지만 펼쳐 보는 구조여야 합니다.