Google 공식 Agent Skills 직접 써 보기 – Claude Code에 붙여 로그 쿼리부터 BigQuery 비용 점검까지

작성자 박 희찬 작성일 10월 14, 2026 조회수 23

안녕하세요. GS Neotek 박희찬 입니다.
2026년 4월 Google Cloud Next에서 Google이 공식 Agent Skills 저장소를 공개했습니다.
13개 스킬로 시작한 저장소는 반년 만에 156개까지 늘었습니다.

Agent Skills는 AI 코딩 에이전트에게 특정 제품을 다루는 방법을 알려 주는 문서 묶음입니다.
에이전트가 막연한 일반 지식으로 답하는 대신 Google 엔지니어가 정리한 규칙대로 쿼리를 쓰고, 점검하고, 문제를 진단하게 만드는 것이 목적입니다.

이번 글에서는 이 스킬을 Claude Code에 설치하고, 실제 운영 중인 프로젝트에서 로그 조회와 BigQuery 비용 점검을 맡겨 본 과정을 정리했습니다.

한눈에 보기

1. Agent Skills는 무엇인가

스킬 하나는 폴더 하나입니다.
핵심은 SKILL.md 파일이고, 필요하면 참고 문서(references/)와 실행 스크립트(scripts/)가 함께 들어 있습니다.

# 스킬 폴더 구조 예시 (cloud-logging-query-generation)
cloud-logging-query-generation/
├── SKILL.md                  # 언제 쓰는지(description) + 작업 규칙
└── references/
    ├── query_cloud_run.md    # 서비스별 쿼리 예시 20여 종
    ├── query_bigquery.md
    └── ...

에이전트는 평소에 각 스킬의 짧은 설명(description)만 들고 있다가, 요청이 그 설명과 맞을 때만 본문과 참고 문서를 읽습니다.
Google은 공개 글에서 MCP 서버를 많이 붙일 때 생기는 “context bloat”(컨텍스트가 불필요하게 커지는 문제)를 줄이는 방식이라고 설명합니다.

2. 설치하기

2-1. 전체 목록 확인

먼저 어떤 스킬이 있는지 목록만 받아 봤습니다.
저장소를 내려받아 스킬마다 이름과 설명을 보여 줍니다.

# 설치하지 않고 목록만 보기
npx skills add google/skills --list

◇  Source: https://github.com/google/skills.git
◇  Repository cloned
◇  Found 156 skills
◇  Available Skills
│    data-manager-api-audience-ingestion
│    ...
└  Use --skill <name> to install specific skills

2-2. 필요한 스킬만 골라 설치

-s로 스킬을, -a로 에이전트를 지정하면 그 에이전트의 스킬 폴더에 바로 들어갑니다.
설치 과정에서 스킬마다 보안 평가 결과(Gen·Socket·Snyk)를 보여 주는 점이 인상적이었습니다.

설치가 끝나면 프로젝트 폴더에 .claude/skills/와 skills-lock.json이 생깁니다.
lock 파일에 출처와 해시가 남아 팀원과 같은 버전을 맞추기 좋습니다.

2-3. 전부 설치하지 않은 이유

156개를 모두 설치하지는 않았습니다.
에이전트가 설치된 스킬의 설명을 매 세션마다 읽기 때문에, 쓰지 않는 스킬이 많을수록 그만큼 컨텍스트를 차지합니다.
그래서 자주 쓰는 운영·분석 스킬만 설치하고, 나머지는 다음에 소개할 finding-google-skills가 필요할 때 찾아 쓰게 했습니다.

3. 스킬을 찾아 주는 스킬 – finding-google-skills

이 스킬은 직접 작업을 하지 않습니다.
요청이 들어오면 저장소의 스킬 목록(index.json, 약 100KB, 156개 항목)을 내려받아 설명이 맞는 스킬을 최대 3개 고르고, 그 스킬의 본문만 받아 와서 따릅니다.

설치하지 않은 스킬도 필요할 때 불러 쓸 수 있다는 점이 핵심입니다.
요청 키워드에 따라 어떤 스킬이 후보로 잡히는지 확인해 봤습니다.

목록은 매번 새로 받아 쓰고 저장해 두지 않도록 규칙이 정해져 있습니다.
목록을 받지 못하면 받지 못했다고 답하게 되어 있어, 없는 스킬을 지어내는 일을 막습니다.

4. 실전 1 – Cloud Logging 쿼리 만들기

저희 팀은 Cloud Run Job으로 매월 GCP 보안 점검을 돌리고 있습니다.
Claude Code에 이렇게 요청했습니다.

지난 30일 동안 보안 점검 Cloud Run 잡에서 경고 이상 로그를 찾아줘

에이전트는 cloud-logging-query-generation 스킬을 불러 Cloud Run 참고 문서를 읽고 쿼리를 만들었습니다.
Job은 cloud_run_job 리소스 타입을 써야 한다는 규칙이 스킬에 들어 있어 리소스 타입은 정확했습니다.

# 1차 쿼리 (스킬이 생성)
resource.type="cloud_run_job" AND
resource.labels.job_name="<JOB_NAME>" AND
severity>=WARNING

# 결과
0 entries

0건이 나온 이유

문법은 맞았지만 결과가 0건이었습니다.
같은 잡의 로그 3,000건을 받아 보니 2,991건의 심각도(severity)가 DEFAULT였습니다.
애플리케이션이 Python logging으로 표준 오류(stderr)에 일반 텍스트를 쓰고 있어서, Cloud Logging 입장에서는 [WARNING]이 그냥 글자일 뿐이었습니다.

스킬에는 이런 경우를 위한 규칙도 있습니다.
정확한 필드를 모르면 SEARCH()로 전체 키워드 검색을 하고, 그 사실을 쿼리 주석으로 남기라는 것입니다.

# 2차 쿼리 (스킬 규칙대로 키워드 검색으로 변경)
-- severity 필드가 비어 있어(DEFAULT) 전역 키워드 검색 사용
resource.type="cloud_run_job" AND
resource.labels.job_name="<JOB_NAME>" AND
log_id("run.googleapis.com/stderr") AND
(SEARCH("WARNING") OR SEARCH("ERROR"))

# 결과
1441 entries

이번에는 원하던 결과가 나왔고, 점검 계정 권한이 빠진 프로젝트가 꽤 많다는 것도 확인했습니다.
스킬은 쿼리 문법과 리소스 타입은 지켜 주지만, 우리 로그가 구조화되어 있는지는 모릅니다.
심각도로 걸러 보려면 애플리케이션에서 JSON 구조화 로그를 쓰는 편이 좋겠다는 숙제도 얻었습니다.

5. 실전 2 – BigQuery 슬롯·비용 점검

bigquery-slot-cost-optimizer는 분석 스크립트까지 들어 있는 스킬입니다.
INFORMATION_SCHEMA.JOBS_BY_PROJECT에서 최근 쿼리 기록을 읽어 슬롯 사용량, 예상 비용, 병목 유형을 정리해 줍니다.

# 최근 30일 쿼리 분석 (가격은 공식 가격표 값을 직접 넣어야 함)
python3 scripts/slot_analyzer.py --project-id <PROJECT_ID> \
  --region region-us --days 30 --mode all \
  --ondemand-rate <USD_PER_TIB> --slot-hour-rate <USD_PER_SLOT_HOUR>

Queries Analyzed: 40 | Total Slot-Hours: 0.78
Bottlenecks Detected: Contention: 0 | Cartesian: 0 | Unpartitioned: 0

테스트 프로젝트라 쿼리는 40건, 예상 비용은 1달러 미만으로 작았습니다.
눈여겨본 것은 판정 결과입니다.
이 기간에 한 번에 20GB 넘게 읽은 빌링 데이터 쿼리가 여러 건 있었지만, 모두 파티션 조건(_PARTITIONTIME)을 걸었기 때문에 “파티션 없이 전체 스캔”으로 잡히지 않았습니다.

스킬은 결과를 세 가지 병목(슬롯 경합, 카티전 조인, 파티션 미사용 스캔)으로 분류하고, 해당하는 개선 절차 문서를 반드시 읽도록 되어 있습니다.
비용이 큰 운영 프로젝트에서 쓰면 “어떤 쿼리를 먼저 고칠지”를 빠르게 정할 수 있겠다고 느꼈습니다.

6. 써 보고 느낀 점

좋았던 점

• 1. 틀리기 쉬운 부분을 미리 막아 줍니다.
  Cloud Run Job과 서비스의 리소스 타입 구분, 작은따옴표 금지 같은 규칙이 스킬에 들어 있어 첫 쿼리부터 문법 오류가 없었습니다.
• 2. 필요한 만큼만 읽습니다.
  평소에는 설명 한 줄만 들고 있다가 요청이 맞을 때 본문을 읽기 때문에, 스킬을 여러 개 설치해도 대화가 무거워지지 않았습니다.
• 3. 스크립트가 있는 스킬은 바로 결과가 나옵니다.
  BigQuery 스킬은 분석 스크립트를 함께 제공해 쿼리를 직접 짜지 않아도 표로 결과를 받았습니다.

아쉬웠던 점

• 1. 우리 환경을 모르는 첫 답은 빗나갈 수 있습니다.
  심각도 필터가 0건을 낸 것처럼, 로그 형식 같은 환경 차이는 결과를 보고 한 번 더 고쳐야 할 수 있습니다.
• 2. 실행형 스킬은 에이전트 권한 그대로 동작합니다.
  조직 정책과 폴더를 실제로 만드는 스킬(foundation-builder)도 있어, 고객 환경에서는 내용을 먼저 읽고 쓰는 것이 필요할 수 있습니다.
• 3. 가격 같은 값은 사람이 넣어야 합니다.
  비용 분석 스크립트는 단가를 인자로 받기 때문에 공식 가격표를 직접 확인해야 합니다.
• 4. 전부 설치하면 오히려 무거워질 수 있습니다.
  156개를 다 설치하기보다 자주 쓰는 스킬과 finding-google-skills를 함께 두는 구성이 나아 보입니다.

7. 정리

Google 공식 Agent Skills는 설치가 간단하고, 지금 쓰는 에이전트(Claude Code 등)에 그대로 붙습니다.
직접 써 보니 결과의 정확도보다 “어떤 순서로, 무엇을 확인하며 일하는지”가 몸에 밴 동료를 한 명 붙여 주는 느낌에 가까웠습니다.

Google Cloud 운영 노하우를 필요할 때만 꺼내 쓰는 형태로 에이전트에게 빌려주는 도구였습니다.

다음 글에서는 이 저장소의 Well-Architected 스킬로 Terraform 코드의 아키텍처 리뷰를 받아 보고, 일부러 심어 둔 문제를 얼마나 찾는지 확인해 보겠습니다.