Agent Skills: 필요할 때만 읽히는 에이전트 지침과 MCP의 차이

에이전트에게 회사의 배포 절차를 가르치고 싶다고 해 보겠습니다. 가장 쉬운 방법은 시스템 프롬프트에 절차를 적는 것입니다. 그런데 배포 절차 옆에 문서 작성 규칙, 코드 리뷰 기준, 장애 대응 순서까지 적다 보면 시스템 프롬프트가 수만 토큰이 됩니다. 배포와 상관없는 질문을 할 때도 그 전부가 매번 컨텍스트를 차지합니다.

Anthropic의 Agent Skills는 이 문제에 대한 답입니다. 지침을 폴더에 넣어 두고, 필요할 때만 읽게 합니다.

긴 프롬프트를 파일로 옮긴 것일 뿐이라는 오해

스킬을 처음 보면 프롬프트를 마크다운 파일로 옮겨 둔 것처럼 보입니다. SKILL.md라는 파일에 지침을 적는 것이 전부이기 때문입니다.

차이는 언제 읽히느냐에 있습니다. 시스템 프롬프트는 대화가 시작될 때 전부 컨텍스트에 들어갑니다. 스킬은 이름과 설명 한 줄만 먼저 들어가고, 본문은 모델이 그 스킬이 필요하다고 판단했을 때 비로소 읽힙니다. 문서는 이것을 점진적 공개(progressive disclosure)라고 부릅니다.

세 단계로 나뉘어 읽히는 구조

문서가 밝힌 단계별 비용은 이렇습니다.

단계	언제 읽히나	토큰 비용	내용
1. 메타데이터	항상 (시작 시)	스킬당 약 100토큰	name과 description
2. 지침	스킬이 호출될 때	5천 토큰 미만	SKILL.md 본문
3. 자료와 코드	필요할 때	읽기 전까지 0	참고 문서, 스크립트, 템플릿

스킬을 스무 개 설치해도 평소에는 약 2천 토큰만 차지합니다. 3단계가 특히 흥미롭습니다. 스킬 폴더에 스크립트를 넣어 두면 모델은 그 코드를 읽지 않고 실행만 합니다. 컨텍스트에 들어오는 것은 "검증 통과" 같은 실행 결과뿐입니다. 같은 일을 모델이 매번 코드로 새로 짜는 것보다 싸고, 결과도 매번 같습니다.

설명 한 줄이 스킬의 전부를 좌우하는 이유

1단계에서 모델이 보는 것은 설명 한 줄뿐입니다. 모델은 사용자의 요청을 이 설명들과 비교해서 어떤 스킬을 열지 정합니다. 문서가 설명에 "무엇을 하는지"와 "언제 써야 하는지"를 둘 다 적으라고 강조하는 이유입니다.

저는 스킬을 만들 때 본문보다 이 한 줄에 시간을 더 써야 한다고 봅니다. 본문이 아무리 좋아도 설명이 요청과 맞지 않으면 스킬은 열리지 않습니다. 반대로 설명이 너무 넓으면 상관없는 요청에도 열려서 컨텍스트를 낭비합니다. "PDF를 다룰 때"보다 "PDF에서 표를 뽑거나 양식을 채우거나 여러 PDF를 합칠 때, 또는 사용자가 PDF나 양식을 언급할 때"처럼 사용자가 실제로 쓸 말을 넣는 편이 잘 맞습니다. 이름은 64자, 설명은 1,024자까지입니다.

MCP와 헷갈리는 지점

스킬과 함께 자주 나오는 것이 MCP(Model Context Protocol)입니다. 둘 다 에이전트에게 새 능력을 준다는 점에서 비슷해 보입니다.

제가 보는 구분은 이렇습니다. MCP는 손이고 스킬은 업무 매뉴얼입니다. MCP는 에이전트를 바깥 시스템에 연결합니다. 데이터베이스를 조회하고, 슬랙에 메시지를 보내고, 캘린더를 읽는 도구를 서버로 제공합니다. 스킬은 그 도구들을 어떤 순서로, 어떤 기준으로 쓸지를 가르칩니다. 배포 스킬은 "먼저 테스트를 돌리고, 통과하면 태그를 달고, 실패하면 멈춰서 보고하라"를 적고, 실제로 명령을 실행하는 것은 셸이나 MCP 도구입니다.

그래서 둘은 대체 관계가 아니라 보완 관계입니다. MCP만 있으면 에이전트는 도구는 있는데 회사의 방식을 모르고, 스킬만 있으면 방식은 아는데 손이 닿지 않는 시스템이 생깁니다.

어디서 쓸 수 있는가

Claude Code에서는 폴더만 만들면 됩니다. ~/.claude/skills/에 두면 개인용, 프로젝트의 .claude/skills/에 두면 그 저장소를 쓰는 모두가 공유합니다. API에서는 스킬을 올려서 쓰고 워크스페이스 전체가 공유합니다. claude.ai에서는 설정에서 zip으로 올리고 사용자 개인에게만 적용됩니다.

세 곳의 스킬은 서로 동기화되지 않습니다. 실행 환경도 다릅니다. API의 스킬은 네트워크 없이 격리된 컨테이너에서 돌고, Claude Code의 스킬은 사용자 컴퓨터의 다른 프로그램과 같은 권한으로 돕니다.

스킬을 설치하는 것은 소프트웨어를 설치하는 일

마지막으로 짚을 것은 보안입니다. 스킬은 지침과 코드를 함께 담을 수 있으니, 악의적인 스킬은 에이전트에게 설명과 다른 일을 시킬 수 있습니다. 문서는 믿을 수 있는 출처의 스킬만 쓰고, 모르는 출처라면 번들된 파일을 전부 검토하라고 경고하며, 스킬 설치를 소프트웨어 설치처럼 다루라고 권합니다.

특히 바깥 URL에서 내용을 가져오는 스킬은 프롬프트 인젝션의 통로가 됩니다. 오늘 믿을 만한 스킬도 그것이 참조하는 외부 내용이 바뀌면 내일은 다르게 동작합니다. 편하게 공유되는 텍스트 파일처럼 보여도, 에이전트에게는 실행할 명령이라는 점을 기억해 두는 것이 좋습니다.