책에 포함된 노트Agent Skills 실무 가이드: 프롬프트를 넘어 스스로 일하는 AI 인프라와 에이전틱 워크플로우 구축하기

2. 에이전트 스킬 표준과 기술적 아키텍처

2026-04-25Views 17약 11분생성형 AI 활용

에이전트 스킬 표준과 기술적 아키텍처

에이전트를 잘 쓰는 사람과, 에이전트를 잘 굴리는 사람 사이에는 작은 차이가 하나 있습니다. 전자는 좋은 프롬프트를 씁니다. 후자는 좋은 구조를 만듭니다. 실무에서 더 오래 살아남는 쪽은 대개 후자입니다. 한 번 잘 나온 답변보다, 여러 번 비슷한 품질을 안정적으로 내는 체계가 훨씬 가치 있기 때문입니다.

Agent Skill은 바로 그 체계를 만드는 단위입니다. 스킬은 단순히 "잘 써 둔 프롬프트"가 아닙니다. 언제 활성화할지, 어떤 지침을 읽을지, 어떤 파일을 추가로 참조할지, 어떤 스크립트를 실행할지까지 포함하는 실행 가능한 패키지에 가깝습니다.¹² 이 장에서는 그 패키지가 어떤 형식으로 구성되고, 왜 그런 구조가 필요한지, 그리고 MCP와는 어떤 식으로 맞물리는지를 차근차근 살펴보겠습니다.

에이전트 스킬 표준과 기술적 아키텍처

2.1 SKILL.md: 에이전트의 역량을 정의하는 표준 포맷

Agent Skill의 가장 중요한 규칙은 의외로 단순합니다. 스킬은 하나의 디렉터리이고, 그 안에는 반드시 SKILL.md가 있어야 합니다.¹ 다시 말해 스킬의 최소 단위는 "파일 한 장"이 아니라 "폴더 하나"입니다. 이 차이가 꽤 큽니다. 에이전트의 능력은 설명문만으로 끝나지 않고, 필요하면 스크립트도 실행하고, 참고 문서도 읽고, 템플릿도 꺼내 써야 하기 때문입니다.

전형적인 구조는 다음과 같습니다.

my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

여기서 SKILL.md는 스킬의 안내판이자 작업 설명서입니다. scripts/는 실제로 실행할 코드가 들어가는 곳이고, references/는 길지만 필요한 순간에만 읽으면 되는 문서, assets/는 템플릿이나 스키마처럼 정적인 자산을 담는 곳입니다.¹²

이 구조가 좋은 이유는 책임이 분리되기 때문입니다. 예를 들어 "배포 점검" 스킬이 있다고 해 봅시다. 배포 전에 무엇을 확인해야 하는지는 SKILL.md에 적습니다. 실제 점검 명령은 scripts/check-deploy.sh에 넣습니다. 에러 코드 표나 운영 정책은 references/DEPLOY_GUIDE.md로 분리합니다. 이렇게 해 두면 에이전트는 생각할 것과 실행할 것을 뒤섞지 않습니다. 사람으로 치면, 머릿속 체크리스트와 손에 쥔 공구함을 분리해 두는 셈입니다.

또 하나 중요한 점은 SKILL.md가 비교적 자유로운 마크다운 본문을 가진다는 사실입니다. YAML 프론트매터 뒤에 오는 본문에는 형식 제약이 거의 없습니다.¹ 덕분에 스킬 작성자는 워크플로우, 입출력 예시, 실패 시 대처법, 흔한 함정 같은 실전 지식을 자연스럽게 담을 수 있습니다. 즉, 스킬은 딱딱한 스키마 문서가 아니라, 에이전트가 실제로 따라 할 수 있는 작업 설명서가 됩니다.

하지만 자유롭다고 해서 아무렇게나 길게 쓰면 안 됩니다. 공식 가이드와 구현 문서들은 공통적으로 SKILL.md를 지나치게 길게 만들지 말고, 본문은 핵심 절차에 집중하며, 상세 자료는 별도 파일로 분리하라고 권합니다.¹² 이유는 간단합니다. 스킬은 뒤에서 설명할 Progressive Disclosure 방식으로 로드되기 때문에, 본문이 비대해질수록 활성화 순간의 비용이 커집니다.

결국 SKILL.md의 역할은 이렇습니다. "이 스킬은 무엇을 하는가?"를 알려 주고, "언제 써야 하는가?"를 신호로 주며, "실제로 어떻게 수행할 것인가?"를 단계적으로 설명하는 것입니다. 좋은 스킬은 장황한 지식 저장소가 아니라, 일을 시작하게 만드는 정확한 작업 매뉴얼입니다.

2.2 메타데이터 설계: YAML을 활용한 스킬 속성 정의

SKILL.md의 맨 위에는 YAML 프론트매터가 들어갑니다. 이 부분은 사람보다 에이전트가 먼저 읽는 영역이라고 생각하면 이해가 쉽습니다. 본문이 "업무 지침서"라면, 프론트매터는 "카탈로그 정보"입니다.

공식 스펙에서 필수 필드는 name과 description 두 개입니다.¹ 얼핏 간단해 보이지만, 실무에서는 이 두 필드가 스킬의 성패를 좌우합니다.

먼저 name은 단순한 이름표가 아닙니다. 64자 이하여야 하고, 소문자·숫자·하이픈만 허용되며, 디렉터리 이름과 정확히 일치해야 합니다.¹² 즉, db-migration-check라는 폴더 안에 name: db-migration-check가 들어 있어야 합니다. 이 제약은 귀찮아 보이지만 아주 실용적입니다. 이름 규칙이 느슨하면 스킬 검색, 중복 판별, 배포 자동화 과정에서 금방 혼란이 생깁니다. 스킬은 문서이면서 동시에 배포 가능한 단위이므로, 파일 시스템 수준에서 식별이 명확해야 합니다.

description은 더 중요합니다. 이 필드는 "무엇을 하는가"와 "언제 사용해야 하는가"를 함께 설명해야 합니다.¹² 많은 사람이 여기서 실수합니다. 예를 들어 description: 코드 리뷰를 도와줍니다라고 쓰면 사람이 보기엔 무난하지만, 에이전트에게는 신호가 약합니다. 반면 "PR 변경사항을 검토하고 컨벤션 위반, 잠재 버그, 테스트 누락을 점검한다. 코드 리뷰나 변경사항 검토가 필요할 때 사용한다"처럼 쓰면 선택 정확도가 높아집니다. 스킬은 활성화되기 전에 우선 설명만 보고 선택되기 때문에, description은 일종의 라우팅 키 역할을 합니다.¹⁶

실무에서 자주 쓰는 나머지 필드도 알아둘 필요가 있습니다.

license는 스킬의 라이선스를 표시합니다.
compatibility는 Python 필요 여부, 네트워크 접근 필요 여부, 특정 제품 전용인지 같은 실행 조건을 적습니다.
metadata는 작성자, 버전, 태그 같은 확장 정보를 담는 자유 영역입니다.
allowed-tools는 해당 스킬이 사용해도 되는 도구를 미리 제한하는 실험적 필드입니다.¹²

특히 compatibility와 metadata는 팀 단위 운영에서 빛을 발합니다. 예를 들어 사내 데이터 접근이 필요한 스킬이라면 compatibility: Requires python3 and internal VPN access처럼 적어 두면, 로컬 환경에서는 되는데 CI에서는 안 되는 황당한 상황을 줄일 수 있습니다. metadata에는 owner, version, domain, risk-level 같은 속성을 넣어 운영 도구나 레지스트리에서 필터링하기 좋게 만들 수도 있습니다.¹²

아래는 실무 감각으로 다듬은 예시입니다.

---
name: code-review
description: >-
  Pull request 변경사항을 검토하고 컨벤션 위반, 잠재 결함, 테스트 누락을 점검한다.
  코드 리뷰, PR 검토, 리팩터링 점검이 필요할 때 사용한다.
license: Apache-2.0
compatibility: Requires python3 and git access
metadata:
  author: platform-team
  version: "1.2"
  domain: engineering
allowed-tools: read_file bash git
---

이 예시에서 핵심은 화려함이 아닙니다. 에이전트가 스킬을 고를 때 필요한 신호가 충분한가, 그리고 운영자가 스킬의 실행 조건을 한눈에 파악할 수 있는가입니다.

여기서 한 가지 더 기억할 점이 있습니다. 버전 정보는 종종 최상위 필드로 적고 싶어지지만, 오픈 스펙 관점에서는 metadata 아래에 넣는 편이 이식성 면에서 더 안전합니다.¹⁰ 어떤 구현체는 편의상 별도 필드를 받아들일 수 있어도, 표준을 따르려면 확장 속성은 가급적 metadata에 넣는 습관이 좋습니다.

정리하면, YAML 프론트매터는 장식이 아니라 스킬의 "발견 가능성"과 "운영 가능성"을 결정하는 층입니다. 본문을 잘 써도 메타데이터가 흐리면 스킬은 선택되지 않습니다. 마치 훌륭한 가게가 간판 없는 골목 안쪽에 숨어 있는 것과 비슷합니다. 내용은 좋은데, 아무도 못 찾습니다.

2.3 컨텍스트 최적화 기법: 필요한 순간에만 활성화되는 지능

Agent Skill 아키텍처의 진짜 묘미는 파일 구조보다 로딩 방식에 있습니다. 스킬은 한꺼번에 다 실리지 않습니다. 필요한 만큼만, 필요한 순간에만 점진적으로 불러옵니다. 이 방식을 Progressive Disclosure라고 부릅니다.¹²⁶

쉽게 비유하면 이렇습니다. 거대한 시스템 프롬프트는 여행 갈 때 집 전체를 가방에 넣는 방식입니다. 반면 스킬은 여행지와 일정에 맞춰 필요한 물건만 챙기는 방식입니다. 당연히 더 가볍고, 필요한 물건도 더 빨리 찾습니다.

공식 문서들을 종합하면 실무적으로는 세 층으로 이해하면 좋습니다.¹⁶

1단계 메타데이터: 모든 스킬의 name과 description만 먼저 읽습니다.
2단계 지침 본문: 현재 작업과 맞는다고 판단된 스킬의 SKILL.md 본문 전체를 불러옵니다.
3단계 리소스: 필요할 때만 references/, assets/, scripts/의 파일을 읽거나 실행합니다.

Microsoft 문서처럼 런타임 도구 관점에서 보면 이를 네 단계, 즉 advertise → load → read resources → run scripts로 설명하기도 합니다.² 표현만 다를 뿐 본질은 같습니다. 처음엔 얇은 카탈로그만 보여 주고, 선택된 스킬만 펼쳐 보고, 정말 필요할 때만 부속 자료와 실행 코드를 사용한다는 뜻입니다.

이 구조가 중요한 이유는 세 가지입니다.

첫째, 토큰 비용을 줄입니다. 모든 스킬의 상세 지침을 시스템 프롬프트에 다 넣으면 호출마다 같은 비용을 반복해서 냅니다. 반대로 스킬 메타데이터만 먼저 싣고, 현재 작업에 맞는 스킬 하나만 본문을 불러오면 기본 컨텍스트가 훨씬 가벼워집니다.²⁶

둘째, 정확도를 높입니다. 긴 프롬프트는 중요한 규칙을 중간 어딘가에 묻어 버리기 쉽습니다. 반면 스킬 방식은 지금 필요한 절차만 전면에 올리므로 주의력이 덜 분산됩니다.⁸⁹

셋째, 유지보수가 쉬워집니다. 예를 들어 SEO 규칙이 바뀌었다고 해 봅시다. 거대한 시스템 프롬프트를 뜯어고치는 대신 해당 스킬의 references/seo-guide.md만 수정하면 됩니다. 스킬의 책임 범위가 작을수록 수정의 영향도 좁아집니다.

그래서 좋은 스킬은 본문에 모든 것을 다 적지 않습니다. 자주 필요한 핵심 절차는 SKILL.md에 두고, 길고 세부적인 내용은 references/로 보냅니다.¹² 예를 들어 API 호출 규칙이 30줄이면 본문에 둘 수 있지만, 15개 엔드포인트의 상세 스키마까지 전부 넣는 것은 과합니다. 그런 내용은 참조 문서로 분리하는 편이 낫습니다.

실무에서 특히 중요한 작성 원칙은 두 가지입니다. 하나는 SKILL.md를 너무 비대하게 만들지 말라는 권고이고, 다른 하나는 참조 경로를 지나치게 깊게 중첩하지 말라는 점입니다.¹ SKILL.md가 references/REFERENCE.md를 가리키는 정도는 괜찮지만, 그 문서가 다시 다른 문서를 따라가고 또 그 아래 파일을 찾게 만들면 에이전트의 읽기 흐름이 흐트러집니다. 스킬은 똑똑해야 하지만, 미로처럼 설계되면 안 됩니다.

또한 Progressive Disclosure에서는 description의 중요성이 다시 한 번 커집니다. 에이전트는 처음에 상세 지침을 모릅니다. 오직 이름과 설명만 보고 "이 스킬을 켤까?"를 판단합니다.¹⁶ 즉, 잘못 쓰인 설명은 스킬이 존재하지 않는 것과 비슷한 결과를 낳습니다. 스킬의 선택 정확도는 본문보다 먼저, 메타데이터에서 결정됩니다.

정리하면 Progressive Disclosure는 단순한 최적화 기법이 아닙니다. 스킬 아키텍처의 핵심 철학입니다. 에이전트에게 모든 것을 미리 억지로 외우게 하는 대신, 필요한 순간에 필요한 지식만 정확하게 불러오게 만드는 설계입니다. 사람도 회의 때 회사 위키 전체를 머리에 넣고 들어가지는 않듯이, 에이전트도 작업에 맞는 정보만 들고 있을 때 더 안정적으로 일합니다.

2.4 MCP(Model Context Protocol)와 에이전트 스킬의 상호 운용성

스킬을 처음 접하면 흔히 이런 질문이 나옵니다. "그러면 MCP는 필요 없는 건가요?" 결론부터 말하면 전혀 그렇지 않습니다. 스킬과 MCP는 경쟁 관계가 아니라 역할 분담 관계에 가깝습니다.¹⁰¹¹

아주 짧게 구분하면 이렇습니다. 스킬은 에이전트에게 "어떻게 일할지"를 가르치고, MCP는 에이전트가 "무엇에 연결할 수 있는지"를 표준화합니다.¹⁰¹² 스킬이 플레이북이라면, MCP는 외부 시스템과 연결된 공용 포트입니다.

예를 들어 보겠습니다. 사용자가 "어제 장애 로그를 분석하고, 영향 범위를 요약해서 보고해 줘"라고 요청했다고 합시다. 여기서 스킬은 다음을 알려 줍니다. 어떤 순서로 로그를 확인할지, 어떤 패턴을 우선 의심할지, 요약 보고서는 어떤 형식으로 정리할지. 하지만 실제 로그 저장소에 접속하고, 검색 API를 호출하고, 이슈 트래커에 티켓을 생성하는 일은 스킬 혼자 할 수 없습니다. 그 부분은 MCP 서버가 노출한 도구나 리소스를 통해 처리하는 편이 맞습니다.¹²¹³

즉, 둘의 차이는 비결정성과 결정성의 경계에서도 드러납니다. 스킬은 자연어 지침이므로 해석의 여지가 있습니다. 반면 MCP 도구는 이름, 설명, 입력 스키마를 갖춘 구조화된 인터페이스이고, 호출 결과도 비교적 결정적입니다.¹² 다시 말해 스킬은 판단과 절차를 담당하고, MCP는 연결과 실행을 담당합니다.

이 상호 보완 관계를 이해하면 아키텍처가 훨씬 선명해집니다.

AGENTS.md는 프로젝트 차원의 공통 작업 방식과 경계를 알려 줍니다.
SKILL.md는 특정 업무나 도메인 역량을 재사용 가능한 형태로 제공합니다.
MCP는 데이터베이스, API, 파일 시스템, 사내 서비스 같은 외부 능력에 안전하게 연결해 줍니다.⁴¹⁰

실무에서는 셋을 함께 쓰는 장면이 자연스럽습니다. AGENTS.md에 "절대 운영 DB에 직접 쓰지 말 것" 같은 팀 규칙을 둡니다. db-analysis 스킬에는 "먼저 스키마를 확인하고, 읽기 전용 쿼리만 사용하며, 결과를 요약 표로 반환할 것" 같은 절차를 적습니다. 그리고 실제 쿼리 실행은 MCP 서버가 제공하는 읽기 전용 도구로 제한합니다. 이렇게 하면 에이전트는 마음대로 날아다니는 초보 인턴이 아니라, 사내 절차를 배우고 권한이 제한된 실무자에 가까워집니다.

MCP가 중요한 또 다른 이유는 보안과 운영성입니다. 외부 시스템 접근은 인증, 권한, 로깅, 속도 제한, 샌드박싱 같은 통제가 필요합니다. 이 부분을 자연어 스킬만으로 처리하려 하면 금방 무너집니다. MCP는 도구의 입력 스키마, 실행 인터페이스, 호스트-클라이언트-서버 구조를 통해 연결 계층을 표준화하므로, 에이전트가 외부 세계와 만나는 경계를 더 명확하게 만들 수 있습니다.¹²¹³

여기서 기억할 점이 하나 있습니다. 스킬은 도구가 아닙니다. 그리고 MCP도 스킬이 아닙니다.¹⁰ 스킬은 "이런 상황에서는 이렇게 하라"를 알려 주고, MCP는 "이 시스템에서는 이런 함수를 이렇게 부를 수 있다"를 알려 줍니다. 둘을 한데 섞으면 편할 것 같지만, 오히려 시스템이 흐려집니다. 업무 절차는 스킬에, 외부 연결은 MCP에, 공통 작업 규칙은 AGENTS.md에 두는 편이 장기적으로 훨씬 건강합니다.

앞으로 에이전트 인프라가 성숙할수록 중요한 것은 더 강한 단일 도구가 아니라 더 좋은 조합일 가능성이 큽니다. 스킬이 지식을 모듈화하고, MCP가 연결을 표준화하며, 상위 에이전트가 이를 조율하는 구조입니다. 이 조합이 만들어지면 에이전트는 "말 잘하는 모델"을 넘어 "필요한 지식을 골라 읽고, 필요한 시스템에 정확히 연결하는 작업자"로 바뀝니다.

2.5 구조를 이해하면 스킬이 흔들리지 않는다

스킬을 제대로 설계한다는 것은 단지 문장을 예쁘게 쓰는 일이 아닙니다. 어떤 정보가 항상 보여야 하는지, 어떤 정보는 필요할 때만 읽혀야 하는지, 어떤 로직은 자연어가 아니라 코드로 내려야 하는지, 어떤 외부 연결은 MCP로 분리해야 하는지를 결정하는 일입니다.

이 장의 핵심을 한 문장으로 요약하면 이렇습니다. 실무에서 흔들리지 않는 에이전트는, 좋은 답변 이전에 좋은 구조를 가진다.

SKILL.md는 그 구조의 시작점입니다. YAML 메타데이터는 스킬을 찾게 만들고, 본문은 작업 방식을 가르치며, Progressive Disclosure는 컨텍스트를 가볍게 유지하고, MCP는 외부 세계와의 연결을 안전하고 표준화된 방식으로 맡습니다. 이 네 가지가 맞물릴 때 비로소 스킬은 "프롬프트의 모음"이 아니라 "재사용 가능한 역량 단위"가 됩니다.

다음 장에서는 이 원리를 실제로 손에 잡히는 형태로 만들어 보겠습니다. 이제 설계도를 봤으니, 직접 스킬을 지어 볼 차례입니다.