Google Cloud Skill Registry: 엔지니어를 위한 실용 가이드

서론

만약 두세 개 이상의 AI 에이전트를 구축해 본 경험이 있다면, 아마 이 고통을 이미 느껴보셨을 겁니다. 모든 에이전트는 '노하우'가 필요합니다. BigQuery를 올바르게 쿼리하는 방법, 팀이 GKE 클러스터 이름을 지정하는 방식, 티켓을 제출하는 방법, 비용 보고서를 실행하는 방법 등 말이죠. 그리고 매번마다 누군가는 똑같은 프롬프트 스니펫과 헬퍼 스크립트를 또 다른 리포지토리에 복사합니다.

몇 달 후에는 같은 지침의 약간씩 다른 버전 다섯 개가 생겨나고, 어느 것이 최신인지 아무도 모릅니다. 게다가 에이전트의 컨텍스트 창은 현재 작업에 필요하지 않은 것들로 가득 차게 됩니다.

Google Cloud의 Skill Registry (Gemini Enterprise Agent Platform의 일부이며 현재 Preview 단계)는 바로 이 문제에 초점을 맞추고 있습니다. 이것을 npm이나 pip 패키지 대신 에이전트 스킬용 사설 패키지 레지스트리로 생각하시면 됩니다. 스킬을 한 번 게시하면 버전 관리가 되고, 에이전트는 사용자의 요청이 실제로 필요할 때만 검색하고 로드할 수 있게 됩니다.

본 포스팅에서는 Skill Registry가 무엇인지, 구성 요소들이 어떻게 연결되는지, 스킬 패키지가 어떤 모습인지, 그리고 작동하는 curl 명령과 함께 전체 REST API 흐름을 안내해 드릴 것입니다. 또한 Preview 서비스를 기반으로 구축하기 전에 알아야 할 제한 사항과 주의할 점(gotchas)도 알려드릴 테니 참고하세요.

Skill Registry가 실제로 무엇인지

Skill Registry는 에이전트 스킬을 위한 안전하고 사설적이며 낮은 지연 시간의 저장소입니다. '스킬'이란 자체적으로 완결된 패키지입니다. SKILL.md 파일에 담긴 지침과, 에이전트가 특정 작업을 잘 수행하는 데 필요한 모든 스크립트, 참고 문서 및 자산들이 포함됩니다.

API는 단 두 가지 리소스를 중심으로 구축되어 있으며, 이 두 가지만 이해하면 나머지 API도 파악하기 쉽습니다.

따라서 Skill은 사용자가 계속 편집하는 것이며, 의미 있는 변경 사항이 생길 때마다 되돌아가 검사할 수 있는 리비전(revision)을 남깁니다. Cloud Run 서비스와 리비전을 다뤄본 경험이 있다면, 이 모델이 매우 친숙하게 느껴질 것입니다.

무료로 얻을 수 있는 Skill도 하나 있습니다: gcp-skill-registry. 이것은 Google이 관리하고 버전 관리하는 내장(built-in) Skill로, 에이전트가 Skill Registry 자체와 대화하는 방법을 학습시킵니다. 이를 통해 에이전트는 Skill을 검색하고, 새로운 Skill을 생성하며, 사용 가능한 것을 관리할 수 있습니다. 작은 놀라움 하나: Google은 첫 API 호출 시에 이 Skill을 프로비저닝(provision)하므로, 첫 번째 응답에는 목록으로 나타나지 않습니다. 두 번째 호출부터 표시됩니다.

작동 방식

Skill Registry를 통하는 경로는 실제로 두 가지가 있습니다. Skill 작성자를 위한 '게시 경로(publish path)'와 이를 사용하는 에이전트를 위한 '검색 경로(retrieval path)'입니다.

  PUBLISH PATH                     SKILL REGISTRY (one region)             RETRIEVAL PATH

+----------------------+        +-----------------------------------+ 
... 

게시 경로에서는 압축된, base64로 인코딩된 Skill을 API로 전송합니다. 유효성 검사(Validation)는 장기 실행 작업(long-running operation)으로 백그라운드에서 실행되며, 오직 유효한 패키지만 새로운 불변 리비전(immutable revision)을 가진 Skill이 됩니다. 검색 경로에서는 에이전트(ADK 또는 Managed Agents API로 구축됨)가 자신이 필요로 하는 것을 일반적인 말로 설명하면, RetrieveSkills는 각 Skill의 표시 이름(display name)과 설명을 기반으로 의미적 일치(semantic match)를 수행하고, 에이전트는 적합한 Skill만 로드합니다. Skill이 에이전트에 연결되면, 해당 Skill의 SKILL_ID가 에이전트가 보는 폴더 이름이 됩니다.

Skill의 구성 요소

Skill은 단순히 압축된 폴더입니다. 반드시 있어야 하는 파일은 SKILL.md 하나뿐입니다. 나머지는 선택 사항이지만, 문서(docs) 패키지는 전형적인 Skill을 다음과 같이 구성합니다:

finops-cost-report/
├── SKILL.md          # 필수: 프론트 매터 + 지침
├── scripts/          # 에이전트가 실행할 수 있는 헬퍼 코드
... 

SKILL.md는 YAML 프론트 매터로 시작하고 그 뒤에 일반 마크다운(plain Markdown) 형식의 지침을 포함합니다. 여기 작은 예시가 있습니다:

name: finops-cost-report
description: BigQuery 결제 내보내기(billing export)를 사용하여 프로젝트별 월간 Google Cloud 비용 보고서를 생성합니다. 사용자가 지출, 비용 추세 또는 주요 비용 발생 원인에 대해 문의할 때 사용하세요.
...

프론트 매터(front matter)에는 엄격한 규칙이 있으며, 레지스트리가 이를 확인합니다:

• name: 필수 항목이며, 64자까지 가능하고 소문자 문자, 숫자 및 하이픈만 허용하며, 하이픈으로 시작하거나 끝날 수 없습니다.
• description: 필수 항목이며, 1,024자까지 가능합니다. 이 부분은 신중하게 작성해야 합니다. 왜냐하면 시맨틱 검색(semantic search)에서 사용자가 요청과 해당 스킬이 일치하는지 판단하는 데 사용하기 때문입니다.
• license: 선택 사항이며, 1,024자까지 가능합니다.
• The instructions body: 최대 500,000자까지 가능합니다.

어떤 종류의 검색(retrieval)을 다뤄본 경험에서 얻은 팁: 코드를 설명하는 방식이 아니라 사용자가 자신의 문제를 설명하는 방식으로 설명을 작성하세요. "지출이나 비용 추세에 대해 문의할 때 사용한다"는 문구가 "결제 데이터에 SQL 집계 실행"보다 훨씬 더 잘 일치합니다.

실제 사례의 경우, Google은 Google Cloud Skills repository에 샘플 SKILL.md 파일을 보관하고 있습니다.

실습: REST API를 사용한 전체 라이프사이클

문서에는 Python 및 Node.js 샘플 외에도 Colab에서 열 수 있는 "Skill Registry 소개(Intro to Skill Registry)" 노트북도 나와 있습니다. 저는 여기서 curl을 사용하는 것이, 실제로 어떤 데이터가 전송되는지 정확하게 보여주기 때문에 이를 고수하겠습니다.

0단계: 프로젝트 설정하기

1. Google Cloud 프로젝트를 선택하거나 생성하고 결제가 활성화되어 있는지 확인합니다.
2. Agent Platform API (aiplatform.googleapis.com)를 활성화합니다.
3. 본인에게 roles/aiplatform.user (읽기 전용의 경우 roles/aiplatform.viewer)와 roles/serviceusage.serviceUsageConsumer 역할을 부여합니다. Skill Registry는 프로젝트 수준의 IAM을 상속받으므로, 별도로 학습해야 할 권한 모델은 없습니다.

그런 다음 몇 가지 변수를 설정하여 나머지 명령어들이 읽기 쉽게 유지되도록 합니다:

export PROJECT_ID="my-agent-project"
export LOCATION="us-central1"   # 또는 europe-west4, us-east5
export SKILL_ID="finops-cost-report"
...

1단계: 스킬 패키징하기

API는 전체 스킬 폴더를 단일 라인 base64 문자열로 인코딩된 zip 파일 형태로 기대합니다.

cd finops-cost-report
zip -r skill.zip SKILL.md scripts/ references/ assets/
base64 -w 0 skill.zip > skill.b64   # macOS의 경우: base64 -i skill.zip -o skill.b64

Step 2: 스킬 생성하기

압축된 스킬은 최대 10MB에 달할 수 있어, 셸 명령어 내부에 붙여넣기에는 너무 길습니다. 그래서 먼저 JSON 본문을 파일로 작성한 다음 curl을 해당 파일에 지정합니다.

cat > create.json <<EOF
{
  "displayName": "finops-cost-report",
...

SKILL_ID는 신중하게 선택해야 합니다. 1~63자 길이여야 하며, 소문자 알파벳, 숫자, 하이픈으로 구성되어야 하고, 문자로 시작해야 하며, gcp-로 시작할 수 없습니다 (Google에서 해당 접두사를 예약했기 때문입니다). 또한 영구적입니다: 한 번 사용하면 스킬을 삭제하더라도 계속 예약된 상태를 유지합니다. 그리고 SKILL_ID는 스킬이 에이전트에 연결될 때 폴더 이름이 되므로, 설명적인 이름은 모델이 이 스킬의 용도를 이해하는 데 실제로 도움이 됩니다.

Step 3: 장기 실행 작업 대기하기

생성(Create), 업데이트(Update), 삭제(Delete) 작업은 즉시 완료되지 않습니다. 대신 작업을 반환하며, zip 파일에 대한 유효성 검사는 백그라운드에서 이루어집니다. 응답에는 projects/PROJECT_NUMBER/locations/LOCATION/skills/SKILL_ID/operations/OPERATION_ID와 같은 이름이 포함됩니다. 이 작업이 완료(done)될 때까지 폴링(Poll)해야 합니다:

OP_NAME="projects/123/locations/us-central1/skills/finops-cost-report/operations/456"

curl -s -H "Authorization: Bearer ${TOKEN}" \
...

이 단계는 보이는 것보다 훨씬 중요합니다. 잘못된 zip 파일은 POST 요청에서 실패하지 않습니다. POST는 성공하고, 작업은 나중에 유효성 검사 오류와 함께 실패합니다. 만약 CI 파이프라인이 create 호출의 HTTP 상태만 확인한다면, 작동하지 않는 스킬에 대해서도 안심하고 녹색(green)으로 보고할 것입니다.

Step 4: 스킬 업데이트하기

업데이트는 PATCH 방식이며, updateMask에서 나열한 필드만 변경됩니다. 설명(description)만 수정하려면 zippedFilesystem을 제외하십시오.

Step 5: 리비전(revisions) 목록 가져오기 및 검사하기

# 이 리전의 모든 스킬 (이름, 표시 이름, 설명, 상태)
curl -s -H "Authorization: Bearer ${TOKEN}" "${BASE}/skills"

...

목록 호출(list call)은 다음과 같은 항목들을 반환합니다:

{
  "name": "projects/1234567890/locations/us-central1/skills/3456789012",
  "createTime": "2026-05-10T00:02:12.497720Z",
...

Step 6: 시맨틱 검색(semantic search)을 통해 스킬 찾기

이것이 가장 흥미로운 호출입니다. RetrieveSkills는 일반 언어 질의(plain-language query)를 받아 각 스킬의 표시 이름과 설명을 대상으로 일치 여부를 확인합니다. 이를 통해 에이전트가 모든 것을 미리 로드하는 대신 런타임(runtime)에 적절한 스킬을 선택할 수 있게 됩니다.

curl -s -G -H "Authorization: Bearer ${TOKEN}" \
  --data-urlencode "query=find skills to report on cloud spend" \
  "${BASE}/skills:retrieve"

Step 7: 스킬 삭제하기

삭제(Delete)는 해당 스킬과 그 모든 리비전을 제거하며, 이 또한 장기 실행 작업(long-running operation)입니다. 내장된 gcp- 스킬은 삭제할 수 없습니다.

curl -X DELETE -H "Authorization: Bearer ${TOKEN}" "${BASE}/skills/${SKILL_ID}"

참고: 중요한 내용을 스크립트화하기 전에는 항상 요청 경로(request paths)를 실제 문서를 통해 다시 확인해야 합니다. 특히 retrieve 경로는 프리뷰 API(Preview API)이므로 경로가 변경될 수 있습니다.

유효성 검사 규칙 치트 시트 (Validation rules cheat sheet)

모든 생성 또는 업데이트는 사용자의 zip 파일을 일련의 안전 점검(safety checks)을 거치게 합니다. 이들 중 대부분은 클래식한 zip 공격(zip bombs, path traversal, symlink tricks)을 차단하기 위한 것이며, 에이전트가 이러한 패키지에서 코드를 실행할 예정일 때 안심할 수 있는 부분입니다.

리전, 규정 준수 및 주의사항

Skill Registry는 현재 세 개의 리전에서 운영됩니다: us-central1 (아이오와), europe-west4 (네덜란드), 그리고 us-east5 (콜럼버스, 오하이오). 스킬은 특정 리전에 존재하므로, 에이전트가 다른 리전에서 실행될 경우 이를 고려하여 계획해야 합니다.

• 미리 보기(Preview) 버전입니다. 사전 GA(General Availability) 조건이 적용되며, 지원 범위가 제한적이고 API는 v1beta1입니다. 변경될 것을 예상해야 합니다.
• 아직 VPC-SC, CMEK 또는 HIPAA를 지원하지 않습니다. 규제 대상 워크로드(의료 등, 또는 VPC-SC 경계 뒤에 있는 모든 것)의 경우 현재로서는 장애 요인입니다.
• Skill ID는 영구적입니다. SKILL_ID는 삭제된 후에도 예약 상태가 유지되며, 문서에는 재사용 전에 24시간 대기 시간이 필요하다고 명시되어 있습니다. 어느 쪽이든, 공유 프로젝트에서 임시(throwaway) ID를 사용하지 마십시오.
• 검증은 비동기적입니다. 성공적인 POST 요청이 유효한 스킬을 의미하지는 않습니다. 항상 작업 상태를 폴링해야 합니다.
• 내장된 스킬의 로딩 시점이 늦습니다. gcp-skill-registry가 첫 번째 API 응답에 포함되지 않습니다.
• 검색 품질은 사용자에게 달려 있습니다. RetrieveSkills는 표시 이름(display name)과 설명(description)만 확인합니다. 모호한 설명은 에이전트가 절대 찾지 못하는 스킬을 의미할 수 있습니다.
• 스킬은 코드를 실행합니다. 레지스트리는 패키지 구조를 검사할 뿐, 실제 스크립트가 무엇을 하는지는 검사하지 않습니다. 스킬 코드는 에이전트의 자격 증명으로 실행되는 모든 코드와 동일한 방식으로 검토해야 합니다.

알아두면 좋은 또 다른 점은 Google이 Agent Registry를 통해 독립형 스킬(standalone skills)을 중앙에서 관리할 수 있도록 허용한다는 것입니다. 회사에서 많은 에이전트를 구축하고 있다면, 이 두 가지 모두를 살펴보고 어디서 스킬을 관리해야 할지 결정하십시오.

결론

Skill Registry는 오늘날 대부분의 팀들이 잘못 수행하는 작업(에이전트 리포지토리 간 프롬프트와 헬퍼 스크립트를 복사하는 행위)을 가져와 적절한 플랫폼 서비스로 변환합니다. 사용자는 불변의 개정판을 통한 버전 관리, 모든 패키지에 대한 보안 검사, 이미 이해하고 있는 IAM(Identity and Access Management), 그리고 에이전트가 필요한 것만 로드할 수 있게 하는 시맨틱 검색 기능을 얻게 됩니다.

아직 초기 단계입니다. Preview 라벨, 세 개의 리전만 지원하고 VPC-SC 및 CMEK 지원이 부족하다는 점을 감안할 때, 규제 대상의 프로덕션 워크로드를 아직 여기에 옮기지는 않을 것입니다. 하지만 에이전트 노하우를 위한 공유되고 관리되는 허브를 원하는 플랫폼 팀에게는 지금 주말 동안 직접 시간을 투자하여 경험해 볼 가치가 충분합니다. 그래야 GA(General Availability)가 되었을 때 준비될 수 있습니다.

제 조언은 이렇습니다. 팀이 이미 여기저기 복사해서 사용하고 있는 스킬 한두 개로 시작하세요. 정말 좋은 설명을 작성하고, 장시간 실행되는 작업 검사를 CI에 연결하며, RetrieveSkills가 이를 얼마나 잘 인식하는지 확인해 보세요.

여러분은 Skill Registry를 사용해 보셨나요, 아니면 에이전트 스킬을 다른 방식으로 관리하고 계신가요? 댓글로 어떻게 하는지 들려주시면 좋겠습니다.

자료