에이전트는 어떻게 Skill을 읽는가

지난 장에서 Skill이 무엇인지 정리했다면, 이제 질문은 조금 더 실전적으로 바뀐다. Skill이 폴더 안에 잘 들어 있다고 해서 에이전트가 저절로 잘 쓰는 것은 아니다. 어떤 Skill은 분명 좋은 내용을 담고 있는데도 좀처럼 불리지 않고, 어떤 Skill은 의도와 다르게 엉뚱한 순간에 튀어나온다. 문제는 대개 지식의 질보다 읽히는 방식에 있다.

핵심은 이것이다. Skill은 사람이 정독하는 매뉴얼이 아니라, 에이전트가 상황에 맞게 꺼내 보는 실행 문서다. 즉, 잘 쓴 Skill이란 "내용이 많고 친절한 문서"가 아니라 "필요한 순간에 정확히 선택되고, 필요한 부분만 로드되며, 실행 중 혼동을 줄이는 문서"다.¹²

에이전트는 처음부터 다 읽지 않는다

많은 초안이 실패하는 이유는 여기서 시작된다. 사람은 문서를 처음부터 끝까지 읽는 습관이 있다. 하지만 에이전트는 보통 그렇게 일하지 않는다. 대부분의 Skill 호환 환경에서는 먼저 모든 Skill의 name과 description 같은 가벼운 메타데이터만 훑는다. 그리고 현재 요청과 맞아 보이는 Skill이 있을 때만 SKILL.md 본문을 읽고, 그 뒤에야 references/나 assets/, scripts/ 같은 추가 자료를 필요할 때 불러온다.¹²³

이 흐름을 이해하면 설계 관점이 완전히 달라진다. SKILL.md는 처음부터 끝까지 읽혀야 하는 홍보 브로슈어가 아니다. 오히려 세 번에 걸쳐 나눠 읽히는 문서에 가깝다. 먼저 "이 Skill이 지금 필요한가"를 판단하는 얇은 표지층이 있고, 그다음 "실제로 어떻게 할 것인가"를 알려주는 본문층이 있으며, 마지막으로 "정말 필요할 때만 꺼내는 보조 재료층"이 있다.

쉽게 말해 공구함과 비슷하다. 서랍 바깥 라벨이 description이고, 서랍을 열었을 때 보이는 사용 설명서가 본문이며, 안쪽 칸에 들어 있는 템플릿과 스크립트가 리소스다. 라벨이 흐릿하면 서랍 자체를 못 찾고, 설명서가 난잡하면 공구를 잘못 쓰고, 안쪽 칸이 무겁고 복잡하면 일하다가 손이 꼬인다.

SKILL.md는 메타데이터와 본문이 역할이 다르다

좋은 Skill 설계는 메타데이터와 본문을 섞지 않는 데서 시작한다. 둘은 같은 문서 안에 있지만 맡은 일이 다르다.

메타데이터는 선택을 돕는다. 특히 name과 description은 에이전트가 "이 일을 이 Skill로 처리할지" 판단할 때 가장 먼저 보는 신호다. 반면 본문은 실행을 돕는다. 한 번 Skill이 활성화된 뒤에는 본문이 절차, 기준, 예외 처리, 출력 형식을 안내한다.²⁴

이 차이를 놓치면 흔한 문제가 생긴다. 예를 들어 어떤 작성자는 본문에 트리거 조건을 길게 적어 놓고 description은 "문서 작성 도우미"처럼 모호하게 써 둔다. 사람 눈에는 본문이 훌륭해 보여도, 에이전트는 거기까지 도달하지 못할 수 있다. 입구 표지판이 작아서 문을 지나치기 때문이다.

반대로 본문이 빈약한데 description만 화려해도 문제가 된다. 이번에는 잘 불리긴 하지만, 막상 로드된 뒤 무엇을 어떻게 해야 할지 몰라 성능이 흔들린다. 결국 메타데이터는 라우팅, 본문은 실행이라는 역할 분리가 선명해야 한다.

name, description, instructions, resources는 각각 무엇을 좌우하는가

이제 각 요소를 따로 보자. 이 네 가지는 비슷해 보여도 에이전트의 행동에 미치는 영향이 다르다.

name은 식별자이자 기억의 손잡이다

name은 사람에게는 단순한 파일명처럼 보이지만, 에이전트에게는 Skill의 정체성을 묶는 손잡이다. 보통 소문자와 하이픈 중심의 짧고 일관된 이름을 쓴다. 여기서 중요한 것은 멋있음보다 분명함이다. report-helper보다 executive-report-writer가 낫고, research-tool보다 market-research-brief가 더 낫다. 이름만으로도 대략 어떤 일인지 짐작 가능해야 한다.

다만 name은 어디까지나 식별자다. 활성화의 핵심은 보통 description이 담당한다. 이름은 너무 포괄적이거나 너무 장황하지 않게, 한 가지 업무 축을 정확히 잡아 주는 정도면 충분하다.

description은 사실상 활성화 조건의 압축본이다

description은 가장 중요한 필드다. 무엇을 하는 Skill인지뿐 아니라 언제 써야 하는지도 여기에 들어가야 한다. 다시 말해 description은 소개문이 아니라 활성화 조건을 자연어로 압축해 둔 라우팅 문장이다.¹²⁴

좋지 않은 예를 먼저 보자.

"문서를 잘 작성합니다."

이 설명은 거의 아무 일에도 맞고, 동시에 아무 일에도 정확히 맞지 않는다. 보고서, 이메일, 회의록, 제안서, 블로그 글이 전부 문서이기 때문이다. 이런 Skill은 너무 자주 잘못 불리거나, 반대로 주변 Skill과 구분되지 않아 묻혀 버릴 수 있다.

조금 더 좋은 설명은 이렇게 바뀐다.

"임원용 1페이지 보고서를 작성한다. 주간 실적, 리스크, 의사결정 포인트, 다음 액션을 간결한 경영진 보고 형식으로 정리해야 할 때 사용한다."

여기에는 무엇을 하는지와 언제 써야 하는지가 함께 들어 있다. 실적 요약, 리스크 정리, 1페이지 보고서, 경영진 보고 형식 같은 단서가 붙으면서 에이전트의 선택 정확도가 높아진다.

실무적으로는 description에 다음 세 가지를 녹여 쓰는 것이 좋다.

• 어떤 결과물을 만드는가

• 어떤 상황이나 요청에서 써야 하는가

• 무엇에는 쓰지 말아야 하는가

세 번째는 특히 인접한 Skill이 많을 때 중요하다. 예를 들어 meeting-minutes와 executive-report가 같이 있으면, 전자는 회의 발언과 결정 사항 정리에, 후자는 임원 보고용 압축 문서에 쓰인다고 경계를 분명히 적어 두는 편이 훨씬 안정적이다.

instructions는 실행 규칙이다

본문의 instructions는 선택이 끝난 뒤 에이전트가 실제로 따라갈 절차다. 여기에는 순서, 체크포인트, 금지사항, 예외 대응, 출력 형식이 들어간다. 이때 중요한 것은 백과사전처럼 많이 쓰는 것이 아니라, 행동이 달라질 정도로만 쓰는 것이다.³

좋은 instructions는 보통 처음 부분에 핵심 원칙이 먼저 온다. 예를 들어 "원자료가 없으면 추정하지 말고 누락 사실을 명시한다", "외부 수치를 인용할 때는 날짜와 출처를 함께 적는다", "최종 결과는 반드시 표준 템플릿 순서를 따른다" 같은 규칙은 문서 앞쪽에 있어야 잘 지켜진다.³

반대로 나쁜 instructions는 이런 식이다. 설명은 길지만 무엇이 필수인지, 무엇이 선택인지 구분이 없다. 단계가 많지만 멈춰야 할 조건이 없다. 예외 상황이 본문 중간 깊숙한 곳에 숨어 있다. 이런 Skill은 읽는 데는 그럴듯하지만 실행에서는 자주 흔들린다.

resources는 깊이를 늘리되 기본 문서는 가볍게 만든다

references/, assets/, scripts/는 Skill의 힘을 키우는 보조 장치다. 긴 기준표, 샘플 출력, 브랜드 문체 가이드, 검증 스크립트, 데이터 변환 코드 같은 것들이 여기에 들어간다.¹²

중요한 점은, 리소스가 있다는 사실 자체가 좋은 것이 아니라 본문을 가볍게 유지하게 해 준다는 데 있다. 기본 SKILL.md가 모든 세부 사항을 떠안으면 활성화될 때마다 무거운 문서를 통째로 실어 나르게 된다. 반면 본문에는 "언제 어떤 리소스를 읽어라"만 적고, 실제 내용은 분리해 두면 에이전트가 필요한 순간에만 가져다 쓸 수 있다. 이것이 바로 Skill 설계에서 자주 말하는 점진적 공개다.¹²³

progressive disclosure는 컨텍스트 예산을 아끼는 설계다

컨텍스트 창은 넓어졌지만, 그렇다고 아무 문서나 다 넣어도 된다는 뜻은 아니다. 오히려 에이전트는 너무 많은 문서를 한꺼번에 받으면 중요한 규칙을 놓치거나, 중간 정보에 묻혀버리는 경우가 많다. 그래서 Skill 시스템은 가능한 한 적게 보여 주고, 필요해질 때만 더 읽히도록 설계된다.¹³

보통 흐름은 네 단계로 이해하면 쉽다. 먼저 광고하듯 존재만 알린다. 이 단계에서는 이름과 설명만 보인다. 다음으로 관련 Skill의 본문을 로드한다. 그다음 정말 필요할 때만 참고 자료를 읽는다. 마지막으로 필요하면 번들된 스크립트를 실행한다.²

이 방식의 장점은 단순하다. 에이전트는 수십 개의 Skill을 알고 있어도, 실제 작업에서는 그중 몇 개만 깊게 읽으면 된다. 그래서 Skill 수가 늘어나도 곧바로 컨텍스트가 터지지 않는다.

여기서 작성자가 해야 할 일도 분명해진다. SKILL.md는 시작 버튼 역할을 하는 제어판처럼 쓰고, 긴 설명서가 되어서는 안 된다. 본문에는 작업의 뼈대만 남기고, 세부 기준표나 장문 사례는 리소스로 빼는 편이 좋다. "무조건 다 적자"는 친절이 아니라, 오히려 선택과 실행을 방해하는 소음이 되기 쉽다.

description에 활성화 조건을 어떻게 녹여 쓸까

많은 초보 작성자가 "활성화 조건"이라는 말을 보면 별도의 규칙 언어가 있어야 한다고 생각한다. 하지만 현재 많은 Skill 환경에서는 활성화가 엄격한 프로그래밍 규칙으로 표준화돼 있지 않고, 실제로는 description이 가장 중요한 실전 신호로 작동한다.⁵ 그래서 description을 잘 쓰는 것이 곧 활성화 설계다.

가장 쉬운 방법은 한 문장을 세 층으로 나누는 것이다.

첫 번째 층은 업무 정의다. 이 Skill이 무슨 일을 하는지 적는다. 두 번째 층은 사용 상황이다. 어떤 요청, 어떤 산출물, 어떤 맥락에서 써야 하는지 적는다. 세 번째 층은 비사용 경계다. 비슷하지만 다른 일에는 쓰지 말라고 못 박는다.

예를 들어 회의록 Skill이라면 이렇게 쓸 수 있다.

"회의 내용을 결정 사항, 액션 아이템, 미해결 이슈 중심으로 정리하는 Skill. 회의 녹취, 메모, 채팅 로그를 회의록으로 변환할 때 사용한다. 임원용 요약 보고서나 외부 홍보용 문안 작성에는 사용하지 않는다."

이 문장은 짧지만 강하다. 어떤 입력을 받는지, 어떤 출력으로 가는지, 어디까지가 범위인지가 다 들어 있기 때문이다.

반대로 description에 지나친 수사나 1인칭 표현을 넣는 것은 피하는 편이 좋다. "나는 멋진 보고서를 써준다" 같은 문장은 에이전트 입장에서 라우팅 신호가 약하다. 에이전트가 비교해야 하는 것은 감탄사가 아니라 업무 단서다.⁴

너무 넓은 Skill은 만능처럼 보이지만 자주 오작동한다

처음 Skill을 만들 때 가장 달콤한 유혹은 하나의 Skill로 많은 일을 해결하고 싶은 마음이다. 예를 들어 document-writing-master 같은 Skill 하나로 보고서, 이메일, 보도자료, 회의록, 블로그 글까지 다 처리하고 싶어진다. 보기에는 효율적이지만 실제로는 선택과 실행 모두 망가질 가능성이 크다.

너무 넓은 Skill은 우선 잘못 활성화되기 쉽다. 문서 관련 요청은 너무 많기 때문이다. 게다가 본문 안에서 모드가 갈라지기 시작한다. "만약 이메일이면", "만약 블로그 글이면", "만약 보고서면" 같은 분기문이 늘어나면서 instructions가 비대해진다. 그러면 에이전트는 무엇이 현재 작업의 핵심 규칙인지 놓치기 쉽다.³

더 나쁜 경우는 가까운 Skill들을 잡아먹는 것이다. 원래는 email-reply, meeting-minutes, executive-report처럼 분리되어야 할 업무가 하나의 큰 Skill에 빨려 들어가면, 정작 세밀한 품질 기준은 사라지고 모든 결과물이 비슷한 말투와 구조로 납작해진다. 만능 칼은 멋있지만, 실제 주방에서는 칼날이 둔해지기 쉽다.

너무 좁은 Skill은 정밀해 보이지만 거의 불리지 않는다

반대쪽 극단도 있다. 이번에는 Skill을 지나치게 잘게 쪼개는 경우다. 예를 들어 q1-sales-report-korean, q1-sales-report-english, q1-sales-report-with-chart, q1-sales-report-no-chart처럼 쪼개기 시작하면, 설명은 정밀해 보여도 실제로는 재사용성과 선택 가능성이 떨어진다.

너무 좁은 Skill은 첫째, 활성화되기 어렵다. 사용자의 요청이 description과 정확히 겹치지 않으면 후보에서 밀려난다. 둘째, 유지보수가 힘들다. 규칙 하나 바뀔 때마다 비슷한 Skill 여러 개를 같이 수정해야 한다. 셋째, 인접 Skill 간 충돌이 생긴다. 차이가 너무 미세하면 에이전트도 어느 쪽을 골라야 할지 애매해한다.

좋은 분할 기준은 출력 형식의 차이보다 업무 절차의 차이에 있다. 같은 절차로 처리하되 언어만 다른 경우라면 하나의 Skill 안에서 출력 옵션으로 다루는 편이 낫다. 반대로 입력, 판단 기준, 검증 방식이 실제로 다르다면 별도 Skill로 나누는 것이 맞다.

좋은 Skill은 넓이가 아니라 경계가 좋다

결국 Skill 설계의 핵심은 많이 담는 것이 아니라 경계를 잘 긋는 것이다. 에이전트가 읽는 Skill은 사람용 위키가 아니다. 선택될 수 있어야 하고, 로드된 뒤에는 빨리 이해되어야 하며, 필요한 정보만 추가로 꺼내 읽을 수 있어야 한다.

실무에서 기억할 기준은 간단하다.

• 메타데이터는 선택을 위해 쓴다.

• 본문은 실행을 위해 쓴다.

• 리소스는 깊이를 늘리되 기본 문서를 가볍게 유지하기 위해 둔다.

• description은 소개가 아니라 활성화 조건을 담는 라우팅 문장으로 쓴다.

• Skill은 넓어도 안 되고, 지나치게 쪼개도 안 되며, 하나의 반복 업무 흐름을 또렷하게 감싸야 한다.

이 원리를 이해하면 SKILL.md를 쓰는 손맛이 달라진다. 이제부터는 "무엇을 많이 적을까"보다 "에이전트가 어떤 순간에 이 문서를 선택하고, 어디까지 읽고, 무엇을 실행하게 할까"를 먼저 떠올리게 된다. 그리고 바로 그 순간, Skill은 사람을 위한 설명문에서 에이전트를 위한 실행 문서로 바뀐다.

다음 장에서는 시야를 조금 더 넓혀 보자. 지금까지는 Skill 하나를 어떻게 읽히게 만들지 살폈다면, 이제는 여러 제품과 도구 안에서 Skill이 어떻게 쓰이는지, Claude, Copilot, Cursor, ChatGPT Agent, MCP 같은 생태계 안에서 이 개념이 어떻게 연결되는지를 지도로 펼쳐 볼 차례다.

참고

¹Progressive Disclosure Pattern | microsoft/agent-skills | DeepWiki

²Agent Skills | Microsoft Learn

³Skill Design Guide | Agent Layer

⁴AI Agent Skills, 어떻게 만들고 어떻게 쓸까? | MadPlay🚀

⁵RFC: Skill Activation Mechanisms - Bridging the Gap Between Discovery and Usage