AI 에이전트 스킬 만들기 5가지 원칙: 설명문 트리거·컨텍스트 절약·결정적 스크립트·보안 검증

핵심 메시지

• 스킬은 모델이 이미 아는 지식이 아니라 '우리 조직이 그 일을 하는 방식'이라는 절차적 지식을 넘겨주는 장치이며, 형식은 폴더 안의 마크다운 파일 하나로 끝날 만큼 단순하다.
• 에이전트는 시작할 때 각 스킬의 이름과 설명문만 읽기 때문에, 스킬이 실제로 호출될지 여부는 본문이 아니라 설명문이 결정한다.
• 본문은 길수록 좋은 것이 아니라 컨텍스트 창을 두고 다른 정보와 경쟁하므로, 모델이 이미 아는 내용은 빼고 500줄 안팎으로 유지하되 나머지는 참조 폴더로 미뤄야 한다.
• 매번 정확해야 하는 단계는 지시문 대신 스크립트로 고정해 모델이 그때그때 논리를 다시 만들어내지 않게 해야 한다.
• 스킬은 코드를 실행할 수 있으므로 외부에서 받은 스킬은 다른 의존성과 똑같이 내용을 읽고 검증한 뒤에 돌려야 한다.

쉽게 이해하기

IBM 테크놀로지의 마틴 킨과 브리 코페키가 AI 에이전트 스킬을 만들 때 지켜야 할 다섯 가지 원칙을 정리했다. 두 사람은 스킬을 '모델에게 건네는 절차적 지식'으로 정의한다. 모델은 이미 방대한 사실을 알고 있지만, 특정 조직이 특정 업무를 처리하는 고유한 방식은 알지 못하고, 스킬이 바로 그 부분을 가르친다는 설명이다.

형식 자체는 우스울 만큼 단순하다. 폴더 하나에 마크다운 파일을 넣으면 그만이고, 관련 규격은 개방형 표준으로 공개돼 있다. 문제는 그 단순함 때문에 오히려 망치기 쉽다는 점이다. 진행자들은 확률적으로 동작하는 모델에게 텍스트 폴더를 넘기고 여러 단계짜리 작업을 맡기는 구조 자체가 조심스럽다고 지적한다.

첫 번째 원칙은 설명문이 곧 방아쇠라는 것이다. 스킬 파일 맨 위 설정에는 이름과 설명이 들어가는데, 이름은 64자, 설명은 1,024자까지만 쓸 수 있다. 스킬을 수십 개 깔아두면 에이전트가 모든 본문을 한꺼번에 읽을 수 없으니, 시작 시점에는 이름과 설명만 훑는다. 따라서 그 두 줄만으로 '무엇을 하는지'와 '언제 써야 하는지'가 모두 드러나야 한다. 발표자들은 모델이 써야 할 스킬을 그냥 지나치는 경우가 잦다며, 설명문은 다소 적극적으로 쓰는 편이 안전하다고 조언한다.

두 번째와 세 번째 원칙은 서로 팽팽하게 맞선다. 본문은 모델이 접근할 수 없는 실제 경험에서 나와야 한다는 것이 두 번째다. 한 번 직접 손으로 작업하며 무엇이 통했고 어디서 고쳤는지 적어두거나, 이미 가진 보고서·운영 문서·리뷰 코멘트에서 뽑아내라는 것이다. 특히 매번 손으로 고쳐주게 되는 환경별 함정은 가장 값진 항목이니 반드시 적어두라고 강조한다. 반면 세 번째 원칙은 컨텍스트를 아끼라는 것이다. 본문의 모든 줄이 모델의 주의를 두고 경쟁하므로, 모델이 이미 아는 상식은 빼고 500줄 남짓으로 줄인 뒤 나머지는 참조용 하위 폴더로 넘겨 필요할 때만 열게 하라고 권한다.

네 번째는 결정적 스크립트를 쓰라는 것이다. 느슨해도 되는 단계는 지시문으로 충분하지만, 매번 정확히 같아야 하는 단계는 코드로 고정하라는 뜻이다. 진행자는 실제 보고서를 바탕으로 만든 스킬이 첫 실행에서 행 합계와 열 합계가 맞지 않았던 경험을 든다. 계산을 스크립트로 옮기자 그 부류의 오류가 통째로 사라졌다. 마지막 원칙은 검증이다. 스킬은 파일 시스템이나 API 키에 손댈 수 있는 코드를 품을 수 있는데, 공개 스킬 약 4,000개를 조사한 결과 35% 이상에서 보안 결함이, 13%에서는 프롬프트 인젝션이나 악성코드 같은 치명적 문제가 발견됐다는 감사 결과가 소개된다.

주요 인사이트

• 스킬이 실패하는 첫 지점은 품질이 아니라 호출 여부다. 아무리 잘 쓴 본문도 설명문이 모호하면 에이전트가 그 스킬을 아예 열지 않는다.
• 모델에게 스킬을 대신 써달라고 시키면 '오류를 적절히 처리하라', '입력을 검증하라' 같은 이미 아는 내용만 돌아온다. 사람이 가진 도메인 지식을 넣고 반복 작업만 모델에 맡기는 역할 분담이 핵심이다.
• 상세함과 간결함은 실제로 충돌하며, 해법은 둘 중 하나를 고르는 것이 아니라 계층을 나누는 것이다. 본문에는 핵심만 두고 세부는 참조 폴더로 미루는 점진적 공개 방식이 그 답으로 제시된다.
• 테스트를 늘리는 것으로는 신뢰를 살 수 없다. 테스트는 이미 의심한 항목만 잡아내므로, 반드시 맞아야 하는 부분은 애초에 추측을 개입시키지 않는 편이 낫다.
• 개방형 표준이라는 사실은 개별 스킬의 안전성을 전혀 보장하지 않는다. 외부 스킬은 프로젝트에 새 패키지를 들일 때와 같은 절차로 무엇을 하고 어디에 접속하는지 읽어봐야 한다.

자주 묻는 질문

관련 AI 소식