(Day 3) 5-Day AI Agents: Intensive Vibe Coding Course With Google

AI 에이전트가 발전하면서 사람들은 점점 더 많은 일을 에이전트에게 맡기기 시작했다.

고객 문의 응대, 문서 작성, 코드 생성, 데이터 분석, 보고서 작성까지. 이제 에이전트는 단순한 챗봇이 아니라 실제 업무를 수행하는 시스템으로 진화하고 있다.

하지만 에이전트를 실제 환경에 투입해보면 몇 가지 공통적인 문제가 반복적으로 등장한다.

 

Google의 Agent Skills 백서는 이러한 문제를 크게 네 가지로 정리한다.

Problem

첫째, 지시사항이 많아질수록 성능이 나빠진다.

에이전트를 처음 만들 때는 간단하다.

 

"너는 고객 지원 담당자다."

 

하지만 시간이 지나면서 예외 상황과 업무 규칙이 추가된다.

• 환불 정책
• 배송 정책
• VIP 고객 처리 규칙
• 보안 규정
• 제품별 예외 사항

결국 수천 줄짜리 시스템 프롬프트가 만들어진다.

문제는 여기서 시작된다.

직관과 달리 LLM은 더 많은 정보를 넣는다고 항상 더 똑똑해지지 않는다.

오히려 관련 없는 정보가 계속 누적되면 중요한 내용을 놓치기 시작한다.

 

백서는 이를 Context Rot라고 부른다.

즉, 에이전트는 모든 것을 알고 있는 것처럼 보이지만 실제로는 너무 많은 정보를 한 번에 처리하느라 성능이 떨어지는 상태가 된다.

둘째, LLM은 '무엇'은 알지만 '어떻게'는 기억하지 못한다.

현재의 LLM은 사실을 기억하는 데는 꽤 뛰어나다.

 

예를 들어,

• 파이썬 문법
• 환율 정보
• 역사적 사건

같은 지식을 알고 있다.

 

하지만 실제 업무는 지식만으로 이루어지지 않는다.

 

예를 들어 고객 환불 요청이 들어왔다고 가정해보자.

1. 주문 조회
2. 중복 결제 확인
3. 환불 승인
4. 고객 안내

이 과정은 단순한 지식이 아니라 절차다.

 

사람은 이런 업무를 반복하면서 "어떻게 처리하는지"를 기억한다.

이를 Procedural Memory(절차 기억)라고 부른다.

백서는 Agent Skills를 LLM에게 제공되는 최초의 실질적인 Procedural Memory 메커니즘으로 설명한다.

셋째, 모든 문제를 멀티 에이전트로 해결하려 했다.

AI 에이전트 아키텍처는 멀티 에이전트가 유행이었다.

Router Agent
 ├─ HR Agent
 ├─ Finance Agent
 ├─ Support Agent
 └─ Research Agent

 

새로운 업무가 생기면 새로운 Agent를 추가했다.

 

하지만 시간이 지나면서 문제가 발생한다.

• 관리해야 할 Agent 증가
• 복잡한 오케스트레이션
• 배포 및 운영 비용 증가
• 평가(Evaluation) 복잡도 증가

물론 멀티 에이전트는 여전히 필요한 경우가 있다.

하지만 많은 경우 단지 "전문성을 추가하고 싶다"는 이유만으로 새로운 Agent를 만드는 것은 과한 해결책일 수 있다.

넷째, AI 생태계는 멀티 벤더 환경이다.

기업들은 하나의 AI 플랫폼만 사용하지 않는다.

• Claude
• Gemini
• OpenAI
• 자체 Agent Runtime

여러 시스템이 함께 존재한다.

 

그렇다면 특정 에이전트 플랫폼에 종속된 방식으로 업무 노하우를 저장하는 것은 좋은 전략이 아니다.

조직이 축적한 업무 지식은 어떤 에이전트에서도 재사용할 수 있어야 한다.

Agent Skills

Agent Skills는 이 네 가지 문제를 해결하기 위해 등장했으며, 놀라울 정도로 단순한 구조를 가진다.

 

하나의 폴더와 하나의 SKILL.md 파일.

하지만 그 안에는 특정 업무를 수행하는 절차, 규칙, 노하우, 그리고 필요한 도구 사용 방법이 담겨 있다.

 

필요한 순간에만 로드되고, 범용 에이전트를 특정 분야의 전문가처럼 행동하게 만들며, 어떤 Agent Runtime에서도 재사용할 수 있다.

가장 중요한 개념은 Progressive Disclosure, 점진적 공개다.

 

말 그대로 필요한 정보만 단계적으로 공개한다는 뜻이다.

 

Skill은 세 단계로 로드된다.

1단계: Metadata

항상 로드되는 것은 skill의 이름과 설명뿐이다.

이 설명은 모델이 어떤 skill을 사용할지 판단하는 라우팅 정보다.

2단계: SKILL.md 

사용자의 요청이 skill의 설명과 맞아떨어질 때만 SKILL.md 본문이 로드된다.

3단계: Bundled Resource

더 깊은 정보가 필요할 때만 추가 파일을 사용한다.

이 모든 정보는 처음부터 모델의 컨텍스트에 들어가지 않으며 필요한 순간에만 열린다.

이것이 Agent Skills가 Context Rot을 줄이는 핵심 방식이다.

SKILL.md에서 가장 중요한 것은 Description이다.

Agent Skill을 만들 때 많은 사람이 본문을 먼저 신경 쓴다.

하지만 백서에서 특히 강조하는 부분은 description이다.

왜냐하면 모델은 Skill을 사용할지 말지 결정할 때 가장 먼저 description을 보기 때문이다.

다시 말해 description은 단순한 설명문이 아니다.

Skill의 라우팅 알고리즘이다.

 

좋지 않은 description은 다음과 같다.

"helps with documents"

너무 모호하다.

 

좋은 description에는 세 가지가 들어간다.

• 첫째, 이 skill이 무엇을 하는지.
• 둘째, 언제 사용해야 하는지.
• 셋째, 언제 사용하면 안 되는지.

이 세 가지가 명확해야 Skill이 너무 넓게 실행되거나, 필요한 순간에 실행되지 않는 문제를 줄일 수 있다.

SKILL.md vs AGENTS.md

또 하나 헷갈리기 쉬운 개념이 AGENTS.md다.

 

AGENTS.md는 프로젝트 안에서 에이전트가 따라야 할 기본 규칙을 담는 파일이다.

 

예를 들어 소프트웨어 프로젝트라면 다음과 같은 내용이 들어갈 수 있다.

- 이 프로젝트는 TypeScript를 사용한다.
- 테스트는 npm test로 실행한다.
- API 코드는 src/api 아래에 둔다.
- PR을 만들기 전에 lint를 통과해야 한다.

 

이런 정보는 특정 작업에만 필요한 것이 아니라 프로젝트 전반에서 계속 필요한 기본 맥락이다.

 

따라서 AGENTS.md는 보통 항상 로드되는 반면, Skill은 특정 작업이 필요할 때만 로드된다.

 

좋은 구조는 둘을 함께 쓰는 것으로, AGENTS.md에는 프로젝트 전체에 필요한 짧은 규칙만 두며 세부적인 업무 절차는 skill로 분리하는 것이다.

 

중요한 점은 Agent Skills가 멀티 에이전트를 대체하는 만능 해결책은 아니라는 것이다.

멀티 에이전트가 필요한 경우는 여전히 존재한다.

 

예를 들어,

• 서로 다른 권한 체계가 필요한 경우
• 병렬 작업이 중요한 경우
• 독립적인 검토자와 실행자가 필요한 경우
• 서로 다른 모델을 조합해야 하는 경우
• 보안 경계가 명확히 분리되어야 하는 경우

이런 상황에서는 멀티 에이전트 구조가 적합하다.

 

하지만 단순히 "업무별 전문성"을 추가하기 위해 매번 새로운 Agent를 만드는 것은 과할 수 있다.

이때 Agent Skills가 더 가볍고 유지보수하기 쉬운 선택지가 된다.

Google Antigravity

Antigravity에서 Skills가 어떻게 쓰이는지 실습해보자.

 

먼저 antigravity-skills 레포를 다운받아주고,

git clone https://github.com/rominirani/antigravity-skills

 

아래 폴더 4개를 프로젝트 폴더 <project-root>/.agents/skills/에 옮겨준다.

• git-commit-formatter
• license-header-adder
• database-schema-validator
• json-to-pydantic

Antigravity를 실행시켜서 어떤 skill들을 사용할 수 있는지 물어보면, 방금 옮겨준 친구들을 확인할 수 있다.

/skills 커맨드로도 확인 가능하다.

1. git-commit-formatter

개발하면서 커밋 메세지를 일일히 작성하고, 작성 형식을 맞추는 것은 귀찮은 일이다.

이 스킬은 정해진 포맷대로 커밋 메세지를 작성한다.

git-commit-formatter/
└── SKILL.md  (Instructions only)

# SKILL.md
---
name: git-commit-formatter
description: Formats git commit messages according to Conventional Commits specification. Use this when the user asks to commit changes or write a commit message.
---

Git Commit Formatter Skill

When writing a git commit message, you MUST follow the Conventional Commits specification.

Format
`<type>[optional scope]: <description>`

Allowed Types
- **feat**: A new feature
- **fix**: A bug fix
- **docs**: Documentation only changes
- **style**: Changes that do not affect the meaning of the code (white-space, formatting, etc)
- **refactor**: A code change that neither fixes a bug nor adds a feature
- **perf**: A code change that improves performance
- **test**: Adding missing tests or correcting existing tests
- **chore**: Changes to the build process or auxiliary tools and libraries such as documentation generation

Instructions
1. Analyze the changes to determine the primary `type`.
2. Identify the `scope` if applicable (e.g., specific component or file).
3. Write a concise `description` in an imperative mood (e.g., "add feature" not "added feature").
4. If there are breaking changes, add a footer starting with `BREAKING CHANGE:`.

Example
`feat(auth): implement login with google`

 

 

로그인을 위한 auth.py 코드 제작과 커밋을 맡기면,

아래와 같이 "feat(auth): add login function" 메세지로 커밋한 것을 확인할 수 있다.

Google Login 기능을 넣도록 코드를 수정하고,

수정된 사항을 올리고 커밋하도록 만들면, 해당 내용을 수행한다.

2. license-header-adder

기업 프로젝트의 모든 소스 파일에는 특정 20줄짜리 Apache 2.0 라이선스 헤더가 필요할 수 있다.

이 정적 텍스트를 프롬프트에 직접 넣는 것은 비효율적이며 필요할 때 읽는 것이 좋다. 

license-header-adder/
├── SKILL.md
└── resources/
   └── HEADER_TEMPLATE.txt  (The heavy text)

 

헤더를 저장해두면, 해당 내용을 바탕으로 라이선스를 작성한다.

# SKILL.md
---
name: license-header-adder
description: Adds the standard open-source license header to new source files. Use involves creating new code files that require copyright attribution.
---

# License Header Adder Skill

This skill ensures that all new source files have the correct copyright header.

## Instructions

1. **Read the Template**:
  First, read the content of the header template file located at `resources/HEADER_TEMPLATE.txt`.

2. **Prepend to File**:
  When creating a new file (e.g., `.py`, `.java`, `.js`, `.ts`, `.go`), prepend the `target_file` content with the template content.

3. **Modify Comment Syntax**:
  - For C-style languages (Java, JS, TS, C++), keep the `/* ... */` block as is.
  - For Python, Shell, or YAML, convert the block to use `#` comments.
  - For HTML/XML, use `<!-- ... -->`.

 

아래와 같이 파이썬 코드 작성을 맡겨보자.

아래와 같이 라이센스를 코드에 포함시킨 것을 확인할 수 있다.

3. json-to-pydantic

JSON API 응답과 같은 느슨한 데이터를 Pydantic 모델과 같은 엄격한 코드로 변환하는 과정에는 수십 가지의 결정이 필요하다. 

클래스 이름,  Optional 사용 여부 등의 규칙을 일일이 적는 것은 지루하고 오류가 발생하기 쉽다.

json-to-pydantic/
├── SKILL.md
└── examples/
   ├── input_data.json   (The Before State)
   └── output_model.py   (The After State)

# SKILL.md
---
name: json-to-pydantic
description: Converts JSON data snippets into Python Pydantic data models.
---

# JSON to Pydantic Skill

This skill helps convert raw JSON data or API responses into structured, strongly-typed Python classes using Pydantic.

Instructions

1. **Analyze the Input**: Look at the JSON object provided by the user.
2. **Infer Types**:
  - `string` -> `str`
  - `number` -> `int` or `float`
  - `boolean` -> `bool`
  - `array` -> `List[Type]`
  - `null` -> `Optional[Type]`
  - Nested Objects -> Create a separate sub-class.
 
3. **Follow the Example**:
  Review `examples/` to see how to structure the output code. notice how nested dictionaries like `preferences` are extracted into their own class.
 
  - Input: `examples/input_data.json`
  - Output: `examples/output_model.py`

Style Guidelines
- Use `PascalCase` for class names.
- Use type hints (`List`, `Optional`) from `typing` module.
- If a field can be missing or null, default it to `None`.

 

먼저 product.json 파일을 만들어주고, JSON 데이터를 구조화된 Pydantic 클래스로 변환해보면

아래와 같이 모델이 만들어진 것을 확인할 수 있다.

4. database-schema-validator

LLM에게 이 스키마가 안전한지 물으면, 중요한 기본 키가 누락되었더라도 SQL이 올바르다는 이유만으로 모든 것이 괜찮다고 답할 수 있다.

이제 이 검사를 결정론적인 스크립트에 위임해 보겠다.

데이터베이스 스키마 유효성 검사 스킬은 에이전트가 우리가 작성한 Python 스크립트를 실행하도록 라우팅한다.

database-schema-validator/
├── SKILL.md
└── scripts/
   └── validate_schema.py  (The Validator)

# SKILL.md
---
name: database-schema-validator
description: Validates SQL schema files for compliance with internal safety and naming policies.
---

# Database Schema Validator Skill

This skill ensures that all SQL files provided by the user comply with our strict database standards.

Policies Enforced
1. **Safety**: No `DROP TABLE` statements.
2. **Naming**: All tables must use `snake_case`.
3. **Structure**: Every table must have an `id` column as PRIMARY KEY.

Instructions

1. **Do not read the file manually** to check for errors. The rules are complex and easily missed by eye.
2. **Run the Validation Script**:
  Use the `run_command` tool to execute the python script provided in the `scripts/` folder against the user's file.
 
  `python scripts/validate_schema.py <path_to_user_file>`

3. **Interpret Output**:
  - If the script returns **exit code 0**: Tell the user the schema looks good.
  - If the script returns **exit code 1**: Report the specific error messages printed by the script to the user and suggest fixes.

 

먼저 에이전트에게 정책 위반 사항이 여러 개 포함된 bad_schema.sql이라는 새 파일을 생성하도록 요청한다.

위의 스키마 파일은 세 가지 정책을 모두 위반한다.

금지된 DROP TABLE 문을 사용했고, userProfile 테이블 이름에 camelCase를 사용했으며, posts 테이블에서 id 기본 키를 누락했다.

database-schema-validator 스킬을 활성화하여 Python 유효성 검사 스크립트를 파일에 대해 실행하면,

다음과 같이 오류를 보고하고 스크립트에서 발견된 구체적인 오류를 알려준다.