에이전트 스킬 라이브러리 8계층 아키텍처: 프롬프트 비대화 방지와 절차 분리 방법론

2026년 11월 3일, X 사용자 @0xShoopy는 비대해진 지침 컨텍스트를 줄이기 위한 8계층 에이전트 스킬 라이브러리 구축 가이드를 공유했습니다.

이미지 출처: @0xShoopy

이번 가이드는 X 사용자 @0xShoopy가 공유한 10페이지 분량의 방법론 문서로, 핵심 공식인 Skill = Trigger + Procedure + Resources + Checks를 기반으로 에이전트가 상황에 맞는 절차를 선택하도록 설계하는 세부 계층을 다룹니다.

팩트와 절차의 분리 및 기본 4개 계층

해당 가이드가 제시하는 제1원칙은 모든 작업에 공통 적용되는 프로젝트 정적 팩트와 특정 작업에만 필요한 동적 절차의 엄격한 분리입니다.

기존 방식처럼 수백 줄의 규칙을 단일 설정 파일에 몰아넣는 대신, 상시 참조할 사실은 CLAUDE.md에 유지하고 실행 절차는 skills/ 하위 모듈로 격리합니다. 이를 통해 스킬 호출 전까지는 디스크립션 수준(약 100토큰)만 노출하여 기본 컨텍스트 부하를 줄입니다.

• Layer 1 (Library): 상시 유효한 정보만 CLAUDE.md에 두고, 개별 작업 수행법은 스킬로 격리합니다.
• Layer 2 (Trigger): 스킬 설명문 자체가 라우팅 인터페이스로 동작합니다. 기대 출력, 입력 요건, 3개의 대표 트리거 문구, 그리고 라우터 혼선을 방지하기 위한 1개의 예외 조건("not for X, use Y instead")을 명시합니다.
• Layer 3 (Procedure): 번호가 매겨진 명시적 단계로 구성하며, 항상 상태 관찰인 'Look'으로 시작하고 검증 단계인 'Check'로 종료합니다.
• Layer 4 (Resources): 상세 참조 문서와 매뉴얼은 references/ 경로에 배치하며, 서술형 형용사 나열 대신 구체적인 실제 예시 1개를 제공하는 구성을 채택합니다.

결정론적 코드 실행과 가드레일(Layer 5~8)

후반 4개 계층은 에이전트의 계산 오류 방지와 보안, 누적 학습을 규정합니다.

• Layer 5 (Scripts): 유일한 정답이 존재하는 수치 연산, 파일 배치 변환 등의 작업은 모델의 추론에 의존하지 않고 결정론적 실행 스크립트로 분리합니다. 후속 답글에서 @0xShoopy는 입력 행 수와 출력 행 수가 일치하는지 확인하는 단언(assert)을 하나 추가하라고 권장했습니다.
• Layer 6 (Checks): 작업 종료를 선언하기 전에 검증해야 하는 5개의 Yes/No 체크리스트를 포함하며, 체크박스가 모두 충족되지 않은 상태에서 완료 처리를 금지합니다.
• Layer 7 (Guard): 외부 텍스트(이메일, 웹 문서, PDF 등)를 읽을 때 이를 지시문이 아닌 순수 데이터로만 취급하도록 격리 규칙을 적용합니다. 단독 실행 권한, 사전 확인 필요 항목, 절대 금지 행동을 명시적으로 구분합니다.
• Layer 8 (Learn): 사용자의 지적이나 교정(correction) 피드백이 발생하면 일회성 프롬프트로 소모하지 않고, 해당 실패 원인을 분석하여 영구적인 체크리스트 항목으로 스킬에 누적합니다.

컨텍스트 최적화 효과와 고려 사항

@0xShoopy의 게시물에 따르면, 비교 대상인 단일 파일 구성에서 25개 절차는 요청당 약 36K 토큰이 들지만 모듈형 스킬 라이브러리 구성에서는 약 3.9K 토큰이 듭니다.

이는 @0xShoopy가 보고한 수치이며, 제공된 근거만으로 독립 검증되지는 않았습니다. @0xShoopy는 후속 답글에서 스킬이 겹치면 라우터가 두 스킬 사이를 오갈 수 있으며, 명시적인 "not for X, use Y instead" 문구 하나로 보통 해결할 수 있다고 설명했습니다.

출처

• @0xShoopy X 게시물: 에이전트 스킬 라이브러리 8계층 가이드 안내
• @0xShoopy가 링크한 PDF 가이드: 10-Page Agent Skill Library Guide (Google Drive)