Agent Skills 설계법: 긴 프롬프트 대신 필요한 지식만 로드하는 방법

AI 에이전트를 만들다 보면 시스템 프롬프트가 점점 길어진다. 코딩 규칙, 배포 절차, 장애 대응 매뉴얼, 고객지원 톤, 보안 정책, 데이터베이스 스키마를 전부 넣고 싶어진다. 처음에는 잘 작동하는 것처럼 보이지만 곧 문제가 생긴다. 토큰 비용이 늘고, 모델이 중요한 규칙을 놓치고, 서로 충돌하는 지시가 섞인다. Agent Skills는 이 문제를 “모든 지식을 항상 넣지 말고, 필요한 순간에만 로드하자”는 방식으로 푼다.

Google은 Genkit에서 Agent Skills 지원을 소개하며 progressive disclosure 원칙을 강조했다. Skill은 SKILL.md와 보조 파일로 구성되고, 처음에는 frontmatter의 이름과 설명만 에이전트에게 노출된다. 요청이 해당 skill과 맞을 때만 본문 지침과 references, scripts, assets가 로드된다. 실무적으로는 프롬프트를 거대한 한 문서로 키우는 대신, 운영 절차를 작은 패키지로 나누는 방식이다.

Agent Skills가 필요한 이유

에이전트가 맡는 일이 늘어나면 컨텍스트 윈도우는 빠르게 오염된다. 예를 들어 “배포 장애를 조사해 줘”라는 요청에 회계 처리 규칙, 블로그 작성 톤, 고객 환불 정책까지 같이 들어가 있을 필요는 없다. 반대로 “환불 요청 초안을 써 줘”라는 작업에 Kubernetes 롤백 절차가 들어가면 모델의 주의가 흐려진다. 긴 프롬프트는 많은 지식을 담지만, 필요한 지식을 더 잘 쓰게 해 주지는 않는다.

Skill 구조는 지식의 discoverability와 activation을 분리한다. 에이전트는 “어떤 skill이 있는지”만 알고 있다가, 필요할 때 use_skill 같은 도구로 자세한 내용을 불러온다. 이렇게 하면 기본 컨텍스트는 짧게 유지되고, 특정 작업에는 더 정확한 절차를 제공할 수 있다. 토큰 절감만이 목적이 아니다. 운영 절차를 파일 단위로 버전 관리하고 리뷰할 수 있다는 점이 더 중요하다.

좋은 SKILL.md의 구조

좋은 skill은 frontmatter에서 언제 써야 하는지가 분명해야 한다. 이름만 멋있고 설명이 모호하면 에이전트가 잘못 활성화하거나 필요한데도 놓친다. 예를 들어 database-incident-triage라는 skill은 “데이터베이스 지연, connection pool 포화, 쿼리 타임아웃 진단”처럼 활성 조건을 구체적으로 써야 한다. “DB 관련 도움”은 너무 넓다.

본문에는 절차를 순서대로 적는다. 첫 단계에서 어떤 텔레메트리를 확인할지, 두 번째 단계에서 최근 배포와 스키마 변경을 어떻게 볼지, 세 번째 단계에서 절대 해서는 안 되는 조치가 무엇인지 적는다. 보조 파일에는 긴 reference, 스크립트, 템플릿을 둔다. 본문이 다시 거대한 매뉴얼이 되면 skill의 장점이 줄어든다. 본문은 판단 흐름, 보조 파일은 세부 자료라는 경계를 두는 편이 낫다.

코드 에이전트에 적용하는 방법

코딩 에이전트에서는 skill을 작업 유형별로 나눌 수 있다. 예를 들어 react-native-debugging, nextjs-cache-audit, database-migration-review, security-code-review, release-note-writing처럼 만든다. 에이전트가 “Next.js 동적 라우트에서 캐시 문제가 난다”는 요청을 받으면 nextjs-cache-audit skill을 로드하고, 일반 문서 작성 요청에는 로드하지 않는다.

이 구조는 팀 규칙에도 좋다. “코드 수정 후 테스트를 실행하라” 같은 전역 규칙은 기본 프롬프트에 있어도 된다. 하지만 “이 회사의 DynamoDB 마이그레이션은 백업 2벌과 GSI 검증이 필요하다” 같은 프로젝트별 절차는 skill로 두는 편이 관리하기 쉽다. 프로젝트가 바뀌어도 전역 프롬프트를 계속 수정할 필요가 없다.

운영 에이전트에 적용하는 방법

고객지원이나 내부 운영 에이전트에서는 skill이 playbook 역할을 한다. 환불, 계정 복구, 보안 사고, 결제 실패, 배송 지연, 개인정보 삭제 요청을 각각 skill로 나눈다. 각 skill에는 필요한 확인 항목, 금지 문구, 승인 필요 조건, escalations를 넣는다. 예를 들어 개인정보 삭제 요청 skill에는 본인 확인 전 데이터 삭제 금지, 법적 보존 의무 확인, 완료 후 기록 방식이 들어가야 한다.

중요한 것은 skill이 모델의 기억이 아니라 제품 정책이라는 점이다. 정책 변경은 PR 리뷰를 거치고, 변경 이력을 남기고, 이전 버전으로 롤백할 수 있어야 한다. 에이전트가 외부 고객에게 답변하거나 시스템을 변경한다면 skill 파일 하나가 실제 비즈니스 결과를 바꾼다.

흔한 실패 패턴

첫 번째 실패는 skill을 너무 많이 쪼개는 것이다. 작은 skill이 수십 개 생기면 활성 조건이 겹치고 에이전트가 고르기 어려워진다. 두 번째 실패는 반대로 하나의 skill에 모든 절차를 넣는 것이다. 그러면 거대한 시스템 프롬프트를 파일 하나로 옮긴 것뿐이다. 세 번째 실패는 skill에 실행 권한을 과하게 주는 것이다. 스크립트를 포함할 수 있다고 해서 삭제, 배포, 외부 전송을 자동 실행하게 두면 안 된다.

네 번째 실패는 평가 없이 skill을 수정하는 것이다. skill 본문 한 줄을 바꾸면 에이전트 행동이 달라진다. 따라서 중요한 skill에는 간단한 behavioral eval이 있어야 한다. “DB 장애 skill을 로드하면 최근 배포 확인 전 rollback을 제안하지 않는다”, “환불 skill을 로드하면 본인 확인 전 환불 확정을 말하지 않는다” 같은 테스트가 필요하다.

도입 체크리스트

• 전역 프롬프트에서 특정 도메인 절차를 분리한다.
• skill 이름과 description에 활성 조건을 구체적으로 쓴다.
• 본문은 판단 흐름, references는 세부 자료로 나눈다.
• scripts가 있다면 읽기 전용과 변경 작업을 명확히 분리한다.
• 삭제, 결제, 배포, 외부 전송은 skill만으로 자동 허용하지 않는다.
• skill 변경은 코드 리뷰와 버전 관리를 거친다.
• 핵심 skill마다 행동 테스트를 만든다.

결론

Agent Skills는 프롬프트를 예쁘게 정리하는 문서 포맷이 아니다. 에이전트가 필요한 지식만 제때 불러오게 만드는 운영 구조다. 긴 시스템 프롬프트로 모든 일을 해결하려는 방식은 비용과 정확도, 유지보수에서 한계가 온다. skill을 잘 설계하면 에이전트는 더 짧은 기본 컨텍스트로 시작하고, 특정 작업에서는 더 정확한 절차를 따른다. 실무팀이 해야 할 일은 더 긴 프롬프트를 쓰는 것이 아니라, 지식을 작고 검증 가능한 skill로 나누는 것이다.

핵심 출처

• Google Developers Blog, Enable on-demand expertise with Agent Skills in Genkit Go
• Agent Skills specification