ADK Agent Skills 패턴 가이드: 프로그레시브 디스클로저로 AI 에이전트 확장하기

여러분의 AI 에이전트가 지시를 따르는 건 기본이에요. 그런데 스스로 새로운 지시를 작성할 수 있다면 어떨까요? Google의 Agent Development Kit(ADK)이 제공하는 SkillToolset은 에이전트가 도메인 전문성을 필요할 때만 로드하고, 나아가 런타임에 완전히 새로운 전문성을 생성할 수 있게 해줘요. 보안 리뷰 체크리스트, 컴플라이언스 감사, 데이터 파이프라인 검증 등 어떤 작업이든 "생성 → 로드 → 사용"이라는 단순한 워크플로로 처리할 수 있어요. 이 글에서는 ADK Agent Skills의 핵심 아키텍처인 프로그레시브 디스클로저(Progressive Disclosure)와, 이를 활용한 4가지 실전 패턴을 깊이 있게 다뤄볼게요.

모놀리식 프롬프트의 한계와 프로그레시브 디스클로저

대부분의 AI 에이전트는 도메인 지식을 시스템 프롬프트에 직접 주입하는 방식을 써요. 컴플라이언스 규칙, 스타일 가이드, API 레퍼런스, 트러블슈팅 절차를 하나의 거대한 문자열로 합쳐 넣는 거죠.

에이전트 기능이 2~3개일 때는 이 방식이 잘 동작해요. 하지만 10개 이상의 태스크로 확장하면, 사용자의 쿼리가 실제로 해당 지식을 필요로 하는지 여부와 상관없이 매 LLM 호출마다 수천 토큰이 소비돼요. 이건 비용과 레이턴시 모두에서 심각한 병목이에요.

ADK Agent Skills 스펙은 이 문제를 프로그레시브 디스클로저로 해결해요. 지식 로딩을 세 단계로 분리하는 거예요:

• L1 메타데이터(~100 토큰/스킬): 스킬 이름과 설명만 포함해요. 시작 시 모든 스킬에 대해 로드되며, 에이전트가 관련성을 판단하는 메뉴 역할을 해요.
• L2 인스트럭션(<5,000 토큰): 스킬의 전체 본문이에요. 에이전트가 특정 스킬을 명시적으로 활성화할 때만 API를 통해 로드돼요.
• L3 리소스(필요 시): 스타일 가이드나 API 스펙 같은 외부 참조 파일이에요. 스킬의 인스트럭션이 요구할 때만 로드돼요.

이 아키텍처를 사용하면, 10개의 스킬을 가진 에이전트가 각 호출을 약 1,000 토큰의 L1 메타데이터로 시작해요. 모놀리식 프롬프트의 10,000 토큰 대비 약 90% 베이스라인 컨텍스트 절감 효과가 있어요.

4가지 스킬 패턴 완전 정복

ADK의 SkillToolset은 activate_skill, deactivate_skill, get_skill_resource 세 가지 도구를 자동 생성해요. 이를 기반으로 점진적으로 복잡해지는 4가지 패턴을 살펴볼게요.

패턴 1: 인라인 스킬 — 가장 단순한 시작점

Python 객체로 직접 정의하는 방식이에요. 변경 빈도가 낮은 소규모 규칙에 적합해요.

# ADK Pseudocode: Pattern 1: Inline Skill
seo_skill = models.Skill(
    frontmatter=models.Frontmatter(
        name="seo-checklist",
        description="SEO optimization checklist for blog posts.",
    ),
    instructions=(
        "When optimizing a blog post for SEO, check each item:\n"
        "1. Title: 50-60 chars, primary keyword near the start\n"
        "2. Meta description: 150-160 chars, includes a CTA\n"
        "3. Headings: H2/H3 hierarchy, keywords in 2-3 headings\n"
        "4. First paragraph: Primary keyword in first 100 words\n"
        "5. Images: Alt text with keywords, compressed\n"
    )
)

frontmatter 필드가 L1 메타데이터가 되고, instructions가 L2로 동작해요. "블로그 포스트 SEO 리뷰해 줘"라고 요청하면, 에이전트가 이 스킬을 로드해서 항목별로 체계적으로 적용하는 구조예요.

패턴 2: 파일 기반 스킬 — 참조 문서가 필요할 때

인라인 스킬은 단순 체크리스트에 적합하지만, 스타일 가이드나 API 스펙 같은 참조 문서가 필요하면 디렉터리 기반 구조를 사용해야 해요.

skills/blog-writer/
├── SKILL.md           # L2: 인스트럭션
└── references/
    └── style-guide.md # L3: 필요 시 로드

SKILL.md는 YAML 프론트매터로 시작하고, 마크다운 인스트럭션이 이어져요. get_skill_resource 도구를 통해 L3 리소스를 필요한 시점에만 로드하는 게 핵심이에요.

# ADK Pseudocode: Pattern 2: File-Based Skill
blog_writer_skill = load_skill_from_dir(
    pathlib.Path(__file__).parent / "skills" / "blog-writer"
)

패턴 3: 외부 스킬 — 커뮤니티 리포지토리 활용

외부 스킬은 파일 기반 스킬과 코드가 완전히 동일해요. 차이점은 SKILL.md를 직접 작성하는 대신, awesome-claude-skills 같은 커뮤니티 리포지토리에서 다운로드한다는 것뿐이에요.

npx skills add google/adk-docs -y -g

ADK Skills Spec이 범용 디렉터리 포맷을 정의하기 때문에, load_skill_from_dir는 SKILL.md의 출처를 신경 쓰지 않아요. Google도 공식 ADK 개발 스킬을 동일한 포맷으로 배포하고 있어요.

패턴 4: 스킬 팩토리 — 스스로 확장하는 에이전트

메타 스킬(Meta Skill)은 새로운 SKILL.md 파일 자체를 생성하는 게 목적인 스킬이에요. 메타 스킬을 장착한 에이전트는 자기 확장(self-extending)이 가능해져요. 사람의 개입 없이 런타임에 새로운 스킬 정의를 작성하고 로드할 수 있어요.

이건 단순히 프롬프트 엔지니어링이 아니라, 에이전트가 자신의 역량 범위를 동적으로 넓히는 아키텍처 패턴이에요. 예를 들어 "GraphQL API 보안 감사 체크리스트"가 필요한데 기존 스킬이 없다면, 에이전트가 직접 해당 스킬을 생성하고 즉시 활용할 수 있는 거예요.

실전 적용 시 고려할 점

ADK Agent Skills를 프로덕션에 적용할 때 몇 가지 중요한 포인트가 있어요:

• 스킬 그래뉼러리티: 스킬을 너무 잘게 쪼개면 L1 메타데이터가 비대해지고, 너무 크게 묶으면 프로그레시브 디스클로저의 이점이 줄어들어요. 하나의 스킬이 하나의 명확한 태스크를 담당하도록 설계하는 게 좋아요.
• L3 리소스 크기 관리: 참조 문서가 너무 크면 컨텍스트 윈도를 초과할 수 있어요. 청크 단위로 분할하거나, 요약본을 별도로 준비하는 전략이 필요해요.
• 메타 스킬 가드레일: 패턴 4를 사용할 때는 에이전트가 생성하는 스킬의 품질을 검증하는 레이어가 필수예요. 생성된 SKILL.md의 구조 검증, 인스트럭션 길이 제한, 테스트 실행 등을 자동화하는 게 안전해요.
• 버전 관리: 파일 기반 스킬과 외부 스킬은 Git으로 버전 관리하면 변경 추적과 롤백이 용이해요.

마무리

ADK Agent Skills의 프로그레시브 디스클로저 아키텍처는 모놀리식 프롬프트의 토큰 낭비 문제를 구조적으로 해결해요. 인라인 → 파일 기반 → 외부 → 메타 스킬로 이어지는 4가지 패턴을 상황에 맞게 조합하면, 확장 가능하고 비용 효율적인 에이전트 시스템을 구축할 수 있어요. 특히 패턴 4의 자기 확장 에이전트는 앞으로 에이전트 아키텍처의 중요한 방향이 될 거예요.