AI 에이전트 스킬 작성법 — 트리거·구조·스티어링·가지치기 4단계 체크리스트 정리

핵심 메시지

• 쓸 수 있는 스킬이 너무 많아 좋은 스킬과 나쁜 스킬을 구분할 수 없는 ‘스킬 지옥(skill hell)’이 새로운 문제로 떠올랐다.
• 스킬은 ‘사용자 호출형’과 ‘모델 호출형’으로 나뉘며, 각각 에이전트의 컨텍스트 부담과 사용자의 인지 부담이라는 서로 다른 비용을 가진다.
• 스킬은 ‘단계(steps)’와 ‘참고자료(reference)’ 두 단위로 구성되며, SKILL.md 본문은 최대한 작게 유지해야 한다.
• 많은 의미를 압축한 ‘리딩 워드(leading word)’를 본문에 넣고 반복하면 에이전트의 행동을 효과적으로 유도할 수 있다.
• 중복(DRY), 누적된 군더더기(sediment), 효과 없는 문구(no-op)를 ‘삭제 테스트’로 솎아내 스킬을 작게 만든다.

쉽게 이해하기

발표자는 AI 엔지니어 행사에 직접 참석하지 못해 영상으로 발표를 대신하며, 자신이 운영하는 인기 스킬 저장소 사용자들이 겪는 문제를 짚는다. 과거 개발자들이 ‘튜토리얼 지옥’과 ‘프레임워크 지옥’을 거쳤듯, 지금은 무료로 받을 수 있는 스킬이 넘쳐나지만 조각들이 어떻게 맞물리는지 몰라 약속된 결과를 얻지 못하는 ‘스킬 지옥’에 빠져 있다고 진단한다. 빠진 것은 ‘무엇이 좋은 스킬을 만드는가’에 대한 공통 기준이며, 그는 그 기준을 체크리스트로 제시한다.

첫 항목은 ‘트리거’, 즉 스킬이 어떻게 호출되는가다. 모든 스킬은 사용자가 직접 호출할 수 있지만, 설명(description)을 에이전트의 컨텍스트에 넣어 모델이 스스로 SKILL.md를 불러오게 하는 ‘모델 호출형’도 있다. 모델 호출형은 유연하지만 매 요청마다 설명이 토큰을 소모하고 에이전트가 생각할 거리를 늘린다. 반대로 사용자 호출형은 컨텍스트 부담은 줄지만 사용자가 스킬을 깊이 이해해야 하는 인지 부담을 키운다.

두 번째는 ‘구조’다. 스킬은 따라갈 절차인 ‘단계’와 그 단계를 돕는 ‘참고자료’ 두 단위로 나눌 수 있다. 핵심 원칙은 SKILL.md 본문을 가능한 한 작게 유지하는 것이다. 작은 스킬은 유지·감사하기 쉽고, 단어 하나를 줄일 때마다 토큰이 절약된다. 여러 분기(branch)로 쓰이는 스킬이라면, 특정 분기에서만 필요한 참고자료를 ‘컨텍스트 포인터’ 뒤의 별도 파일로 빼내 본문에서 덜어낸다.

세 번째는 ‘스티어링’, 즉 에이전트가 원하는 대로 움직이게 만드는 일이다. 핵심 기법은 ‘리딩 워드’다. ‘버티컬 슬라이스(vertical slice)’처럼 의미가 압축된 표현을 본문에 심어 반복하면, 에이전트가 사고·출력 과정에서 그 단어를 되뇌며 행동을 바꾼다. 또한 에이전트가 ‘계획 세우기’ 같은 다음 목표를 보면 현재 단계(예: 질문하기)에 충분한 노력을 쏟지 않으므로, 단계를 별도 스킬로 분리해 미래 단계를 숨기면 현재 단계의 수행이 깊어진다.

마지막은 ‘가지치기’다. 큰 스킬은 대개 그 자체가 문제가 아니라 다른 실패의 증상이다. 같은 내용을 여러 곳에 반복하지 말고(DRY) 각 부분이 단일 출처를 갖게 하며, 공동 편집으로 쌓인 군더더기(sediment)는 구조를 점검해 적절한 분기로 옮기거나 제거한다. 지워도 에이전트 행동이 그대로일 ‘no-op’ 문구는 삭제 테스트로 솎아낸다. 이 모든 점검을 거치면 작고 명확한 스킬로 ‘스킬 지옥’에서 벗어날 수 있다고 정리한다.

주요 인사이트

• 모델 호출형 스킬은 편리하지만 매 요청마다 설명이 토큰을 소모하고, 완벽히 들어맞는 상황에서도 모델이 호출을 건너뛸 수 있는 ‘예측 불가능성’ 비용이 따른다.
• 한 분기에서만 쓰이는 참고자료는 컨텍스트 포인터 뒤로 빼서 SKILL.md에서 덜어내면 유지보수와 토큰 양쪽에서 이득이다.
• 단계를 별도 스킬로 쪼개 미래 단계를 숨기면, 에이전트가 현재 단계에 더 많은 ‘품(leg work)’을 들이게 된다 — 발표자는 계획 단계를 분리한 사례를 든다.
• 리딩 워드가 잘 작동하는지는 에이전트의 추론 과정(reasoning trace)에서 그 단어가 되풀이되는지로 확인할 수 있다.
• 큰 스킬은 대개 중복·군더더기·no-op 같은 다른 실패 모드의 증상이므로, 크기보다 원인을 먼저 봐야 한다.

자주 묻는 질문

관련 AI 소식