AgentSkill 해부하기

놀라울 정도로 작은 설계

AI 에이전트에게 새로운 능력을 가르치는 파일이 얼마나 복잡할 것 같나요? AgentSkills 스펙의 답은 “놀라울 정도로 간단하다"예요.

이 레슨을 마치면 AgentSkills의 구조를 이해하고 스킬이 여러 에이전트에서 작동하는 원리를 알게 돼요.

배울 내용

• AgentSkills 스펙의 세 계층 구조
• 필수 필드와 선택 필드
• 점진적 노출 패턴
• MCP vs 스킬의 차이
• 이 코스의 전체 로드맵

세 계층 구조

AgentSkills는 세 가지 계층으로 구성돼요:

계층 1: 메타데이터 (항상 로드)

---
name: meeting-notes-formatter
description: "회의 녹취를 구조화된 노트로 변환"
---

에이전트가 항상 읽는 최소 정보예요. name(최대 64자)과 description(최대 1024자)만 있으면 돼요.

계층 2: 지시문 (필요할 때 로드)

YAML 프론트매터 아래의 마크다운 본문이에요. 에이전트가 스킬을 실행할 때 컨텍스트에 로드해요.

계층 3: 연결 파일 (요청 시 로드)

references/, assets/, scripts/ 디렉토리의 파일들이에요. 에이전트가 필요할 때만 읽어요.

이 점진적 노출 패턴이 컨텍스트 윈도우를 효율적으로 관리해요 — 불필요한 정보로 에이전트의 “기억"을 채우지 않아요.

선택 필드

✅ Quick Check: 왜 에이전트는 전체 SKILL.md를 항상 로드하지 않고, 메타데이터 → 지시문 → 연결 파일 순서로 필요할 때만 로드하나요?

MCP vs 스킬: 무엇이 다른가

혼동하기 쉬운 두 개념이에요:

MCP가 “무엇을 할 수 있는지"를 확장한다면, 스킬은 “어떻게 할지"를 가르쳐요. 두 가지는 상호보완적이에요 — 고급 스킬에서는 MCP 서버를 활용하는 경우도 많아요.

크로스플랫폼 호환성

AgentSkills 표준의 핵심 장점은 이식성이에요. 한 번 만든 스킬이 여러 에이전트에서 작동해요:

스킬 파일의 형식이 동일하기 때문에, 한 플랫폼에서 만든 스킬을 다른 플랫폼으로 폴더만 옮기면 그대로 작동해요. 한국의 위키독스 커뮤니티에서도 이런 크로스플랫폼 활용 사례가 활발하게 공유되고 있어요.

핵심 정리

• AgentSkills 스펙은 놀라울 정도로 간단 — 필수 필드는 name과 description 두 개뿐
• 세 계층(메타데이터 → 지시문 → 연결 파일)의 점진적 노출로 컨텍스트 효율 극대화
• MCP는 “배관”(외부 연결), 스킬은 “두뇌”(행동 지시) — 서로 보완
• AgentSkills는 크로스플랫폼 표준 — 한 번 만들면 OpenClaw, Claude Code, Cursor 등에서 재사용

Up Next: 다음 레슨에서 실제로 첫 번째 커스텀 스킬을 만들어요 — 회의 노트 포맷터를 처음부터 완성까지.