Agent Skills 설계법: 컨텍스트 창을 아끼면서 에이전트 전문성을 유지하는 방법

요약: Agent Skills는 모든 지침을 system prompt에 넣는 대신, 필요한 순간에만 전문 지식과 스크립트를 로드하는 구조입니다. Genkit Go의 Agent Skills 지원은 이 패턴을 제품 코드에 넣을 수 있게 보여줍니다. 핵심은 progressive disclosure, 명확한 description, 작은 SKILL.md, 번들 리소스 관리입니다.

문제: 에이전트가 커질수록 system prompt가 쓰레기통이 된다

AI 에이전트를 운영하다 보면 처음에는 간단합니다. “우리 회사 정책을 따라라”, “이 API를 사용해라”, “답변 형식은 JSON이다” 정도로 시작합니다. 몇 주 지나면 상황이 바뀝니다. 환불 정책, 보안 규칙, 장애 대응 절차, 코드 리뷰 기준, 배포 체크리스트, 고객 등급별 응대 방식이 모두 system prompt에 들어갑니다.

그 결과는 predictable합니다. 토큰 비용이 늘고, 모델의 집중도가 떨어지고, 서로 충돌하는 지침이 생깁니다. 실제로 필요한 지식은 요청마다 다른데, 모든 요청에 모든 문서를 넣기 때문입니다.

Google이 Genkit에서 소개한 Agent Skills 패턴은 이 문제를 progressive disclosure로 풉니다. 처음에는 skill의 metadata만 모델에 노출하고, 요청이 skill description과 맞을 때 full instruction과 references, scripts를 로드합니다.

Agent Skill의 기본 구조

Agent Skill은 보통 하나의 디렉터리로 관리합니다.

skill-name/
  SKILL.md
  scripts/
  references/
  assets/

SKILL.md는 frontmatter와 body로 나뉩니다. frontmatter에는 name, description, license, version 같은 메타데이터가 들어갑니다. body에는 실제 작업 절차, 주의사항, 예시, 체크리스트가 들어갑니다.

중요한 것은 description입니다. description은 모델이 “이 skill을 언제 켜야 하는지” 판단하는 검색 키워드이자 라우팅 규칙입니다. 너무 넓게 쓰면 항상 켜지고, 너무 좁게 쓰면 필요한 순간에 켜지지 않습니다.

좋은 description은 다음 조건을 만족합니다.

• 어떤 작업에서 켜야 하는지 구체적이다.
• 어떤 산출물을 만들어야 하는지 포함한다.
• 유사하지만 다른 작업과 경계가 있다.
• 브랜드 문구보다 동작 조건이 앞선다.

예를 들어 “마케팅에 도움을 주는 skill”은 나쁩니다. “신규 SaaS 랜딩 페이지의 hero copy, pricing objection, CTA variant를 작성할 때 사용”은 훨씬 낫습니다.

progressive disclosure의 장점

첫 번째 장점은 비용입니다. 모든 문서를 항상 prompt에 넣지 않으니 token consumption이 줄어듭니다. 특히 에이전트가 tool loop를 돌 때 같은 system prompt가 반복적으로 들어간다면 차이가 커집니다.

두 번째 장점은 품질입니다. 모델이 지금 필요 없는 규칙까지 동시에 고려하지 않아도 됩니다. 코드 리뷰 작업에 고객 환불 정책이 들어가 있으면 attention이 낭비됩니다. 반대로 코드 리뷰 skill이 켜진 순간에는 review checklist, repository convention, test command 같은 정보를 집중적으로 제공할 수 있습니다.

세 번째 장점은 배포 방식입니다. skill은 markdown과 script 묶음이므로 코드처럼 버전 관리할 수 있습니다. 특정 팀의 운영 노하우를 skill repository로 관리하면, 에이전트 prompt를 직접 수정하지 않고도 전문성을 업데이트할 수 있습니다.

실무 설계 패턴

첫째, skill은 “부서”가 아니라 “반복 작업” 단위로 나눕니다. marketing 하나보다 landing-page-copy, cold-email-review, pricing-page-audit이 낫습니다. activation이 명확해야 context 낭비가 줄어듭니다.

둘째, SKILL.md body는 길어도 되지만 구조화되어야 합니다. 추천 구조는 다음과 같습니다.

# 목적
# 활성 조건
# 입력 확인 항목
# 작업 절차
# 금지 사항
# 산출물 형식
# 최종 체크리스트

셋째, references에는 긴 문서만 넣습니다. 모델이 항상 읽어야 하는 절차는 SKILL.md에 두고, 예시 모음·API 문서·브랜드 가이드처럼 길고 선택적인 자료는 references로 분리합니다.

넷째, scripts는 결정적인 작업에만 씁니다. 예를 들어 slug 생성, JSON schema validation, 링크 검사, 제목 prefix 제거 같은 작업은 모델에게 말로 시키는 것보다 script로 검증하는 편이 낫습니다.

실패 패턴

가장 흔한 실패는 skill을 너무 많이 잘게 쪼개는 것입니다. skill이 100개가 되면 discovery metadata 자체가 prompt를 오염시킵니다. 자주 함께 쓰이는 절차는 하나로 묶고, 내부 섹션으로 분리하는 편이 낫습니다.

두 번째 실패는 description이 마케팅 문구가 되는 것입니다. “최고 품질의 콘텐츠를 만드는 skill” 같은 설명은 activation에 도움이 되지 않습니다. 모델은 감성 문구보다 조건문을 필요로 합니다.

세 번째 실패는 skill이 업데이트되지 않는 것입니다. 에이전트가 틀린 절차를 반복한다면 prompt를 탓하기 전에 skill 문서가 실제 업무와 맞는지 봐야 합니다. 운영 규칙이 바뀌면 skill도 코드처럼 리뷰와 배포가 필요합니다.

작은 예시: 코드 리뷰 skill

---
name: code-review
description: Use when reviewing pull requests, checking implementation risk, test coverage, security impact, and release readiness for application code changes.
---

# Code Review Protocol

1. 변경 목적을 한 문장으로 요약한다.
2. 위험도를 correctness, security, performance, UX로 나눠 본다.
3. 테스트가 변경된 로직을 실제로 검증하는지 확인한다.
4. blocking issue와 non-blocking suggestion을 분리한다.
5. 마지막에 merge 가능 여부를 명확히 쓴다.

## 금지
- 취향 문제를 blocking처럼 말하지 않는다.
- 실행하지 않은 테스트를 실행한 것처럼 말하지 않는다.

이 정도만 있어도 일반적인 “코드 좋아 보입니다”보다 훨씬 일관된 리뷰가 나옵니다.

도입 체크리스트

• system prompt에 들어간 긴 절차를 목록화한다.
• 요청마다 항상 필요한 규칙과 특정 작업에서만 필요한 규칙을 분리한다.
• 반복 작업 단위로 5~10개 핵심 skill부터 만든다.
• description은 activation 조건 중심으로 쓴다.
• 긴 예시는 references로 빼고, 검증 가능한 규칙은 scripts로 만든다.
• skill 변경은 PR로 리뷰하고 version을 남긴다.
• activation 로그를 남겨 어떤 skill이 너무 자주 또는 너무 적게 켜지는지 본다.

Agent Skills는 “프롬프트를 잘 쓰는 법”이 아니라 에이전트 지식을 운영하는 방식입니다. 에이전트가 제품의 일부가 될수록, context window를 아끼는 설계가 비용과 품질을 동시에 좌우합니다.