스킬로 ADK 에이전트를 구축하는 개발자 가이드

2026년 4월 1일

여러분의 AI 에이전트는 지시를 따를 수 있어요. 그런데 새로운 지시를 직접 만들 수도 있을까요? ADK(Agent Development Kit)의 SkillToolset은 에이전트가 필요할 때마다 도메인 전문 지식을 불러올 수 있도록 해줘요. 적절한 스킬 설정만 있다면, 에이전트가 런타임에 완전히 새로운 전문 지식을 생성할 수도 있죠. 보안 검토 체크리스트, 규정 준수 감사, 데이터 파이프라인 유효성 검사 등 무엇이 필요하든 워크플로는 간단해요. 생성하고, 로드하고, 사용하면 돼요.

SkillToolset은 진보적 공개(progressive disclosure) 방식을 통해 이걸 해내요. 이 아키텍처 패턴 덕분에 에이전트가 수많은 토큰을 하나의 거대한 시스템 프롬프트에 다 때려 박지 않고도, 필요한 순간에 정확히 컨텍스트를 로드할 수 있게 되는 거죠.

이 가이드에서는 네 가지 실용적인 스킬 패턴을 하나씩 살펴볼 거예요:

1. 인라인 체크리스트: 기본적이고 하드코딩된 스킬 구현 방식이에요.
2. 파일 기반 스킬: 외부 지시사항과 리소스를 로드하는 방법이에요.
3. 외부 임포트: 커뮤니티 기반 스킬 저장소를 활용하는 방법이에요.
4. 스킬 팩토리: 에이전트가 필요에 따라 새로운 스킬을 직접 작성하는 자체 확장 패턴이에요.

각 패턴은 이전 패턴을 기반으로 만들어지고요, 최종적으로는 에이전트가 스스로 역량을 동적으로 확장할 수 있는 아키텍처로 완성돼요.

거대 프롬프트의 문제점

대부분의 AI 에이전트는 시스템 프롬프트에서 도메인 지식을 바로 가져와요. 개발자들은 규정 준수 규칙, 스타일 가이드, API 참조, 문제 해결 절차 등을 하나의 거대한 지시 문자열로 쭉 연결해 놓는 경우가 많죠.

에이전트가 두세 가지 기능만 가지고 있을 때는 괜찮아요. 하지만 열 개 이상의 작업으로 확장될 경우, 이 모든 지시사항을 시스템 프롬프트에 연결하면 매번 LLM을 호출할 때마다 수천 개의 토큰 비용이 발생하게 돼요. 사용자의 특정 질의가 그 지식을 정말 필요로 하는지 여부와 상관없이 말이죠.

Agent Skills 명세는 진보적 공개 방식을 통해 이 문제를 해결해요. 지식 로딩을 세 가지 별개의 레벨로 나눈 거죠:

• L1 메타데이터 (스킬당 약 100 토큰): 스킬 이름과 설명만 포함돼요. 모든 스킬에 대해 시작 시 로드되고, 에이전트가 무엇이 관련 있는지 결정하기 위해 훑어보는 메뉴 역할을 해요.
• L2 지시사항 (5,000 토큰 미만): 전체 스킬 본문이에요. 에이전트가 특정 스킬을 명시적으로 활성화할 때만 API를 통해 로드돼요.
• L3 리소스 (필요에 따라): 스타일 가이드나 API 명세 같은 외부 참조 파일이에요. 스킬의 지시사항이 필요로 할 때만 로드돼요.

이 아키텍처를 사용하면 10개의 스킬을 가진 에이전트가 매번 호출을 시작할 때, 거대 프롬프트의 10,000 토큰 대신 약 1,000 토큰의 L1 메타데이터만으로 시작해요. 이는 기본 컨텍스트 사용량을 약 90% 정도 줄여주는 효과가 있어요.

ADK는 SkillToolset 클래스를 통해 이걸 구현하는데요, 이 클래스는 list_skills (L1), load_skill (L2), load_skill_resource (L3) 이렇게 세 가지 도구를 자동으로 생성해 줘요.

패턴 1: 인라인 스킬 (포스트잇)

가장 간단한 패턴이에요. name, description, instructions를 가진 파이썬 객체를 에이전트 코드에 직접 정의하는 거죠. 작고 안정적이며 거의 변하지 않는 규칙에 가장 적합해요.

# ADK Pseudocode: Pattern 1: Inline Skill

seo_skill = models.Skill(
    frontmatter=models.Frontmatter(
        name="seo-checklist",
        description="SEO optimization checklist for blog posts. Covers title tags, meta descriptions, heading structure, and readability.",
    ),
    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 call-to-action\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, descriptive names\n"
        "Review the content against each item and suggest improvements."
    ),
)

파이썬

복사됨

frontmatter 필드는 LLM이 모든 호출에서 보게 되는 L1 메타데이터가 돼요. instructions는 L2가 되고요, 에이전트가 이 스킬이 관련 있다고 판단할 때만 로드되죠. "내 블로그 게시물을 SEO 관점에서 검토해 줘"라고 요청하면, 에이전트는 이 스킬을 로드하고 각 항목을 체계적으로 적용해요.

패턴 2: 파일 기반 스킬 (참조 자료 바인더)

인라인 스킬은 간단한 체크리스트에는 잘 작동해요. 하지만 스킬에 참조 문서(스타일 가이드, API 명세 등)가 필요하다면, 디렉토리가 필요하죠.

파일 기반 스킬은 자체 디렉토리 안에 SKILL.md 파일과 선택적인 참조 자료, 애셋, 스크립트용 하위 디렉토리를 가지고 있어요. SKILL.md는 YAML frontmatter로 시작해서 마크다운 지시사항이 뒤따르는 형태예요.

skills/blog-writer/
├── SKILL.md           # L2: Instructions
└── references/
    └── style-guide.md # L3: Loaded on demand

일반 텍스트

복사됨

이 디자인은 지식을 두 개의 레이어로 분리해요. SKILL.md 지시사항(L2)은 에이전트에게 어떤 단계를 따라야 하는지 알려주고요. references/style-guide.md 파일(L3)은 각 단계에 필요한 상세 도메인 지식을 제공해요. 에이전트는 load_skill_resource 도구를 통해 지시사항에서 요청할 때만 참조 자료를 로드하죠.

# ADK Pseudocode: Pattern 2: File-Based Skill

blog_writer_skill = load_skill_from_dir(
    pathlib.Path(__file__).parent / "skills" / "blog-writer"
)

파이썬

복사됨

파일 기반 스킬은 지식을 재사용할 수 있게 해줘요. agentskills.io 명세를 따르는 어떤 에이전트든 같은 디렉토리를 로드할 수 있죠. 하지만 이 시나리오에서는 여전히 여러분이 직접 SKILL.md를 작성한 거예요.

패턴 3: 외부 스킬 (임포트)

외부 스킬은 파일 기반 스킬과 똑같이 작동해요. 유일한 차이점은 디렉토리가 어디에서 왔느냐는 거죠. 여러분이 직접 SKILL.md를 작성하는 대신, awesome-claude-skills 같은 커뮤니티 저장소에서 다운로드해서 동일한 load_skill_from_dir 호출로 로드하는 거예요.

# ADK Pseudocode: Pattern 3: External Skill (same API, different source)

content_researcher_skill = load_skill_from_dir(
    pathlib.Path(__file__).parent / "skills" / "content-research-writer"
)

파이썬

복사됨

코드는 패턴 2와 동일해요. agentskills.io 명세는 보편적인 디렉토리 형식을 정의하기 때문에, load_skill_from_dir은 여러분이 SKILL.md를 작성했든 다운로드했든 신경 쓰지 않아요. 구글은 npx skills add google/adk-docs -y -g 명령으로 설치 가능한 공식 ADK 개발 스킬을 같은 형식으로 발행하고 있어요.

이 세 가지 패턴은 이미 존재하는 스킬, 여러분이 직접 작성한 스킬, 그리고 찾아서 사용하는 스킬을 모두 다뤄요. 이제 패턴 4가 마지막 퍼즐을 맞춰주죠. 바로 에이전트가 스스로 스킬을 작성하는 거예요.

메타 스킬은 새로운 SKILL.md 파일을 생성하는 것을 목적으로 하는 스킬이에요. 메타 스킬을 갖춘 에이전트는 스스로 확장하는 능력을 갖추게 돼요. 런타임에 새로운 스킬 정의를 작성하고 로드함으로써 인간의 개입 없이도 자신의 역량을 확장할 수 있는 거죠.

스킬 생성기는 유효한 SKILL.md 파일을 작성하는 방법을 설명하는 인라인 스킬이에요. 핵심은 resources 필드에 있어요. 이 필드는 agentskills.io 명세 자체와 작동하는 예시를 L3 참조 자료로 포함하고 있죠. 새로운 스킬을 만들라고 요청받으면, 에이전트는 이 참조 자료들을 읽고 명세를 준수하는 SKILL.md를 생성해요.

# ADK Pseudocode: Pattern 4: Meta Skill (The Skill Factory)

skill_creator = models.Skill(
    frontmatter=models.Frontmatter(
        name="skill-creator",
        description=(
            "Creates new ADK-compatible skill definitions from requirements."
            " Generates complete SKILL.md files following the Agent Skills"
            " specification at agentskills.io."
        ),
    ),
    instructions=(
        "When asked to create a new skill, generate a complete SKILL.md file.\n\n"
        "Read `references/skill-spec.md` for the format specification.\n"
        "Read `references/example-skill.md` for a working example.\n\n"
        "Follow these rules:\n"
        "1. Name must be kebab-case, max 64 characters\n"
        "2. Description must be under 1024 characters\n"
        "3. Instructions should be clear, step-by-step\n"
        "4. Reference files in references/ for detailed domain knowledge\n"
        "5. Keep SKILL.md under 500 lines, put details in references/\n"
        "6. Output the complete file content the user can save directly\n"
    ),
    resources=models.Resources(
        references={
            "skill-spec.md": "# Agent Skills Specification (agentskills.io)...",
            "example-skill.md": "# Example: Code Review Skill...",
        }
    ),
)

파이썬

복사됨

resources 필드는 models.Resources 클래스가 핵심적인 역할을 하는 부분이에요. 참조 자료들은 agentskills.io 명세를 skill-spec.md로, 그리고 작동하는 코드 검토 스킬을 example-skill.md로 포함하고 있어요. 에이전트가 load_skill_resource("skill-creator", "references/skill-spec.md")를 호출하면, 유효한 스킬이 어떻게 구성되어야 하는지에 대한 전체 명세를 얻게 되는 거죠.

생성된 스킬을 위한 모범 사례: 스킬 자동 생성은 강력한 워크플로이지만, 최종 SKILL.md를 검토하는 인간 검토자를 두는 것을 권장해요. 여러분이 구축하는 모든 스킬에 대한 표준 관행으로, 그 효과를 테스트해야 하죠. ADK를 사용한 강력한 평가를 구축하여 배포 전에 스킬이 의도한 대로 정확히 작동하는지 쉽게 확인할 수 있어요.

실전 스킬 팩토리

에이전트에게 이렇게 요청해 보세요. "파이썬 코드의 보안 취약점을 검토하는 새로운 스킬이 필요해."

에이전트는 스킬 생성기를 로드하고, load_skill_resource를 통해 명세와 예시를 읽은 다음, 유효한 케밥 케이스 이름 지정, 입력 유효성 검사, 인증 및 암호화를 다루는 구조화된 지시사항, 그리고 심각도 기반 보고 형식을 포함하는 완전한 파이썬 보안 검토 스킬을 생성해요.

생성된 스킬은 동일한 agentskills.io 명세를 따르기 때문에 ADK뿐만 아니라 호환되는 어떤 에이전트에서도 작동해요. Gemini CLI, Claude Code, Cursor, 그리고 이 형식을 채택한 40개 이상의 다른 제품들에서 모두 사용할 수 있죠.

모든 것을 연결하기

네 가지 스킬을 모두 정의했다면, 이들을 SkillToolset으로 묶어서 에이전트에 넘겨주는 건 몇 줄 안 되는 코드만으로 가능해요.

# ADK Pseudocode: Assemble the Skill Factory

skill_toolset = SkillToolset(
    skills=[seo_skill, blog_writer_skill, content_researcher_skill, skill_creator]
)

root_agent = Agent(
    model="gemini-2.5-flash",
    name="blog_skills_agent",
    description="A blog-writing agent powered by reusable skills.",
    instruction=(
        "You are a blog-writing assistant with specialized skills.\n"
        "Load relevant skills to get detailed instructions.\n"
        "Use load_skill_resource to access reference materials.\n"
        "Follow each skill's step-by-step instructions.\n"
        "Always explain which skill you're using and why."
    ),
    tools=[skill_toolset],
)

파이썬

복사됨

목록의 첫 세 스킬은 SEO, 글쓰기, 연구를 처리하고요. 네 번째 skill_creator가 바로 팩토리 역할을 해요. 이 에이전트에게 "기술 블로그 서론을 작성하는 스킬을 만들어 줘" 라고 요청하면, 그 자리에서 새로운 SKILL.md를 생성해 줄 거예요.

# Generated by skill-creator
---
name: blog-intro-writer
description: Writes compelling technical blog introductions. Hooks the reader
  with a problem statement, establishes relevance, and previews what they will learn.
---

When writing a blog introduction, follow this structure:
1. Open with a specific problem the reader recognizes
2. State why it matters now (new release, scaling pain, common mistake)
3. Preview what the post covers in one sentence
4. Keep it under 100 words

일반 텍스트

복사됨

에이전트는 기존 작업에 seo-checklist와 blog-writer 스킬을 사용했어요. 하지만 자신이 가지고 있지 않은 기능이 필요했을 때는 스스로 하나를 작성했죠. 이 새로운 스킬도 동일한 agentskills.io 명세를 따르기 때문에, skills/blog-intro-writer/SKILL.md에 저장하고 다음 세션에서 load_skill_from_dir로 로드할 수 있어요.

SkillToolset은 진보적 공개에 직접적으로 매핑되는 세 가지 도구를 자동으로 생성해요: list_skills (L1, 자동 주입), load_skill (L2, 필요에 따라), 그리고 load_skill_resource (L3, 필요에 따라) 이렇게 말이죠.

시작하기 전 몇 가지 프로 팁

• 설명(description)은 여러분의 API 문서와 같아요. description 필드는 LLM이 스킬을 로드할지 말지 결정하기 위해 L1에서 보는 부분이에요. "블로그 게시물 SEO 최적화 체크리스트" 라고 하면 에이전트가 언제 활성화해야 할지 정확히 알 수 있죠. "유용한 스킬" 같은 설명은 그렇지 않아요.
• 인라인으로 시작해서 파일로 확장하세요. 너무 과하게 설계할 필요 없어요. 스킬이 10줄 이내의 지시사항으로 충분하다면 인라인으로 유지하세요. 참조 문서가 필요하거나 여러 에이전트에서 재사용하고 싶을 때 파일 기반 스킬로 옮겨가는 거죠.
• 생성된 스킬은 의존성처럼 검토하세요. 메타 스킬의 결과물은 에이전트의 행동이 돼요. 생성된 SKILL.md 파일도 코드 리뷰처럼 다루세요. 배포하기 전에 꼭 읽어보는 게 좋아요.

시작해 보세요

이제 여러분만의 스킬 팩토리를 만들 준비가 되셨나요? SkillToolset과 진보적 공개에 대해 이해하려면 ADK 스킬 문서를 확인해 보세요. 그리고 GitHub 저장소를 클론해서 ADK로 네 가지 패턴을 모두 직접 실행해 볼 수 있어요.

이전

다음