소개
이 글에서는 Claude의 시각화 기능을 활용해 엔트로픽이 만든 skill-creator , 커뮤니티 스킬인 multi-agent-patterns의 구조와 패턴 분석내용을 공유합니다.
진행 방법
주제가 정해지면 기존의 신뢰도 높은 스킬을 커스텀해 자동화해보면 어떨까~ 하는 생각으로, 스킬을 조사했습니다. Agentic 시스템과 관련된 스킬을 크게 두 가지가 어떻게 만들어져 있는지 그 속을 보고 싶어 분석했습니다.
시스템 구성요소를 직접 만드는 skill
Claude 에 기본적으로 탑재된 mcp-builder와 skill-creator 중 skill-creator의 구조를 살펴봤습니다.시스템을 설계하는 skill
Claude가 관련성으로 조사 추천한 스킬인 multi-agent patterns 를 살펴봤습니다.
1. 앤트로픽의 skill-creator 구조 시각화
1)SKILL.md 파일 시각화
1단계에서 의도와 트리거 조건을 먼저 명확히 ,
2단계에서 엣지 케이스와 성공 기준을 조사한 뒤,
3단계에 SKILL.md를 작성합니다.
4단계의 병렬 평가 루프에서는 with-skill과 baseline(without_skill)을 동시에 실행해 비교,
어서션(Assertions, 스킬이 제대로 동작했는지 확인하는 체크리스트) 초안 작성,
— 객관적으로 검증 가능한 항목만 평가하고, 주관적인 스킬은 생략합니다.
사용자가 정성·정량 결과를 직접 검토한 피드백을 다음 iteration에 반영합니다.
이 루프로 스킬 품질이 반복적으로 개선될 수 있는 구조입니다.
5단계의 Description Optimization 는
"언제 이 스킬을 쓸 것인가(should-trigger)"와
"언제 쓰지 말아야 하는가(should-not-trigger)"를
각각 20개씩 생성해 자동으로 최적의 트리거 설명을 찾아냅니다.
description이 곧 스킬의 호출 정확도를 결정하므로 이 단계가 실제 사용성에 가장 큰 영향을 미칠거 같습니다.
마지막으로 Claude.ai 와 Claude Code의 동작 차이입니다.
서브에이전트와 브라우저 뷰어 기능은 Claude Code 환경에서만 전체 플로우가 가능합니다.
즉, 이 스킬을 제대로 활용하려면 Claude Code 환경이 필요합니다.
2) 전체 구조 시각화
폴더 구조 / 워크플로우 / Progressive Disclosure(점진적 로드),
이 3가지 뷰를 버튼으로 전환하며 내용을 확인할 수 있습니다.
이미지는 컨텍스트를 관리하는 skill의 핵심 원리로 중요한 Progressive Disclosure(점진적 로드)만 첨부했습니다.
스킬의 데이터를 3개의 층으로 나눠 보여줍니다.
Layer 1(메타데이터, ~100단어)은 Claude가 항상 컨텍스트에 올려두는 정보입니다. 스킬 이름과 description만으로 "이 스킬을 언제 쓸지"를 판단하기 때문에, 이 레이어가 스킬의 호출 정확도를 좌우합니다.
Layer 2(SKILL.md 본문, 500줄 이하)는 스킬이 실제로 실행될 때 비로소 로드되는 상세 지침입니다.
Layer 3(번들 리소스)는 필요할 때만 on-demand로 로드되는 스크립트, 참조 문서, 예제 파일로, 로드 없이 실행 가능한 scripts와 대량의 reference 파일을 분리해 놓습니다.
이 구조이 핵심원칙은 "항상 올려두는 것은 최소화하고, 필요할 때만 불러온다" 입니다. 컨텍스트 창은 유한한 자원이기 때문에 이런 설계 없이는 스킬이 많아질수록 품질이 저하됩니다.
3) 시각화 관점에서 claude code 터미널과 비교
처음엔 터미널에서만 구조를 봤었습니다. 시각화로 볼때는 claude.ai 가 월등한데 claude code 는 간결하게 내용이 더 잘 들어오는 이점이 있습니다.
핵심 설계 원칙만 살펴보면
첫째, Progressive Disclosure(점진적 공개):
"항상 컨텍스트에 있는 메타데이터
→ 스킬 트리거 시 로드되는 SKILL.md
→ 필요할 때만 로드되는 번들 리소스" 의 흐름이 설계 철학입니다.
둘째, Generalize from Feedback:
몇 개 예제에서만 동작하는 스킬은 쓸모없으며,
과적합(overfitting)을 피하기 위해 ALWAYS/NEVER 대신
"why"를 설명하고 효과 없는 부분을 제거하는 Lean prompt를 지향합니다.
특정 상황에서만 작동하는 스킬이 아니라 일반화된 스킬을 만들어야 한다는 원칙입니다.
셋째, Bundle Repeated Work:
여러 테스트에서 반복적으로 사용하는 스크립트는 번들에 포함시키고,
scripts/ 폴더에 넣어 재사용하라는 원칙입니다.
한 번 잘 만든 도구를 계속 재활용하는 설계 철학입니다.
주요 명령어 모음을 보면 skill-creator의 핵심 가치가 자동화된 루프에 있음을 알 수 있습니다.
벤치마크 집계 → Eval 뷰어 실행 → Description 최적화 → 스킬 패키징의 4단계가
명령어 한 줄로 실행 가능하며, run_loop.py는 피드백 → 개선 → 재실행을 완전 자동화합니다.
2. 커뮤니티 스킬 multi-agent-patterns 패턴 시각화
외부 skill 를 claude.ai 등록(설정-기능-사용자지정에 zip파일 업로드)한 건 처음이었는데 채팅을 시작하면 바로 먼저 말을 걸어 물어봐서 놀랬습니다. 바로 만들어 볼 수 있는 것을 제안합니다. 다양한 스킬을 써보기에 최적이겠어요.
1) 스킬 구조 패턴
보자마자 어렵습니다. 하지만 각 요소를 클릭하면 더 자세히 설명해줍니다.
패턴은 세 가지입니다.
Supervisor는 팀장이 팀원들에게 일을 나눠주는 구조,
Swarm은 팀원들이 서로 자유롭게 일을 넘기는 구조,
Hierarchical은 전략팀 → 기획팀 → 실행팀처럼 층층이 나뉘는 구조입니다.
마지막 8가지 함정 부분은 "이렇게 하면 실패한다"는 경고 목록이었습니다.
토큰 비용이 최대 15배까지 늘어날 수 있다는 점,
에이전트가 많을수록 서로의 오류가 연쇄적으로 전파된다는 점,
그리고 에이전트를 너무 잘게 쪼갤수록 오히려 성능이 떨어진다는 점입니다.
2) 실전 시나리오별 최적의 에이전트 구성 사례
시나리오마다 어떤 에이전트 구조가 적합한지 구체적인 사례로 보여줍니다. 어떤 것은 싱글 에이전트로 적당하고 어떤 것은 멀티에이전트를 사용한다고 알려줍니다.
스킬 활용한 사례탐구에 아주 유용한 안내였습니다. 단순히 패턴을 나열하는 게 아니라, "이 상황에선 이 구조"라는 식으로 알려주네요.
이렇게 구체적으로 보여준다고?!
막막했는데 덕분에 자동화 설계시 구조도 어느정도는 감을 잡고 시작할 수 있겠습니다.
결과와 배운 점
단일 스킬만 써오던 중에 이것이 어떻게 돌아가는건지 알고 싶었습니다. 이미 잘 만들어진 스킬을 보는 것은 매우 도움이 되었습니다. 특히나 claude 의 인터랙티브 시각화는 복잡한 스킬을 이해하는데 이보다 좋을 수 없는 수준이었습니다.
스킬에 대해 기억할 것 3가지만 꼽자면,
스킬 품질은 description이 결정한다. Claude는 description만 보고 이 스킬을 쓸지 말지를 판단한다.
스킬은 한 번 만들고 끝이 아니다. 테스트 → 피드백 → 개선의 루프를 반복할수록 좋아진다.
멀티에이전트는 "작업이 많을 때"가 아니라 "독립적으로 나눌 수 있을 때" 쓴다.
