Gemini API 에이전트 스킬,
이 모델에서만 제대로 됩니다

Gemini API 에이전트 스킬이 뭔지부터 짚고 가겠습니다

코딩 에이전트의 가장 큰 약점은 학습 데이터가 특정 시점에서 끊긴다는 겁니다. Gemini 3.0이 학습될 때 이미 Gemini 3.1의 SDK는 존재하지 않았고, 새로운 thought circulation 파라미터 같은 최신 기능도 당연히 모릅니다. 그래서 에이전트가 열심히 코드를 짜도 구버전 패턴으로 채워지는 일이 반복됐습니다.

에이전트 스킬(Agent Skills)은 이 간격을 메우기 위해 나온 방식입니다. 핵심 원리는 간단합니다. 현재 어떤 모델이 있고, 어떤 SDK를 써야 하고, 기본 코드 예시는 어떻게 되는지를 담은 작은 텍스트 패키지를 에이전트 컨텍스트에 집어넣는 것입니다. 별도의 서버나 복잡한 설정 없이 npx 명령어 한 줄로 됩니다.

Google은 2026년 3월 25일 공식 개발자 블로그를 통해 gemini-api-dev 스킬을 공개했습니다. Gemini CLI, Cursor, Claude Code, Antigravity 등 주요 에이전트 환경에서 모두 쓸 수 있고, Vercel skills CLI와 Context7 두 가지 방식으로 설치할 수 있습니다. (출처: Google Developers Blog, 2026.03.25)

▲ 목차로 돌아가기

6.8%라는 수치가 말해주는 것

여기서부터가 다른 글에서 잘 안 다루는 부분입니다. 공식 발표문에 이런 내용이 나옵니다. Google은 Python과 TypeScript로 Gemini SDK 코드를 생성하는 117개의 평가 태스크를 만들어 “스킬 있을 때 vs 없을 때”를 직접 측정했습니다. (출처: Google Developers Blog, 2026.03.25)

이 수치가 시사하는 건 명확합니다. 스킬은 이미 추론 능력이 강한 모델에서만 제대로 작동합니다. Gemini 3.0은 스킬을 설치해도 87%에 머뭅니다. 기준치가 6.8%니 개선은 됐지만, Gemini 3.1 Pro의 96.6%와 거리가 있습니다. 단순히 스킬을 깔면 끝이라는 말은 틀렸습니다.

왜 이런 차이가 납니까? Google 공식 발표는 “강한 추론 능력이 뒷받침돼야 스킬이 효과를 낸다”고 직접 밝혔습니다. 스킬이 제시하는 문서를 보고, 필요한 정보를 찾아내 올바른 코드로 연결하는 능력 자체가 모델마다 다릅니다. 스킬은 재료를 제공할 뿐, 요리는 모델이 해야 합니다.

▲ 목차로 돌아가기

스킬을 설치해도 절반은 작동 안 하는 이유

Vercel이 직접 실험한 결과가 있습니다. Next.js 16 API를 대상으로 스킬과 AGENTS.md를 비교 측정했는데, 놀라운 수치가 나왔습니다. 스킬을 설치하기만 했을 때 — 명시적 지시 없이 — 에이전트가 스킬을 전혀 호출하지 않은 케이스가 56%였습니다. 스킬이 환경에 있어도 에이전트가 쓰기로 결정하지 않으면 아무런 소용이 없습니다. (출처: Vercel Blog, vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals, 2026.01.27)

이 결과가 의미하는 건 생각보다 묵직합니다. 현재 AI 모델들은 “언제 도구를 써야 하는지” 스스로 판단하는 신뢰성이 아직 불완전합니다. 스킬 방식 자체의 구조적 문제입니다. 에이전트가 스킬의 필요성을 느끼지 못하면 그냥 오래된 학습 데이터로 코드를 짭니다.

해결책은 있긴 합니다. AGENTS.md에 명시적으로 “코드 작성 전에 프로젝트 구조를 파악한 뒤 스킬을 사용하라”는 지시를 추가하면 호출률이 95% 이상으로 올라가고, 통과율도 53%에서 79%로 뜁니다. 다만 지시 문구 표현이 조금만 달라져도 결과가 크게 바뀌는 취약성이 있습니다. Vercel 실험에서 “스킬을 먼저 써라” vs “프로젝트 먼저 보고 스킬 써라”는 같은 스킬, 같은 문서를 쓰면서도 다른 결과를 냈습니다.

▲ 목차로 돌아가기

실제로 어떻게 설치하는지 따라가봤습니다

공식 문서를 따라가면 설치 경로는 두 가지입니다. Vercel skills CLI를 쓰는 방법과 Context7을 쓰는 방법입니다. 어떤 쪽을 써도 설치 대상 스킬은 동일합니다. (출처: ai.google.dev/gemini-api/docs/coding-agents)

Vercel skills CLI로 설치하는 방법

# 전역 설치 (모든 프로젝트에 적용)
npx skills add google-gemini/gemini-skills --skill gemini-api-dev --global
# 프로젝트별 설치 (현재 디렉토리에만 적용)
npx skills add google-gemini/gemini-skills --skill gemini-api-dev

Context7 방식으로 설치하는 방법

# 전체 목록 확인
npx ctx7 skills install /google-gemini/gemini-skills
# 특정 스킬만 설치
npx ctx7 skills install /google-gemini/gemini-skills gemini-api-dev

설치 후 제대로 됐는지 확인하는 가장 빠른 방법은 에이전트에게 “컨텍스트 캐싱을 Gemini API로 어떻게 구현해?”라고 물어보는 겁니다. cacheContent 또는 cachedContents.create처럼 최신 메서드를 사용한 코드가 나오면 스킬이 제대로 로드된 겁니다. 에이전트 환경마다 확인 방법이 다릅니다.

※ 대부분의 에이전트는 시작 시점에 스킬을 인덱싱합니다. 설치 후에는 IDE나 터미널을 완전히 재시작해야 인식됩니다. (출처: ai.google.dev/gemini-api/docs/coding-agents)

▲ 목차로 돌아가기

구글도 인정한 두 가지 한계

공식 블로그에 이례적으로 솔직한 내용이 담겨 있습니다. Google이 직접 스킬의 한계를 두 가지 꼽았습니다.

이 두 가지는 사실 구조적으로 연결돼 있습니다. 스킬의 정보가 낡아가는 속도와, 그 낡은 정보를 모델이 걸러낼 추론 능력이 없을 때 합쳐지면 — 아무것도 안 한 것보다 나빠질 수 있습니다. Google이 이미 MCP 방식도 병행 탐색 중이라고 밝힌 이유가 여기 있습니다.

▲ 목차로 돌아가기

AGENTS.md가 스킬보다 나은 케이스

Vercel이 Next.js 16 API 기준으로 직접 비교한 결과입니다. 조건별 통과율을 한 줄로 보면 이렇습니다.

스킬만 깔아두면 아무것도 안 한 것과 통과율이 같습니다. 에이전트가 알아서 스킬을 쓰기로 결정하지 않기 때문입니다. 반면 AGENTS.md에 8KB짜리 문서 인덱스를 직접 넣으면 에이전트가 “결정”을 내릴 필요가 없어집니다. 정보가 항상 컨텍스트에 들어 있으니까요. Build/Lint/Test 세 항목 모두 100%로 나왔습니다. (출처: Vercel Blog, 2026.01.27)

다만 이 두 방식은 경쟁 관계가 아닙니다. Google 공식 발표도 “스킬은 수직적, 특정 액션 중심 워크플로우에서 효과적이고, AGENTS.md는 수평적, 범용 지식 공급에 적합하다”고 정리했습니다. 실무에서는 둘을 같이 쓰는 게 현실적입니다. AGENTS.md로 기본 문서 인덱스를 깔고, 특정 마이그레이션 작업이나 버전 업그레이드는 전용 스킬로 처리하는 구조입니다.

▲ 목차로 돌아가기

자주 묻는 질문 (Q&A)

▲ 목차로 돌아가기

마치며

Gemini API 에이전트 스킬은 꽤 실용적인 도구입니다. 설치 자체는 명령어 한 줄로 끝나고, 제대로 작동하면 96.6%까지 성공률이 오릅니다. 근데 “설치했으니 다 됐다”는 생각이 위험합니다.

핵심만 요약하면 이렇습니다. 첫째, Gemini 3.1 Pro 이상 모델을 써야 제대로 작동합니다. 3.0에서는 스킬이 있어도 87%에 머뭅니다. 둘째, 아무런 지시 없이 설치만 하면 에이전트가 56% 케이스에서 스킬을 아예 호출 안 합니다. AGENTS.md에 명시적 지시를 추가해야 합니다. 셋째, 스킬 내용이 오래될 수 있습니다. Google도 업데이트 구조가 아직 불완전하다고 인정했습니다.

개인적으로 이 기능에서 가장 흥미로운 부분은 Google이 공식 블로그에 자사 도구의 한계를 스스로 써놨다는 점입니다. 성능 자랑만 하지 않고 “Vercel 방식이 더 효과적일 수 있다”는 것도 직접 언급했습니다. 그 정직함이 오히려 이 기능을 신뢰하게 만드는 부분이 있습니다.

Gemini CLI나 Cursor를 쓰면서 Gemini API를 다루는 프로젝트가 있다면 지금 바로 깔아볼 만합니다. 다만 깔기 전에 모델부터 확인하는 게 맞습니다.

▲ 목차로 돌아가기

📚 본 포스팅 참고 자료

1. Google Developers Blog — “Closing the knowledge gap with agent skills” (2026.03.25)
   https://developers.googleblog.com/closing-the-knowledge-gap-with-agent-skills/
2. Google Gemini API 공식 문서 — “Set up your coding assistant with Gemini MCP and Skills”
   https://ai.google.dev/gemini-api/docs/coding-agents
3. GitHub — google-gemini/gemini-skills 공식 저장소
   https://github.com/google-gemini/gemini-skills
4. Vercel Blog — “AGENTS.md Outperforms Skills in Our Agent Evals” (2026.01.27)
   https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals
5. The Decoder — “Google’s new Gemini API Agent Skill patches the knowledge gap AI models have with their own SDKs” (2026.03.28)
   https://the-decoder.com/googles-new-gemini-api-agent-skill-patches-the-knowledge-gap-ai-models-have-with-their-own-sdks/