Claude 에이전트 스킬 기반 아키텍처를 설계할 때 가장 흔한 실수는 ‘일단 만들고 나중에 구조를 잡겠다’는 접근이다. 결과는 항상 같다 — 스킬이 5개만 넘어도 충돌이 생기고, 어떤 스킬이 언제 호출되는지 추적이 안 된다. 설계 순서가 틀린 탓이다.
스킬 기반 아키텍처(Skill-Based Architecture)란 에이전트가 수행하는 기능을 독립적인 ‘스킬’ 단위로 분리하고, 오케스트레이터가 상황에 따라 적절한 스킬을 호출하는 구조다. Claude 에이전트에 이 구조를 적용하면 유지보수가 쉬워지고, 스킬을 재사용하거나 교체하기도 수월해진다.
아래 5단계 설계 흐름을 따르면 구조 없이 만든 에이전트와 결과가 달라진다.
스킬 기반 아키텍처가 필요한 이유
단일 프롬프트 에이전트의 한계
Claude 에이전트를 처음 만들 때는 하나의 긴 시스템 프롬프트에 모든 동작을 넣는 방식을 선택하기 쉽다.
문제는 규모가 커질수록 나타난다.
- 프롬프트가 길어질수록 Claude가 어떤 지시를 우선해야 하는지 혼동하는 경우가 생긴다
- 기능 하나를 수정하면 다른 동작에 영향이 생긴다
- 같은 기능을 다른 에이전트에 재사용하려면 전체 프롬프트를 복사해야 한다
- 어떤 스텝에서 오류가 발생했는지 추적이 어렵다
스킬 기반 아키텍처는 이 문제를 구조적으로 해결한다.
스킬 단위 분리의 핵심 원칙
스킬 하나는 하나의 목적만 수행해야 한다.
‘웹 검색 후 요약’은 하나의 스킬이 아니다 — ‘웹 검색’과 ‘요약’을 분리해야 한다. 각각을 독립적으로 테스트하고 교체할 수 있어야 진짜 스킬 기반 구조다.
Claude 에이전트 스킬 기반 아키텍처 설계 5단계
1단계: 에이전트 목적 정의 및 태스크 목록 작성
설계는 코드가 아니라 문서로 시작한다.
에이전트가 수행해야 할 태스크를 동사 기준으로 나열한다. 예를 들어 ‘고객 지원 에이전트’라면 다음처럼 작성할 수 있다.
- 질문 의도 분류하기
- FAQ 데이터베이스에서 답변 검색하기
- 담당자 연결 필요 여부 판단하기
- 답변 초안 생성하기
- 답변 톤 검토 및 조정하기
이 목록이 스킬 후보 목록이 된다.
Tip: 태스크 목록은 10개 이내로 제한한다. 10개가 넘으면 에이전트를 분리할 신호다.
2단계: 스킬 경계 설정 및 의존성 파악
1단계 목록에서 독립 실행 가능한 스킬과 다른 스킬의 출력에 의존하는 스킬을 구분한다.
| 스킬명 | 독립 실행 | 의존 대상 |
|---|---|---|
| 질문 의도 분류 | 가능 | 없음 |
| FAQ 검색 | 가능 | 없음 |
| 답변 초안 생성 | 불가 | 질문 의도 분류 + FAQ 검색 결과 |
| 톤 조정 | 불가 | 답변 초안 |
| 담당자 연결 판단 | 불가 | 질문 의도 분류 결과 |
의존 관계가 복잡하게 얽혀 있다면 스킬 경계가 잘못 설정된 것이다.
Tip: 순환 의존(A → B → A)이 생기면 두 스킬을 하나로 합치거나 중간 레이어를 추가해야 한다.
3단계: 오케스트레이터 설계
오케스트레이터(Orchestrator)는 입력을 받아 어떤 스킬을 어떤 순서로 호출할지 결정하는 제어 레이어다.
Claude 에이전트에서 오케스트레이터는 보통 시스템 프롬프트 또는 라우팅 로직으로 구현된다.
오케스트레이터가 결정해야 할 항목은 다음과 같다.
- 어떤 조건에서 어떤 스킬을 호출하는가
- 스킬 실행 순서는 순차인가, 병렬인가
- 스킬 실패 시 어떻게 처리하는가 (재시도, 폴백, 중단)
오케스트레이터 자체에 도메인 로직을 넣지 않는 것이 원칙이다.
판단은 오케스트레이터가 하되, 실행은 각 스킬에 위임해야 구조가 무너지지 않는다.
Tip: 오케스트레이터 프롬프트에 ‘스킬 이름’을 명시적으로 정의해두면 Claude가 더 일관된 라우팅 결정을 내린다.
4단계: 스킬별 프롬프트 작성 및 입출력 스펙 정의
각 스킬은 입력 형식, 출력 형식, 실패 조건을 명시한 스펙 문서를 갖춰야 한다.
스킬 스펙 예시 — ‘질문 의도 분류’ 스킬:
- 입력: 사용자 메시지 (자유 텍스트)
- 출력: 카테고리 레이블 (FAQ / 불만 / 연결 요청 / 기타)
- 실패 조건: 입력이 비어있거나 50자 미만일 때
- 출력 형식: JSON {“intent”: “…”}
출력 형식을 JSON으로 고정하면 다음 스킬이 파싱 오류 없이 결과를 받을 수 있다.
Tip: Claude에게 출력 형식을 지시할 때 “반드시 JSON으로만 응답하세요. 다른 텍스트 포함 금지”처럼 제약을 명시하는 것이 막연히 “JSON 형식으로 출력하세요”보다 일관성이 높다는 것이 커뮤니티에서 자주 공유되는 패턴이다.
5단계: 테스트 케이스 설계 및 스킬 단위 검증
전체 에이전트를 한 번에 테스트하면 어느 스킬에서 문제가 생겼는지 알 수 없다.
스킬 단위 검증을 먼저 완료한 뒤 통합 테스트를 진행하는 순서가 필요하다.
스킬 단위 테스트 체크리스트:
- 정상 입력 → 예상 출력이 나오는가
- 경계 입력 (최소값, 최대값) → 출력 형식이 유지되는가
- 비정상 입력 → 실패 조건이 올바르게 처리되는가
- 출력이 다음 스킬의 입력 스펙을 충족하는가
통합 테스트는 스킬 단위 검증이 모두 완료된 후에 진행한다.
Tip: 테스트 입력은 실제 사용자 메시지 패턴에서 수집한 것이 가장 유효하다. 임의로 만든 테스트 케이스는 엣지 케이스를 놓치는 경우가 많다.
설계 시 자주 발생하는 오류 패턴
스킬이 너무 크게 설계된 경우
‘검색 + 요약 + 출력’을 하나의 스킬로 묶으면 재사용이 불가능해진다.
스킬 하나가 Claude에게 보내는 프롬프트가 500토큰을 초과한다면 분리를 검토할 신호다.
오케스트레이터에 도메인 로직이 섞인 경우
오케스트레이터가 ‘답변 톤을 공손하게 조정해라’는 지시를 직접 내리면 안 된다. 그 역할은 ‘톤 조정’ 스킬이 담당해야 한다.
오케스트레이터는 언제 어떤 스킬을 호출할지만 결정한다.
스킬 간 상태 공유 문제
스킬 A의 결과를 전역 변수처럼 관리하면 병렬 실행 시 충돌이 생긴다.
스킬 간 데이터는 오케스트레이터를 통해 명시적으로 전달하는 구조를 유지해야 한다.
Claude 에이전트 스킬 기반 아키텍처 실제 적용 시 참고할 자료
Anthropic 공식 문서의 Building Agents with Claude 페이지에서 오케스트레이터 패턴과 툴 사용 구조에 대한 공식 가이드를 확인할 수 있다.
스킬 기반 아키텍처는 Anthropic이 공식적으로 권장하는 멀티스텝 에이전트 구조와 일치한다. 툴 호출(tool_use)을 각 스킬에 매핑하면 Claude의 네이티브 기능과 자연스럽게 통합된다.
자주 묻는 질문
Q. 스킬 수가 몇 개 이상이면 멀티 에이전트 구조로 전환해야 하나요?
명확한 기준은 없지만, 하나의 오케스트레이터가 관리하는 스킬이 10개를 초과하거나 스킬 간 의존 관계가 3단계 이상 중첩되면 서브 에이전트 분리를 검토하는 것이 일반적으로 알려진 가이드라인입니다.
Q. 스킬 프롬프트와 오케스트레이터 프롬프트를 같은 파일에 관리해도 되나요?
기능상 가능하지만 유지보수 측면에서 분리를 권장합니다. 스킬 프롬프트를 별도 파일로 관리하면 스킬 하나를 수정할 때 다른 스킬에 영향을 주지 않고 독립적으로 버전을 관리할 수 있습니다.
Q. Claude API를 쓰지 않고 n8n 같은 워크플로우 도구에서도 이 설계를 적용할 수 있나요?
적용 가능합니다. n8n에서는 각 노드를 스킬로, 워크플로우 분기 로직을 오케스트레이터로 대응시키면 됩니다. 입출력 스펙을 JSON으로 정의하는 원칙은 도구와 무관하게 동일하게 적용됩니다.
다음 단계로 오케스트레이터 프롬프트 작성 패턴을 시도해보세요. 스킬 목록과 호출 조건을 구조화된 형식으로 프롬프트에 명시하는 것이 Claude 에이전트 스킬 기반 아키텍처를 안정적으로 운영하는 첫걸음입니다.
썸네일: Unsplash