2026년 11월 7일 GitHub Trending(전체·Python)에 google/skills가 올랐습니다. 이 글 작성 시점 API 기준 스타 22,869, forks 1,925, 라이선스 Apache-2.0, 최신 HEAD 993b979(2026-11-06 UTC, 모바일 광고 배너 deprecation 라벨 정리). GitHub Releases는 비어 있고, 배포 단위는 태그보다 index.json 카탈로그와 개별 SKILL.md의 metadata.version입니다.
이 글은 초보 튜토리얼이 아닙니다. Agent Skills(agentskills.io) 규약, 카탈로그 생성기·엔트리포인트 계약, gcloud 스킬의 leaf-help 가드레일, Claude/Codex 플러그인 마켓·MCP 동봉, 형제 레포 경계, 그리고 이 박스에서 npx skills 1.5.18로 돌린 list/install/use 실측을 실무자 기준으로 정리합니다. 어제 Opensource 딥다이브(vercel-labs/agent-browser, max-sixty/worktrunk)와는 계층이 다릅니다 — 브라우저는 AXTree, worktrunk는 저장소 슬롯, 이쪽은 도메인 절차서 카탈로그입니다. 11/5에 다룬 NVIDIA Auto Ontology(시맨틱 레이어)와도 겹치지 않습니다.
한 줄 정의와 핵심 숫자
google/skills는 Google 제품·기술(특히 Google Cloud)용 Agent Skills 모음입니다. 에이전트 하네스가 필요할 때만 절차서(SKILL.md)를 컨텍스트에 올리고, CLI·MCP·플러그인으로 같은 카탈로그를 배포합니다. README 설치 경로는 npx skills add google/skills(skills.sh)입니다.
| 항목 | 값 (이 글 검증) |
|---|---|
| 저장소 | google/skills |
| 버전 표기 | main@993b979 (2026-11-06); Releases 없음 |
| 라이선스 | Apache-2.0 (LICENSE 원문) |
| 스타 / forks | 22,869 / 1,925 (GitHub API 2026-11-07) |
| 카탈로그 | index.json skills[] 187 · 파일 128,869 B |
| 트리 SKILL.md | skills/ 아래 187 + plugins/ 중복 5 |
| skills CLI | 1.5.18 (npx skills --version) |
| 플러그인 마켓 | google-plugins 0.0.1 · 플러그인 17 |
| 문서/배포 | agentskills.io · skills.sh/google/skills |
왜 ‘스킬’인가: 문서 RAG와 다른 계약
일반 RAG는 문서를 검색해 인용합니다. Agent Skills는 언제 쓸지(description)·무엇을 강제할지(본문 지시)·무엇을 금지할지(CAUTION/denylist)를 frontmatter+마크다운으로 고정하고, 하네스가 스킬을 선택·로드하는 규약입니다. google/skills는 그 규약을 Google Cloud·Ads·Analytics·Identity 도메인에 대규모로 채운 공식 카탈로그에 가깝습니다.
| 축 | 일반 문서/RAG | Agent Skill (이 레포) |
|---|---|---|
| 단위 | 페이지·청크 | SKILL.md + references/ |
| 선택 신호 | 임베딩 유사도 | name + description (도구 설명란) |
| 안전장치 | 프롬프트에 의존 | 본문에 CAUTION·denylist·attribution |
| 배포 | 사이트/위키 | skills CLI · plugin marketplace · raw URL |
| 버전 | 페이지 개정 | frontmatter metadata.version + git SHA |
| 발견 | 검색창 | index.json entrypoint 목록 |
카탈로그 계약: index.json과 finding-google-skills
index.json은 생성기 산출물입니다(generator: This file is generated. Do not edit it by hand.). 각 항목은 name, description, entrypoint(raw.githubusercontent.com …/SKILL.md) 세 필드입니다. 이 글 시점 187개.
finding-google-skills(metadata.version 1.1.0)는 카탈로그를 바이트 단위로 가져오라고 강제합니다. 요약형 fetch·HTML 에러 페이지·인증서 실패를 성공으로 취급하지 말 것, 잘리면 알파벳 앞쪽 제품만 있는 것처럼 보이므로 jq/파일 저장 후 부분 읽기를 권합니다. 에이전트가 ‘스킬 목록을 기억한다’는 가정이 깨지도록 설계된 메타 스킬입니다.
| entrypoint 상위 경로 | SKILL.md 수 | 대표 도메인 |
|---|---|---|
| skills/cloud/ | 166 | GKE·BigQuery·Agent Platform·IAM·SecOps |
| skills/ads/ | 14 | Google Ads API·Mobile Ads·IMA |
| skills/developers/ | 2~3 | finding-google-skills·지식 검색·Rust 이주 |
| skills/analytics/ | 2 | GA Admin/Data API |
| skills/identity/ | 2 | DPoP·Sign in with Google |
| 이름 접두(대략) | 개수(이름 기준) | 해석 |
|---|---|---|
| google-* | 45 | 제품 온보딩·WAF·SCC 등 |
| gke-* | 42 | 클러스터·추론·TPU 트러블슈팅 |
| cloud-* | 19 | 모니터링·로깅·스토리지·Run |
| agent-platform-* | 15 | Gemini Enterprise Agent Platform |
| bigquery-* | 8 | SQL/AI·옵저버빌리티 |
| secops-* | 5 | 탐지·트리아지·헌팅 |
설명문에 agent/gemini/genkit/rag/model/tpu 등이 들어간 항목은 대략 95개로, 단순 ‘클라우드 치트시트’가 아니라 에이전트 플랫폼·추론·RAG·Genkit 축이 상당 비중을 차지합니다.
SKILL.md 해부: gcloud 1.0.3을 예시로
skills/cloud/gcloud/SKILL.md는 frontmatter에 name: gcloud, metadata.version: "1.0.3", category: CloudInfrastructureAndServices, 긴 description(언제 쓰고/언제 쓰지 말지)을 둡니다. 본문 최상단 CAUTION은 사전 학습된 gcloud 문법을 전부 stale로 선언하고, leaf 서브커맨드에 대해 gcloud help <leaf> 검증을 의무화합니다.
| 단계 | 규칙 | 실패 모드 |
|---|---|---|
| 1 Syntax | leaf help 필수 (parent help 불충분) | 환각 플래그 |
| 2 Parameter | 필수/옵션·dry-run 지원 여부 확인 | 파괴적 기본값 |
| 3 Dry-run | 지원 시 validate-only/dry-run 선행 | 즉시 apply |
| 4 AuthZ | denylist면 사용자 승인 요청 | 자율 실행 |
| 검색 금지 | gcloud 문법에 웹검색 금지 | 문서 미러와 불일치 |
| Attribution | references/attribution.md + metrics UA | 텔레메트리/정책 위반 |
같은 스킬 트리는 references/cli-usage.md, mcp-usage.md, attribution.md를 붙입니다. 박스에서 설치한 .agents/skills/gcloud는 파일 4개·SKILL.md 15,098 B였습니다. MCP 경로와 CLI 경로를 스킬이 동시에 안내하는 점이, ‘프롬프트 한 장’과 구분되는 실무 포인트입니다.
배포 표면: skills CLI · 플러그인 · MCP
README는 세 갈래를 제시합니다. (1) npx skills add google/skills로 스킬 패키지 설치·업데이트, (2) Claude Code/Codex 플러그인 마켓에 google/skills를 추가한 뒤 플러그인 설치, (3) Antigravity CLI의 URL 설치. 레포의 .claude-plugin/marketplace.json은 이름 google-plugins, metadata.version 0.0.1, 플러그인 17개(AlloyDB·BigQuery·Bigtable·Cloud SQL·Firestore·GCS·Looker·data-agent-kit 등). 다수는 별도 GoogleCloudPlatform/* 플러그인 레포를 ref로 가리키고, 이 모노레포의 plugins/cloud/google-cloud-developer가 코어 온보딩·gcloud·finding 스킬을 묶습니다.
| 표면 | 명령/경로 | 실무 메모 |
|---|---|---|
| skills.sh CLI | npx skills add|use|update|list|find |
박스 검증: 1.5.18 |
| 목록만 | npx skills add google/skills -l |
클론 후 Found 187 |
| 단건 설치 | -s gcloud -a '*' -y --copy |
심링크 대신 복사 |
| 프롬프트만 | skills use google/skills@gcloud |
미설치로 SKILL.md 주입 |
| Claude plugin | claude plugin marketplace add google/skills |
marketplace.json |
| Codex plugin | marketplace add 후 /plugins UI | .codex-plugin/ |
| MCP | plugin 내 .mcp.json / mcp_config.json | 스킬+도구 동봉 |
| 형제 레포 | 역할 | 이 글과의 경계 |
|---|---|---|
| google/skills | GCP·Ads 등 공식 카탈로그 | 본문 대상 |
| android/skills · flutter/skills · dart-lang/skills | 모바일/Dart 도메인 | 별도 카탈로그 |
| googlemaps/agent-skills | Maps Platform | 별도 |
| google/agents-cli (ADK) | Agent Development Kit 스킬 | 런타임/SDK 쪽 |
| firebase/agent-skills | Firestore 등 | Firebase 축 |
| mattpocock/skills (트렌딩 동시 노출) | 커뮤니티/교육형 스킬 | Google 공식과 출처 다름 |
저장소 구조
| 경로 | 역할 |
|---|---|
skills/{cloud,ads,analytics,developers,identity}/…/SKILL.md |
본 카탈로그 본체 |
index.json |
생성 카탈로그 (name/description/entrypoint) |
plugins/cloud/google-cloud-developer/ |
하네스별 plugin.json · MCP · 핵심 스킬 묶음 |
.claude-plugin/marketplace.json |
Claude 마켓 정의 (17 plugins) |
.agents/plugins/marketplace.json |
에이전트 인터페이스용 마켓 |
plugins/cloud/data-cloud/ |
데이터 클라우드 플러그인 문서 |
LICENSE · CONTRIBUTING.md |
Apache-2.0 · 이슈/스킬 개선 환영 |
박스 실측 (2026-11-07 KST)
환경: Node v20.19.2, npm 11.21.0, npx skills 1.5.18, 네트워크 허용 박스. GCP 계정·gcloud SDK 실행은 하지 않았고, 카탈로그 발견·설치·프롬프트 주입까지를 측정했습니다.
| 단계 | 명령 | 결과 |
|---|---|---|
| 버전 | npx skills --version |
1.5.18 |
| 목록 | npx skills add google/skills -l |
Found 187 skills · 3.677 s |
| 설치 | … -s gcloud -a '*' -y --copy |
7.01 s · rc 0 |
| 확산 | 설치 로그 → 경로 |
53 harness 디렉터리 · 파일 209 |
| 목록 확인 | npx skills list |
Project Skills: gcloud (Agents: Cursor +46 more) |
| use | npx skills use google/skills@gcloud |
5.224 s · SKILL.md 본문 주입 |
| 카탈로그 파일 | raw index.json | 128,869 B · skills 187 |
관찰 1: -a '*'는 감지된 모든 에이전트 디렉터리에 같은 스킬을 복사합니다. 모노레포/공용 워크스페이스에서는 노이즈가 크므로 실무에서는 타깃 하네스를 명시하는 편이 낫습니다. 관찰 2: skills use는 설치 없이 절차서를 프롬프트에 넣는 경로라, CI나 일회성 평가에 유리합니다. 관찰 3: list 단계가 레포를 클론하므로 첫 호출 지연의 대부분이 git fetch입니다(3.7초대).
# 재현 (이 박스와 동일 계열)
npx skills --version
npx skills add google/skills -l
npx skills add google/skills -s gcloud -a claude-code -y --copy # 타깃 한정 권장
npx skills use google/skills@gcloud
npx skills update -y
트레이드오프와 한계
| 이점 | 비용/함정 |
|---|---|
| 공식 절차서·가드레일 일괄 배포 | GCP/Google 제품 편향 — 멀티클라우드 중립 아님 |
| description 기반 도구 선택 | 187개 전량 로드 시 컨텍스트 폭발 (finder 패턴 필요) |
| leaf-help로 CLI 환각 감소 | 에이전트가 규칙을 무시하면 무효 — 런타임 강제력은 하네스 몫 |
| 플러그인+MCP 동봉 | 마켓 플러그인 다수가 외부 레포 ref — 버전 핀 관리 필요 |
| Apache-2.0 | Usage Attribution·텔레메트리 문구를 제품 정책과 맞춰야 함 |
| skills CLI 생태계 | 에이전트 디렉터리 난립(-a '*') — 저장소 오염 |
| 카탈로그 생성기 | index.json 수동 편집 금지 — 기여는 SKILL.md/이슈 경로 |
언제 쓰고, 언제 다른 층을 고를까
쓸 때: 코딩 에이전트가 GCP를 만질 때(특히 gcloud), Gemini Agent Platform/Genkit/GKE 추론 온보딩, SecOps·IAM 절차를 프롬프트가 아니라 버전 있는 스킬로 고정하고 싶을 때.
다른 층: 웹 UI 조작은 agent-browser, 병렬 작업 디렉터리는 worktrunk, 엔터프라이즈 시맨틱/텍스투SQL 신뢰층은 Auto Ontology(이미 별도 딥다이브), 일반 사내 위키 RAG는 스킬이 대체하지 않습니다. 스킬은 ‘검색 결과’가 아니라 ‘실행 규약’입니다.
모리크월드 편집 기준에서 google/skills는 에이전트 런타임이 아니라 도메인 절차서 공급망입니다. 오늘은 그 공급망의 카탈로그 크기(187), 가드레일 설계(gcloud), 배포 표면(CLI·플러그인·MCP), 그리고 박스에서 재현한 설치 지연을 기준으로 읽으면 됩니다.