"AI 에이전트가 Google Cloud를 다룰 때 옆에 펴놓는, 구글 공인 업무 매뉴얼"입니다. 사람을 위한 문서가 아니라 에이전트가 읽도록 설계된 마크다운이라는 점이 핵심입니다.
아무리 똑똑한 신입(LLM)이라도 회사(GCP) 내부 규정은 모릅니다. "BigQuery 데이터셋은 이렇게 만들고", "삭제 명령은 반드시 결재(사용자 승인) 받고", "모르는 명령은 먼저 사내 위키(gcloud help)를 확인해라" — 이런 규칙을 부서별 챕터로 정리한 바인더가 이 레포입니다.
신입은 바인더 전체를 외우지 않습니다. 목차(스킬 이름과 설명)만 훑어두고, 해당 업무가 떨어졌을 때 그 챕터만 펼쳐 읽습니다. 이것이 뒤에서 설명할 Progressive Disclosure 구조입니다.
SKILL.md 하나이고, 필요하면 참고문서(references)·스크립트(scripts)·자산(assets)을 곁들입니다. Anthropic이 제안한 형식이 사실상 표준이 되어, 이제 구글까지 같은 형식으로 배포합니다.2025년 말 Anthropic이 anthropics/skills로 시작한 Agent Skills 형식은 커뮤니티 중심으로 퍼졌습니다. 그런데 구글이 자사 클라우드 제품 전체를 이 형식으로 공식 포장해서 내놓았다는 것은, 스킬이 일시적 유행이 아니라 에이전트 시대의 공식 문서 포맷으로 자리잡았다는 신호입니다. 2026년 TrendShift 상위권이 스킬 레포로 도배되는 흐름의 정점이라 볼 수 있습니다.
Google Cloud 공식 문서는 방대하지만 사람이 읽는 전제로 쓰였습니다. 에이전트가 그걸 통째로 읽으면 컨텍스트가 폭발하고, 안 읽으면 환각(hallucination)으로 존재하지 않는 gcloud 플래그를 지어냅니다. 이 레포는 그 간극을 메우는 "에이전트 최적화 요약본 + 안전수칙"입니다.
| 비교 대상 | 성격 | google/skills의 차별점 |
|---|---|---|
| anthropics/skills | 문서 작성·디자인 등 범용 스킬 | 특정 클라우드 제품에 깊게 특화. 제품팀이 직접 검증 |
| 커뮤니티 스킬 레포 | 개인이 만든 잡다한 스킬 | 외부 PR을 받지 않는 폐쇄 검증 체제 — 기술 정확성·보안을 내부 절차로 보증 |
| MCP 서버 | 도구(API 호출)를 제공 | 스킬은 도구가 아니라 지식과 절차를 제공 — 상호 보완 관계 (스킬 안에서 MCP 사용법도 안내) |
| GCP 공식 문서 | 사람용 전체 레퍼런스 | 에이전트용 압축본 + 가드레일(denylist, dry-run 강제) |
CONTRIBUTING.md가 이례적입니다 — 코드는 Apache-2.0으로 자유롭게 포크·리믹스하라면서, PR은 받지 않습니다. 스킬은 에이전트의 행동을 바꾸는 "명령서"라서, 잘못된 내용이 들어오면 곧바로 보안 사고(잘못된 IAM 조작 등)로 이어질 수 있기 때문입니다. 스킬 생태계의 공급망 보안 문제를 보여주는 사례입니다.
GitHub 언어 통계는 Python으로 찍히지만, 이 레포의 본체는 마크다운 문서입니다. 전체 198개 파일 중 대부분이 .md이고, Python·셸·YAML은 스킬에 동봉된 보조 도구입니다. 일반적인 백엔드/프론트엔드 구분이 없는 대신, 역할별로 나누면 이렇게 됩니다.
| 계층 | 기술 | 역할 |
|---|---|---|
| 지식 본문 | Markdown + YAML frontmatter | 스킬의 핵심. frontmatter의 name/description이 에이전트의 "이 스킬을 쓸까?" 판단 기준 |
| 실행 스크립트 | Python (google-genai, google-cloud-aiplatform SDK) | 평가 결과 비교, 튜닝 작업 모니터링 등 결정론적 작업을 코드로 위임 (eval-flywheel에 5개, tuning에 5개 등) |
| 환경 설정 | Bash 스크립트 | gcloud CLI 설정 자동화 (예: agent-platform-deploy의 config_gcloud_cli.sh) |
| 인프라 자산 | Kubernetes YAML, Terraform 예제 | GKE 골든패스 매니페스트(Autopilot, HPA/VPA, NetworkPolicy), IaC 레퍼런스 |
| 배포 채널 | npx skills CLI (skills.sh) | npx skills add google/skills 한 줄로 원하는 스킬만 골라 설치 |
| 대상 제품 | BigQuery, GKE, Cloud Run, Cloud SQL, AlloyDB, Firebase, Vertex/Agent Platform | 각 스킬이 다루는 Google Cloud 서비스 |
요리책(마크다운)이 본체이고, 책 부록으로 계량컵과 타이머(Python 스크립트), 미리 손질된 재료(YAML 자산)가 딸려오는 구성입니다. 요리책만 읽어도 되지만, 부록 도구를 쓰면 실수 없이 빠르게 만들 수 있습니다.
gke-basics의 SKILL.md는 20개 참고문서를 "시나리오 | 트리거 키워드 | 문서" 표로 정리합니다. 에이전트는 사용자의 말에서 "HPA", "private cluster" 같은 키워드를 보고 해당 문서만 집어 읽습니다. 사람용 문서의 목차를 기계가 분기하기 좋은 룩업 테이블로 바꾼 것입니다.
gcloud 스킬은 에이전트가 자율 실행하면 안 되는 명령을 명시적으로 금지합니다: gcloud * delete(파괴), gcloud billing *(과금), gcloud kms *(암호화 잠금), IAM 정책 변경(권한 탈취 위험). 또 실행 전 gcloud help <명령>으로 문법 검증을 강제하고, --dry-run이 있으면 반드시 먼저 돌리게 합니다.
"리스트 명령은 --limit=1 --format=json으로 스키마부터 확인하라", "--format=json(key1,key2)로 필요한 필드만 뽑아라" — 에이전트의 컨텍스트 창을 데이터 홍수로부터 지키는 절약 수칙이 스킬 본문에 박혀 있습니다.
eval-flywheel 스킬은 "실제 result 객체에서 읽지 않은 평가 점수를 절대 주장하지 말라"고 못 박고, 수정 전후를 compare_results.py로 비교해 증거를 내놓게 합니다. LLM이 대충 "고쳤습니다!"라고 둘러대는 고질병을 절차로 차단하는 설계입니다.
로컬 코드야 git으로 되돌리면 되지만, 클라우드에서 에이전트가 환각으로 delete를 날리면 복구 불가능한 데이터 손실이나 과금 폭탄이 됩니다. 이 레포의 모든 설계가 "능력 부여"보다 "사고 방지"에 무게를 두는 이유입니다.
스킬은 성격에 따라 4가지 유형으로 나뉩니다. 같은 형식이라도 담는 지식의 종류가 다릅니다.
| 유형 | 예시 | 담는 지식 |
|---|---|---|
| basics | bigquery-basics, gke-basics | 제품 하나의 개념·CLI·클라이언트 라이브러리·IaC·IAM을 망라한 기초 패키지 |
| recipe | recipe-onboarding, recipe-auth | "GCP 처음 세팅", "인증 붙이기" 같은 단발성 절차의 단계별 레시피 |
| waf | waf-security, waf-cost-optimization | Well-Architected Framework — 설계 검토 시 적용할 원칙 모음 (보안·신뢰성·비용·운영·성능·지속가능성) |
| agent-platform | inference, tuning, eval-flywheel, deploy | Vertex 기반 Agent Platform에서 모델 추론·파인튜닝·평가·배포하는 전문 워크플로우 |
README에는 19개 스킬이 실려 있지만 실제 폴더는 30개 가까이 됩니다(agent-platform-* 계열 다수가 미기재). "under active development"라는 안내처럼 빠르게 추가되는 중이며, 카탈로그 갱신이 따라가지 못하는 상태입니다. 레포를 평가할 때 README만 믿으면 안 되는 좋은 예시입니다.
모든 SKILL.md의 첫머리에는 YAML frontmatter가 있고, description이 사실상 스킬의 발동 조건입니다. gke-basics는 description 끝에 WHEN: create GKE cluster, provision GKE environment, ...처럼 트리거 문구를 직접 나열합니다. 스킬이 안 발동되는 문제의 90%는 description이 모호해서입니다.
# SKILL.md frontmatter 구조 (bigquery-basics 발췌)
---
name: bigquery-basics
description: >-
Manages datasets, tables, and jobs in BigQuery... Use when
you need to interact with BigQuery, run SQL queries, ...
---실습 아이디어: 자기가 만든 스킬의 description을 이 레포 스타일("무엇을 한다 + Use when 트리거 나열")로 고쳐보고 발동률 변화를 확인해보세요.
라우팅 테이블, 데이터 축소 수칙, "검증 전 실행 금지" 같은 장치는 모두 LLM의 약점(환각·컨텍스트 한계·과잉 확신)을 전제로 한 설계입니다. 좋은 에이전트 문서는 지식 전달보다 행동 통제에 가깝다는 것을 배울 수 있습니다.
gcloud 스킬의 수칙들(스키마 먼저 확인, 프로젝트 명시적 지정, 위치 플래그로 인터랙티브 프롬프트 방지, denylist)은 에이전트가 아닌 사람 엔지니어의 운영 체크리스트로도 그대로 쓸 수 있는 압축된 베스트 프랙티스입니다.
eval-flywheel 스킬은 데이터 준비 → 추론 → 채점 → 실패 분석 → 개선 5단계 루프를 정의하고, "메트릭 기준을 낮춰서 통과시키기", "한 번 고치고 끝내기" 같은 시간 낭비 지름길 목록까지 표로 제공합니다. LLM-as-judge 메트릭 선택 가이드(태스크 성공·궤적 품질·도구 사용·환각·근거성)는 어떤 에이전트 평가에도 응용 가능한 일반 지식입니다.
| 항목 | 요구사항 |
|---|---|
| 스킬 설치 | Node.js (npx skills CLI 실행용) — 텍스트 파일 복사라 사양 무관 |
| 에이전트 | Claude Code, Gemini CLI 등 Agent Skills 형식을 지원하는 도구 |
| 실전 활용 | Google Cloud 계정 + gcloud CLI 설치·인증. BigQuery·Cloud Run 등은 무료 등급(free tier)으로 실습 가능 |
| agent-platform 계열 | Python 3 + google-cloud-aiplatform, google-genai SDK. 평가·튜닝은 API 호출 비용 발생 |
스킬 자체는 무료지만, 스킬이 시키는 대로 클러스터를 만들면 GKE 요금이 나옵니다. 실습 후 리소스 삭제를 잊지 마세요(아이러니하게도 delete는 denylist라 에이전트가 자동으로 해주지 않습니다 — 의도된 안전장치입니다).
npx skills add google/skills로 bigquery-basics 하나만 골라 설치한 뒤, 에이전트에게 "BigQuery에 테이블 만들어줘"라고 시켜보세요. 에이전트가 스킬을 읽는 과정(어느 시점에 SKILL.md를 여는지, references를 추가로 여는지)을 로그로 관찰합니다.
gcloud / gke-basics / eval-flywheel 세 스킬의 SKILL.md를 나란히 놓고 ① description 트리거 문구 ② 본문에서 금지하는 행동 ③ 3계층 분리 방식을 비교표로 정리해보세요. 스킬 설계 감각이 빠르게 잡힙니다.
자주 쓰는 도구(예: Supabase, Docker)를 골라 이 레포의 basics 패턴 — 빠른 시작 4단계 + references 디렉토리 + 트리거 라우팅 표 — 그대로 모방한 스킬을 만들어보세요. 핵심은 본문을 100줄 이내로 압축하고 나머지를 references로 밀어내는 것입니다.
간단한 에이전트(예: 계산기 도구를 쓰는 챗봇)를 만들고, eval-flywheel 스킬의 5단계를 따라 평가 데이터셋 작성 → evaluate() 채점 → 실패 분석 → 프롬프트 수정 → compare_results.py로 전후 비교까지 완주해보세요. "증거 기반 개선 루프"를 몸으로 익히는 과제입니다.
| 주차 | 주제 | 할 일 |
|---|---|---|
| 1주차 | Agent Skills 형식 | agentskills.io 명세 정독 → anthropics/skills와 google/skills의 SKILL.md 스타일 비교 → 과제 1·2 수행 |
| 2주차 | gcloud + GCP 기초 | gcloud 스킬의 안전수칙을 직접 따라하며 BigQuery·Cloud Run 무료 등급 실습. --format/--filter 데이터 축소 문법 익히기 |
| 3주차 | 스킬 설계 실전 | 과제 3(자작 basics 스킬) 수행 → description 트리거 튜닝 → 동료/다른 에이전트에서 발동 테스트 |
| 4주차 | 에이전트 평가 | eval-flywheel의 메트릭 카탈로그 학습 → LLM-as-judge 원리 이해 → 과제 4로 평가-개선 루프 완주 |
| 용어 | 뜻 |
|---|---|
| Agent Skills | 에이전트에게 절차·규칙을 가르치는 폴더 단위 지식 패키지 표준. agentskills.io에 명세 공개 |
| SKILL.md | 스킬의 본체 파일. YAML frontmatter(name, description) + 마크다운 본문 |
| frontmatter | 마크다운 맨 위 --- 사이의 YAML 메타데이터. description이 스킬 발동 조건 역할 |
| Progressive Disclosure | 요약 → 본문 → 참고문서 순으로 필요한 만큼만 컨텍스트에 올리는 점진적 공개 설계 |
| gcloud | Google Cloud 공식 CLI. 이 레포의 모든 클라우드 스킬이 기본 도구로 삼음 |
| Denylist | 에이전트의 자율 실행을 금지하는 명령 목록 (delete, billing, kms, IAM 변경 등) |
| Dry Run | 실제 변경 없이 결과만 미리 보는 실행 모드. 스킬이 파괴적 명령 전 강제 |
| Well-Architected Framework (WAF) | 클라우드 설계 6대 원칙(보안·신뢰성·비용·운영·성능·지속가능성). 기둥별로 스킬 6개 존재 |
| Autopilot | 노드 관리를 구글이 대신하는 GKE 운영 모드. gke-basics가 권장하는 "골든패스" 기본값 |
| 골든패스 (Golden Path) | 조직이 검증해둔 권장 기본 구성. 고민 없이 따라가면 안전한 길 |
| LLM-as-judge | LLM이 다른 LLM의 응답을 채점하는 평가 기법. eval-flywheel 메트릭의 기반 |
| Eval Flywheel | 데이터 준비→추론→채점→실패 분석→개선을 반복하는 품질 개선 루프(플라이휠) |
| ADK (Agent Development Kit) | 구글의 에이전트 개발 프레임워크. 세션 트레이스를 평가 데이터셋으로 변환하는 스크립트 동봉 |
| MCP (Model Context Protocol) | 에이전트에게 도구(API)를 연결하는 프로토콜. 스킬(지식)과 상호 보완 — basics 스킬마다 mcp-usage.md 존재 |
| Workload Identity | GKE 파드에 키 파일 없이 GCP 권한을 부여하는 인증 방식. gke-security의 핵심 주제 |
| 서비스 계정 가장 (Impersonation) | 개발자 자격증명으로 서비스 계정 권한을 잠시 빌리는 방식. 로컬 에이전트에 권장 — 에이전트와 사람의 권한을 분리 |