Android Skills 해부 — 에이전트에게 전문성을 주입하는 방법

들어가며 — 에이전트는 왜 삽질하는가

AI 코딩 에이전트에게 "기존 XML 레이아웃을 Jetpack Compose로 마이그레이션해줘"라고 시키면 어떤 일이 벌어질까? 에이전트는 Compose 코드 자체는 잘 짠다. 하지만 마이그레이션은 단순 변환이 아니다. 어떤 순서로 진행해야 하는지, 기존 View와 Compose를 혼용하는 과도기에 어떤 패턴을 써야 하는지, 테스트는 어떻게 바꿔야 하는지 — 이런 작업 절차는 코드 생성 능력만으로 해결되지 않는다. 에이전트는 시행착오를 반복하며 토큰을 쏟아붓고, 결과물의 품질은 들쑥날쑥해진다.

Google이 Android CLI와 함께 발표한 Android Skills는 이 문제에 대한 구조적인 해법이다. 그런데 더 흥미로운 건, Android Skills가 Google 독자 규격이 아니라 Agent Skills라는 오픈 표준 위에 만들어졌다는 점이다. 이 표준은 Anthropic이 처음 만들고, 지금은 30개 이상의 AI 도구가 채택하고 있다.

Agent Skills 오픈 표준 — 에이전트의 공통 언어

Android Skills를 이해하려면 먼저 그 기반인 Agent Skills 오픈 표준을 알아야 한다.

한 줄 정의

Agent Skills는 폴더 하나에 SKILL.md 파일을 담는 것이다. 이 파일에 메타데이터(이름, 설명)와 마크다운 지시문을 적으면, 호환되는 모든 에이전트가 이걸 읽고 실행할 수 있다.

my-skill/
├── SKILL.md          # 필수: 메타데이터 + 지시문
├── scripts/          # 선택: 실행 가능한 코드
├── references/       # 선택: 참조 문서
└── assets/           # 선택: 템플릿, 리소스

SKILL.md의 구조

SKILL.md 파일은 YAML frontmatter와 마크다운 본문으로 구성된다.

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

# PDF Processing

## When to use this skill
Use this skill when the user needs to work with PDF files...

## How to extract text
1. Use pdfplumber for text extraction...

frontmatter 필드는 이렇다:

필드	필수	설명
name	Yes	고유 식별자. 소문자+숫자+하이픈, 최대 64자
description	Yes	스킬이 뭘 하는지, 언제 쓰는지. 최대 1024자
license	No	라이선스 정보
compatibility	No	환경 요구사항 (특정 도구, 패키지 등)
metadata	No	임의의 key-value 메타데이터
allowed-tools	No	스킬이 사용할 수 있는 도구 목록 (실험적)

핵심은 description 필드다. 에이전트가 이 설명을 읽고 "이 스킬을 지금 써야 하나?"를 판단한다. 그래서 "Helps with PDFs" 같은 빈약한 설명은 안 되고, "PDF 파일에서 텍스트와 표를 추출하고, 폼을 채우고, 여러 PDF를 병합한다. 사용자가 PDF, 폼, 문서 추출을 언급할 때 사용"처럼 구체적으로 써야 한다.

핵심 메커니즘 — Progressive Disclosure

Agent Skills의 가장 중요한 설계 원칙은 Progressive Disclosure(점진적 노출)다. 에이전트의 컨텍스트 윈도우는 유한하다. 100개의 스킬을 전부 로딩하면 정작 중요한 작업에 쓸 토큰이 없다. 그래서 3단계로 나눠서 필요한 만큼만 로딩한다.

1단계: Discovery (시작 시, ~100 토큰/스킬)

에이전트가 시작되면, 프로젝트에 설치된 모든 스킬의 name과 description만 로딩한다. 스킬이 50개여도 약 5,000 토큰이면 충분하다. 이 단계에서 에이전트는 "어떤 스킬이 있는지"만 파악한다.

2단계: Activation (작업 매칭 시, <5,000 토큰 권장)

사용자의 요청이 특정 스킬의 description과 매칭되면, 에이전트가 해당 SKILL.md 본문 전체를 컨텍스트에 로딩한다. 여기에 구체적인 단계별 지시, 예시, 엣지 케이스 처리법이 담겨 있다.

3단계: Execution (필요 시, 가변)

지시문을 따르면서 필요할 때만 scripts/, references/, assets/ 디렉토리의 파일을 추가로 읽거나 실행한다.

이 구조의 핵심은 "필요할 때 필요한 만큼만"이다. 에이전트가 PDF 작업을 안 하고 있으면 PDF 스킬의 본문은 절대 로딩되지 않는다. 컨텍스트 윈도우를 최적으로 활용하면서도 수십 개의 전문 능력을 가용 상태로 유지할 수 있다.

Android Skills — 실제로 뭐가 있나

Google은 이 오픈 표준 위에 Android 전용 스킬 6개를 만들어 GitHub 저장소에 공개했다.

스킬	카테고리	하는 일
Migrate to Compose	UI/Design	XML 뷰 기반 UI를 Jetpack Compose로 마이그레이션
Make app edge-to-edge	UI/Design	edge-to-edge 레이아웃으로 앱 UI 현대화
Upgrade to AGP 9	Build	Android Gradle Plugin 9로 프로젝트 업그레이드
Audit R8 configuration	Performance	R8 코드 축소 설정 감사 및 성능 최적화
Set up Navigation 3	Architecture	Navigation 3 프레임워크 설정 및 best practice
Upgrade Play Billing library	Monetization	Play Billing Library 최신 버전으로 업그레이드

6개뿐이지만 선정 기준이 명확하다. 전부 "LLM이 혼자서는 잘 못 하는, 최신 마이그레이션/설정 작업"이다. Compose 문법을 짜는 건 LLM이 잘한다. 하지만 "기존 XML 레이아웃을 Compose로 바꾸면서 Navigation 3까지 적용하라"는 건 최신 패턴을 정확히 알아야 하는 작업이다.

어떻게 사용하는가 — 실제 동작 흐름

설치

Android CLI를 통해 스킬을 설치한다:

# 특정 스킬 설치
android skills add --skill edge-to-edge

# 모든 Android 스킬 설치
android skills add --all

# 특정 에이전트용으로 설치
android skills add --all --agent=claude-code,gemini-cli

# 설치된 스킬 목록 확인
android skills list

설치하면 프로젝트의 .skills/ 디렉토리(또는 에이전트별 지정 경로)에 스킬 폴더가 복사된다. 에이전트를 지정하지 않으면 기본 경로(~/.gemini/antigravity/skills)에 설치된다.

자동 트리거

설치 후에는 사용자가 아무것도 할 필요가 없다. 에이전트가 알아서 한다:

1. 사용자: "내 앱 UI를 edge-to-edge로 만들어줘"
2. 에이전트: 시작 시 로딩해둔 스킬 목록에서 description 매칭 → "Make app edge-to-edge" 스킬 발견
3. 에이전트: SKILL.md 본문 전체를 컨텍스트에 로딩
4. 에이전트: 스킬의 단계별 지시를 따라 코드 수정 실행

수동으로 호출할 수도 있다. Android Studio에서는 채팅창에 @skill-name을 입력하면 된다:

@migrate-from-xml-to-compose
@upgrade-to-agp-9
@edge-to-edge-modernization

업데이트

스킬은 GitHub 저장소에서 관리되므로, android skills add를 다시 실행하면 최신 버전으로 덮어쓴다. 스킬 파일 자체가 프로젝트 로컬에 복사되는 구조이므로, 업데이트 시점은 사용자가 통제한다. 자동 업데이트가 아니라 pull 방식이다.

30개 이상의 도구가 채택한 오픈 표준

Agent Skills가 단순한 Google 내부 규격이 아님을 보여주는 건 채택 현황이다. 현재 이 표준을 지원하는 주요 도구들:

도구	제작사
Claude Code	Anthropic
Gemini CLI	Google
OpenAI Codex	OpenAI
GitHub Copilot	Microsoft
Cursor	Anysphere
VS Code	Microsoft
Junie	JetBrains
Roo Code	RooCode
Kiro	AWS
Spring AI	VMware/Pivotal

그 외에도 OpenHands, Goose, Factory, Amp, Firebender, TRAE(ByteDance), Mistral Vibe 등 30개 이상의 도구가 참여하고 있다. Anthropic이 만들고, Google이 채택하고, Microsoft/OpenAI/JetBrains가 따라온 드문 합의다.

이게 의미하는 건 명확하다. 한 번 만든 스킬을 Claude Code에서도, Gemini CLI에서도, Copilot에서도, Cursor에서도 쓸 수 있다. "Write once, use everywhere"가 에이전트 스킬에서 현실이 되고 있다.

커스텀 스킬 만들기

공식 스킬만 쓸 수 있는 게 아니다. 누구나 자기만의 스킬을 만들 수 있다.

# 1. 디렉토리 생성
mkdir -p .skills/my-custom-skill/

# 2. SKILL.md 작성
cat > .skills/my-custom-skill/SKILL.md << 'EOF'
---
name: my-custom-skill
description: 우리 팀의 코드 리뷰 체크리스트를 적용한다. 코드 리뷰, PR 검토 시 사용.
metadata:
  author: my-team
  version: "1.0"
---

# 코드 리뷰 체크리스트

## 보안
1. SQL injection 가능성 확인
2. 사용자 입력 sanitization 확인
...
EOF

이렇게 만든 스킬은 프로젝트의 .skills/ 디렉토리에 넣으면 에이전트가 자동으로 발견한다. 팀 전용 스킬을 Git으로 관리하면, 팀의 노하우가 코드화된 자산이 된다.

설계 원칙에서 읽는 인사이트

1. 메타데이터와 본문의 분리가 핵심이다

100개의 스킬이 있어도 시작 시 로딩되는 건 name + description뿐이다. 본문은 필요할 때만 로딩한다. 이건 단순한 최적화가 아니라 에이전트 시대의 정보 아키텍처다. 사람이 목차를 보고 필요한 챕터만 읽는 것처럼, 에이전트도 메타데이터를 보고 필요한 스킬만 활성화한다.

2. description이 곧 트리거 조건이다

별도의 트리거 규칙이나 정규식이 없다. 에이전트의 LLM이 사용자 요청과 description을 의미적으로 매칭한다. 이건 장점이자 단점인데 — 유연하지만 예측 불가능할 수 있다. 그래서 description을 잘 쓰는 게 스킬 품질의 핵심이 된다.

3. 파일 시스템이 곧 인터페이스다

스킬은 데이터베이스에 저장되지 않는다. API 서버를 거치지도 않는다. 그냥 폴더와 마크다운 파일이다. Git으로 버전 관리되고, 사람이 직접 읽고 편집할 수 있고, 어떤 에이전트든 파일 시스템만 접근하면 쓸 수 있다. 이 단순함이 30개 이상의 도구가 빠르게 채택할 수 있었던 이유다.

4. 에이전트 간 호환성은 새로운 경쟁축이다

과거에는 "어떤 IDE를 쓰느냐"가 개발자 생태계의 경쟁축이었다면, 이제는 "어떤 에이전트 스킬을 지원하느냐"가 새로운 축이 되고 있다. Agent Skills 표준을 지원하지 않는 도구는 이 생태계에서 고립된다. 플러그인 생태계가 IDE 경쟁을 결정했듯, 스킬 생태계가 에이전트 경쟁을 결정할 수 있다.

5. "SDK for Agents"의 실체가 드러났다

이전 글에서 Android CLI를 분석하며 "Agent를 위한 SDK는 Context Engineering"이라고 썼다. Android Skills는 그 구체적 구현체다. SDK 문서를 에이전트가 읽기 좋은 SKILL.md 형태로 제공하고, Progressive Disclosure로 컨텍스트를 효율적으로 관리하고, 오픈 표준으로 에이전트 종속성을 제거한다. 이것이 2026년 시점에서 "에이전트에게 전문성을 주입하는 방법"의 정답에 가장 가까운 형태다.

마치며

Android Skills는 단순한 마크다운 파일 모음이 아니다. 에이전트가 전문가가 되는 메커니즘이다. Progressive Disclosure로 컨텍스트를 절약하고, 오픈 표준으로 도구 종속성을 깨고, GitHub으로 커뮤니티 기여를 가능하게 했다.

아직 공식 스킬은 6개뿐이지만, 커뮤니티가 스킬을 만들기 시작하면 이야기가 달라진다. 사내 코딩 컨벤션, 팀별 아키텍처 패턴, 도메인 특화 가이드 — 이 모든 암묵지가 스킬로 코드화될 수 있다. 에이전트를 똑똑하게 만드는 건 더 큰 모델이 아니라, 더 좋은 맥락이다.

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.