AI 에이전트 스킬 설계 가이드: 스킬 중심 하네스 구축과 대규모 스킬 라이브러리 운영 원칙

핵심 메시지

• 에이전트가 제품의 전면에 서면 화면과 버튼으로 존재하던 기능이 '스킬'이라는 형태로 옮겨간다.
• 프롬프트는 에이전트가 누구인지, 도구는 무엇에 연결되는지, 스킬은 일을 어떻게 처리하는지를 정의한다. 비즈니스 로직이 들어갈 자리는 스킬이다.
• 스킬을 지원하는 하네스의 최소 구성은 스킬 레지스트리, 시스템 프롬프트, 파일 읽기 도구 세 가지뿐이다.
• 스킬의 설명문(description)은 문서가 아니라 라우팅 신호이며, 스킬 자체가 아니라 사용자의 요청 문장에 맞춰 써야 한다.
• 스킬은 모델 버전에 묶인 계약에 가깝기 때문에, 모델을 올릴 때마다 평가(eval)를 다시 돌려야 한다.

쉽게 이해하기

금융 데이터·리서치 기업 팩트셋(FactSet)의 수석 AI 엔지니어 요겐드라 미라제는 AI 엔지니어 콘퍼런스 발표에서 자사가 걸어온 경로를 먼저 공유했다. 이전에는 에이전트가 매번 처음부터 방법을 찾아내지 않도록 '블루프린트'라는 단계별 레시피를 직접 만들어 넘겼는데, 돌이켜 보니 그것은 조악한 형태의 스킬이었다는 것이다. 앤트로픽이 스킬 규격을 공개한 뒤로는 자체 표준을 유지할 이유가 없어져 블루프린트를 버리고 스킬 체계로 완전히 옮겨 갔다고 말했다.

발표의 출발점은 제품의 표면이 바뀌었다는 관찰이다. 예전의 소프트웨어는 화면과 버튼, 입력 폼, 대시보드로 이루어진 표면이었고 사용자가 그 UI를 직접 탐색했다. 지금은 사용자가 에이전트에게 말을 걸거나, 에이전트가 뒤에서 판단을 내리며 사용자를 안내하는 인터페이스가 늘고 있다. 그렇다면 기능은 어디에 사는가. 그는 '누가(프롬프트) · 무엇에(도구) · 어떻게(스킬)'라는 구분으로 답한다. 팩트셋에서 주식 리서치와 자산관리 워크플로는 과거 버튼과 드롭다운, 전용 화면이었지만 지금은 각각 하나의 스킬이 됐다.

여기서 따라 나오는 변화가 있다. 스킬은 제품을 잘 아는 사람이면 누구나 쓸 수 있기 때문에, 기능을 출시하는 일이 엔지니어의 전유물에서 벗어난다. 대신 엔지니어의 역할은 '기능을 출시하는 사람'에서 '스킬이 잘 굴러가도록 하네스를 만드는 사람'으로 이동한다. 스킬 자체는 마크다운 한 장으로도 성립하고, 복잡해지면 참고 파일과 실행 스크립트를 거느린다. 핵심은 SKILL.md이며 앞머리의 이름과 설명이 발견을 담당하고, 본문에 업무 로직과 지시가 들어간다.

직접 만든 하네스에 스킬 지원을 붙이는 최소 조건은 의외로 단출하다. 이름·설명·경로를 담은 스킬 레지스트리, 그 목록을 넣어 둘 시스템 프롬프트, 그리고 파일을 읽는 도구면 된다. 스크립트를 실행할 생각이라면 배시나 샌드박스 환경이 추가로 필요하다. 이때 시스템 프롬프트에는 스킬 본문이 아니라 이름과 설명, 경로만 넣는다. 에이전트가 목록을 훑고 필요한 스킬만 골라 읽게 하는 이 방식이 '점진적 공개'다. 발표에서는 기업 리서치 스킬이 웹 검색으로 마크다운 보고서를 만들고, 리포트 스킬이 그것을 HTML이나 PDF로 바꾸는 세 개짜리 예제로 이 흐름을 보여 줬다.

규모가 커지면 문제의 성격 자체가 달라진다. 스킬이 몇 개일 때는 전부 시스템 프롬프트에 밀어 넣어도 작동하지만, 열 개를 넘어서면 임베딩 유사도 검색이나 작은 모델을 써서 후보를 추린 뒤 프롬프트에 담는 단계를 고민해야 한다. 수백 개에 이르면 계층 구조와 메타데이터 필터, 그리고 거버넌스가 필요해진다. 그는 이를 편입·소유·경계·수명주기·정합성 다섯 축으로 정리하면서, 이것이 관료적 절차가 될 필요는 없고 코드에서 수십 년간 통해 온 관행을 그대로 빌려 오면 된다고 했다.

주요 인사이트

• 설명문은 라우팅 신호다. 같은 보고서 스킬이라도 'PDF 보고서를 요청할 때만 사용'처럼 사용자의 말에 등장할 단어를 넣어야 에이전트가 제대로 고른다. 설명문이 스킬 내부 사정을 설명하거나 서로 비슷해지면 호출 자체가 어긋난다.
• 스킬은 데이터 모델이 아니라 사용자 의도를 기준으로 잘라야 한다. 발표자는 처음에 '추정치 분석', '기초 자료' 같은 단위로 스킬을 만들었다가 실제 사용 사례와 맞지 않아 여러 번 다시 잘랐고, 결국 '실적 발표 준비', '장 시작 전 브리핑' 같은 업무 단위로 바꿨다.
• 모델을 올렸을 뿐 스킬은 한 줄도 바꾸지 않았는데 에이전트가 지시를 따르지 않는 일이 있었다. 원인은 새 모델이 스킬의 앞부분에 더 무게를 뒀는데 중요한 지시가 뒷부분에 있었던 것. 그래서 스킬은 문서가 아니라 모델 버전에 묶인 계약이며, 평가 없는 스킬은 희망사항일 뿐이라는 결론이 나온다.
• 거버넌스의 다섯 축은 각각 코드의 관행과 짝이 맞는다. 새 스킬을 만들지 기존 스킬에 넣을지 판단하는 편입은 PR 리뷰에, 스킬 소유자 지정은 코드 오너에, 시맨틱 버저닝과 폐기 예고·변경 이력은 릴리스 관리에, 주기적 감사는 코드 정리에 대응한다.
• 에이전트 제품의 스킬은 대부분 모델이 알아서 고르게 두는 편이 낫다. 비기술 사용자에게 어떤 스킬이 있는지 외우게 하는 것은 불필요한 인지 부담이기 때문이다. 대신 도구는 허용 목록으로 묶어 스킬이 넘볼 수 있는 경계를 명확히 해야 한다.

자주 묻는 질문

관련 AI 소식