많은 사람이 AI 에이전트용 “스킬”을 그냥 마크다운으로 적은 프롬프트라고 생각합니다. 그런데 수많은 스킬을 검토해온 개발자 샘 맥클라우드는, 그 착각 하나가 대부분의 실패로 이어진다고 말합니다.

맥클라우드는 에이전트 스킬을 자주 작성하고 리뷰하면서 반복적으로 마주치는 흔한 실수들을 정리했습니다. 그가 말하는 핵심은 스킬이 사람이 읽는 문서가 아니라, 에이전트 시스템을 구성하는 하나의 부품이라는 점입니다.

출처: Writing and Reviewing Agent Skills – Common Pitfalls – smcleod.net

설명을 요약처럼 쓰는 실수

스킬에는 보통 description이라는 짧은 설명이 붙는데, 이 설명의 유일한 역할은 “언제 이 스킬을 불러와야 하는지” 에이전트에게 알려주는 것입니다. 그런데 많은 작성자가 이 자리에 스킬 내용 전체를 요약해 넣습니다. 문제는 에이전트가 그 요약만 보고 대충 알겠다며, 정작 스킬 본문을 열어보지 않고 넘어가 버릴 수 있다는 것입니다.

맥클라우드는 설명을 트리거 조건을 담은 명령문 정도로 짧고 단호하게 쓰라고 권합니다. 예를 들어 “사용자가 대시보드, 모니터링, 지표를 언급할 때는 반드시 이 스킬을 사용하라”처럼요.

모든 걸 한 파일에 우겨넣는 실수

두 번째는 스킬 하나에 모든 정보를 다 집어넣는 것입니다. 맥클라우드는 상황별로 필요한 세부 내용은 별도 참조 파일로 빼두고, 메인 파일에는 “특정 상황이면 이 파일을 읽어라”는 안내만 남기라고 말합니다. 필요할 때만 필요한 만큼 불러오는 방식입니다.

같은 맥락에서 그는 “이 줄을 지워도 에이전트의 행동이 달라지지 않는다면, 그 줄은 없어도 되는 것”이라는 간단한 삭제 테스트를 제안합니다. 반복적이고 정확도가 중요한 작업 역시 모델의 추론에 맡기기보다 별도 스크립트로 처리하는 편이 훨씬 안정적이라고 덧붙입니다.

구조 없는 다단계 작업

마지막 실수는 여러 단계를 거쳐야 하는 작업을 구조 없이 던져주는 것입니다. 절차가 길어질수록 에이전트는 중간에 흐트러지거나, 몇 단계를 건너뛰고 일찍 끝내버리는 경우가 많습니다. 맥클라우드는 각 단계를 번호로 명시하고 진행 상황을 추적하게 한 뒤, 모든 단계가 끝나면 스스로 검토하는 절차까지 넣어두면 이런 이탈을 막을 수 있다고 말합니다.

결국 사람이 아니라 에이전트를 위한 문서

이 세 가지 실수를 관통하는 공통점은 스킬을 사람이 읽는 문서처럼 쓴다는 것입니다. 에이전트에게 필요한 건 친절한 설명이 아니라, 언제 무엇을 하라는 정확한 트리거와 최소한의 지침입니다. 커스텀 GPT나 Claude 스킬을 직접 만들어본 적이 있다면, 내가 만든 설명이 요약이었는지 트리거였는지 한번 되짚어볼 만한 지점입니다.