Agent Skills는 어떻게 동작하는가

Agent Skill의 작동 원리를 가장 짧게 말하면 이렇습니다.

처음에는 스킬의 제목표만 보여 주고, 필요하다고 판단되면 본문을 꺼내 읽고, 그래도 더 필요할 때만 참고자료나 스크립트를 가져다 쓴다.

이 방식이 바로 progressive disclosure, 즉 점진적 공개입니다. 에이전트는 시작부터 모든 스킬의 모든 내용을 머리에 넣고 달리지 않습니다. 대신 가벼운 정보로 먼저 후보를 고르고, 맞는 스킬이 보일 때만 다음 층으로 내려갑니다.¹

이 원리를 이해하면 두 가지가 동시에 좋아집니다. 하나는 토큰 비용이고, 다른 하나는 정확도입니다. 쓸데없는 지침을 덜 싣게 되니 비용이 줄고, 지금 해야 할 일과 직접 관련된 지침만 보게 되니 판단도 더 또렷해집니다.

스킬은 시작할 때 무엇부터 읽을까

대부분의 스킬 시스템은 먼저 디렉터리를 훑어보며 SKILL.md를 찾습니다. 그리고 각 스킬의 전체 본문이 아니라, 맨 위 YAML frontmatter에 들어 있는 핵심 메타데이터를 수집합니다. 대표적으로 name과 description이 필수이고, 필요하면 license, compatibility, metadata, allowed-tools 같은 항목이 붙습니다.¹²

이걸 한눈에 보려면 실제 SKILL.md를 한 번 보는 게 가장 빠릅니다. 예를 들어 출장비 처리를 돕는 expense-report 스킬은 대략 이런 식으로 생길 수 있습니다.

---
name: expense-report
description: 직원 출장비 제출, 환급 규정 확인, 지출 한도 검토, 영수증 누락 점검이 필요한 요청에 사용한다.
license: Proprietary
compatibility:
  - gpt-4.1
  - gpt-4o
allowed-tools:
  - filesystem
  - python
  - spreadsheet
---

# Expense Report Skill

이 스킬은 출장비 제출, 환급 가능 여부 확인, 증빙 점검, 제출 전 검토가 필요한 상황에서 사용한다.

기본 절차:
1. 사용자의 요청이 신규 제출인지, 수정인지, 규정 확인인지 구분한다.
2. 지출 항목, 날짜, 금액, 통화, 영수증 보유 여부를 확인한다.
3. 누락된 필수 정보가 있으면 먼저 질문하고, 정보가 충분하면 항목별로 정리한다.
4. 규정 위반 가능성이나 한도 초과 여부를 점검한 뒤 다음 행동을 제안한다.

애매한 경우:
- 환급 가능 여부가 불분명하거나 예외 규정이 걸릴 수 있으면 `references/` 아래 정책 문서를 확인한다.

추가 자료 사용 규칙:
- 제출 문서 형식이 필요하면 `templates/`를 읽는다.
- 영수증 예시, 카테고리 표, 첨부 이미지 같은 보조 자료가 필요하면 `assets/`를 읽는다.

검증 규칙:
- 합계 계산, 항목 분류, 형식 검사가 필요하면 `scripts/` 아래 검증 스크립트를 실행한다.
- 스크립트 결과와 사용자가 입력한 값이 다르면 차이를 먼저 설명하고 재확인한다.

이 예시에서 봐야 할 포인트는 세 가지입니다.

• 시작 시점에는 description이 먼저 읽히고, 바로 이 문장이 "이 요청을 이 스킬로 처리할지"를 가르는 트리거 역할을 합니다.

• 본문 지침은 스킬이 실제로 선택되어 활성화된 뒤에야 읽힙니다. 그래서 절차를 자세히 써도, 선택되지 않으면 애초에 보이지 않습니다.

• references, templates·assets, scripts는 모두 한 번에 불러오는 것이 아니라, 애매함이 생기거나 검증이 필요할 때만 추가로 읽거나 실행합니다.

여기서 중요한 것은 에이전트가 처음부터 스킬의 본문 전체를 읽지 않는다는 점입니다. 시작 시점에는 "이런 스킬이 있고, 이런 일을 할 때 쓰면 된다" 정도의 안내만 받습니다. 구현마다 조금씩 다르지만, 어떤 제품은 여기에 스킬의 파일 경로나 추가 메타데이터까지 함께 넣어 두기도 합니다.³

쉽게 말해, 에이전트는 처음에 도서관의 책을 다 읽는 것이 아니라 목차 카드함부터 봅니다.

메타데이터는 왜 이렇게 중요할까

초보자는 종종 SKILL.md 본문에만 공을 들입니다. 물론 본문은 중요합니다. 하지만 스킬이 아예 선택되지 않으면 그 훌륭한 본문은 읽힐 기회조차 없습니다.

특히 description은 단순 소개문이 아니라, 에이전트가 "이 요청이 이 스킬과 관련 있나?"를 판단하는 핵심 단서입니다. 그래서 스펙에서도 description은 이 스킬이 무엇을 하는지와 언제 써야 하는지를 함께 설명하고, 관련 작업을 잘 떠올릴 수 있는 키워드를 포함하라고 권합니다.²

예를 들어 description이 이렇게 쓰여 있다고 해봅시다.

"직원 출장비 제출, 환급 규정, 지출 한도, 영수증 검증 관련 요청에 사용."

이 문장은 단순히 멋있어 보이기보다, 실제로 에이전트가 사용자의 질문과 연결하기 쉬운 단어들을 품고 있습니다. 사용자가 "택시 팁도 환급되나요?"라고 물었을 때, 에이전트는 이 설명과 질문 사이의 관련성을 비교해 볼 수 있습니다.

즉, 메타데이터는 장식이 아니라 발견 장치입니다.

여기서 말하는 트리거는 무엇인가

이 장에서 말하는 트리거는 버튼을 누르듯 딱 고정된 신호만 뜻하지 않습니다. 보통은 사용자 요청과 스킬 설명이 충분히 잘 맞아 보일 때 발생하는 활성화 판단에 가깝습니다.¹⁴

중요한 점은 세 가지입니다.

1. 트리거는 보통 description을 중심으로 일어납니다.

2. 트리거는 "무조건 실행"이 아니라 "이 스킬을 더 읽어 볼 가치가 있다"는 판단입니다.

3. 트리거가 되었다고 해서 참고자료나 스크립트까지 한꺼번에 전부 불러오지는 않습니다.¹⁴

즉, 트리거는 스킬의 실행 완료가 아니라 다음 단계로 들어가는 문입니다.

1단계: 광고처럼 노출되는 메타데이터

공식 문서에서는 이 첫 단계를 advertise라고 설명합니다. 각 스킬의 이름과 설명이 매 실행 시작 시점에 시스템 프롬프트나 이에 준하는 컨텍스트에 들어가, 에이전트가 어떤 스킬이 있는지 알게 되는 단계입니다. 문서에 따라 대략 스킬당 100토큰 안팎의 가벼운 비용으로 설명되기도 합니다.¹

이 단계에서 얻는 이점은 분명합니다. 에이전트는 가능한 스킬 목록을 알고 있지만, 아직 어떤 스킬의 자세한 절차에도 묶여 있지 않습니다. 마치 식당에 들어가 메뉴판만 보는 상태와 비슷합니다. 아직 주문하지도 않았는데 주방의 모든 레시피를 읽을 필요는 없지요.

반대로 이 단계가 나쁘게 설계되면 문제가 생깁니다. 스킬이 너무 많거나 설명이 장황하면, 아직 본문도 읽기 전에 메타데이터만으로도 컨텍스트가 탁해질 수 있습니다. 그래서 여러 문서가 공통으로 설명은 짧되, 언제 쓰는지 명확해야 한다고 강조합니다.⁵⁷

2단계: 맞는다고 판단되면 전체 SKILL.md를 로드한다

사용자 요청이 특정 스킬의 설명과 잘 맞는다고 판단되면, 그다음에야 에이전트는 load_skill 같은 메커니즘으로 해당 스킬의 전체 SKILL.md 본문을 읽습니다. 이때 frontmatter 아래에 있는 실제 지침, 절차, 예시, 출력 형식, 엣지 케이스 대응이 컨텍스트로 들어옵니다.¹⁴

이 단계가 바로 activation입니다. 메뉴판만 보던 상태에서, 선택한 메뉴의 조리법을 꺼내 읽는 순간이라고 보면 됩니다.

여기서 꼭 기억할 사실이 있습니다. 전체 스킬 본문은 트리거 전까지 읽히지 않습니다. 그래서 스킬 시스템은 "많은 능력을 갖고 있으면서도, 필요할 때까진 조용한" 구조가 될 수 있습니다.¹³

스펙과 가이드에서는 이 본문을 너무 길게 만들지 말라고 권합니다. 전체 SKILL.md가 활성화 순간 한 번에 로드되기 때문입니다. 그래서 보통 500줄 이하, 또는 대략 5,000토큰 이하 수준으로 유지하고, 세부 참고자료는 별도 파일로 빼라고 안내합니다.¹²⁵

이 규칙이 중요한 이유는 단순히 비용 때문만이 아닙니다. 본문이 지나치게 길면, 정작 지금 필요한 핵심 절차가 긴 설명 사이에 묻힐 수 있습니다. 토큰을 많이 먹는 스킬이 항상 좋은 스킬은 아닙니다. 오히려 핵심 절차를 짧고 선명하게 담은 스킬이 더 잘 작동하는 경우가 많습니다.

3단계: 추가 리소스는 정말 필요할 때만 읽는다

전체 SKILL.md를 읽었다고 해서, references/, assets/, scripts/ 안의 파일이 자동으로 다 로드되는 것은 아닙니다. 다음 단계는 훨씬 더 보수적입니다. 스킬 본문 안의 지시를 따르는 과정에서 필요하다고 판단될 때만, 에이전트가 read_skill_resource 같은 방식으로 참고 문서나 템플릿을 읽습니다.¹

예를 들어 SKILL.md 안에 "환급 가능 여부가 애매하면 references/POLICY_FAQ.md를 확인하라"라고 적혀 있다면, 그때 비로소 해당 파일을 읽습니다. 질문이 단순해서 FAQ가 필요 없으면, 그 파일은 끝까지 안 읽힐 수도 있습니다.

이 점은 오해가 아주 많은 부분입니다. 많은 사람이 "스킬이 활성화되면 references 폴더도 같이 다 들어오겠지"라고 생각합니다. 하지만 progressive disclosure의 핵심은 그 반대입니다. 활성화와 리소스 읽기는 다른 단계입니다. 추가 자료는 필요할 때만, 그것도 특정 파일 단위로 읽는 쪽이 기본에 가깝습니다.¹⁶

그래서 참고자료는 통째로 거대한 백과사전 하나를 넣기보다, 주제별로 잘게 나눠 두는 편이 좋습니다. 에이전트는 지금 필요한 파일만 읽을 수 있어야 하고, 읽힌 파일 하나가 너무 크면 그 자체가 또 작은 프롬프트 폭탄이 되기 때문입니다.²⁵⁶

읽힌다와 실행된다는 전혀 다르다

여기서 한 번 더 중요한 구분이 나옵니다.

파일을 읽는 것과 코드를 실행하는 것은 다릅니다.

참고 문서나 템플릿은 보통 읽혀서 컨텍스트에 들어옵니다. 반면 scripts/ 안의 파일은 실제로 실행 가능한 코드일 수 있습니다. 에이전트가 그 스크립트를 실행하려면, 해당 런타임이 이를 지원해야 하고, 스킬 지침이 실제 실행을 요구해야 하며, 도구 권한도 맞아야 합니다. 일부 프레임워크는 run_skill_script 같은 도구를 제공하지만, 지원 범위는 구현마다 다를 수 있습니다.¹²

예를 들어 이런 차이가 있습니다.

• references/POLICY_FAQ.md를 읽는다 → 정책 설명 텍스트를 컨텍스트에 추가한다.

• assets/expense-report-template.md를 읽는다 → 템플릿 형식을 참고한다.

• scripts/validate.py를 실행한다 → 실제 검증 로직이 돌아가고 결과가 나온다.

즉, 모든 것이 결국 "스킬이 실행되었다"라는 한 문장으로 뭉개지기 쉽지만, 내부적으로는 메타데이터 노출, 본문 로드, 리소스 읽기, 스크립트 실행이 서로 다른 행동입니다.

한 번에 흐름으로 보면 이렇게 움직인다

실제 흐름은 보통 아래와 같습니다.

1. 에이전트가 시작되며 스킬 폴더를 스캔하고, 각 스킬의 name과 description 같은 메타데이터를 수집한다.¹⁴

2. 이 메타데이터 목록이 시스템 프롬프트 또는 유사한 컨텍스트에 들어간다.¹³

3. 사용자 요청이 들어오면, 에이전트는 요청과 스킬 설명을 비교해 어떤 스킬이 관련 있는지 판단한다.²⁴

4. 맞는 스킬이 보이면 전체 SKILL.md 본문을 로드한다.¹⁴

5. 본문 절차를 따라가다가 필요할 때만 참고 문서, 템플릿, 자산 파일을 읽는다.¹⁶

6. 필요하면 스크립트를 실행하고, 그 결과를 다시 추론에 활용한다.¹

7. 이렇게 모은 최소한의 맥락으로 최종 응답을 만든다.

핵심은 "조금씩 꺼내 쓴다"는 점입니다. 처음부터 다 싣고 가는 버스가 아니라, 중간중간 필요한 짐만 트렁크에서 꺼내는 여행에 가깝습니다.

예시로 보면 훨씬 쉽다

가상의 expense-report 스킬이 있다고 해봅시다.

시작 시점에 에이전트가 아는 것은 대략 이런 정도입니다.

• 이름: expense-report

• 설명: 출장비 제출, 환급 규정, 지출 한도, 영수증 검증 관련 요청에 사용

이제 사용자가 묻습니다.

"택시비는 알겠는데, 택시 팁 25%도 환급되나요?"

이 질문을 받으면 에이전트는 먼저 메타데이터를 보고 expense-report가 관련 있을 가능성이 높다고 판단합니다. 그래서 전체 SKILL.md를 읽습니다. 여기엔 아마 이런 내용이 들어 있겠지요. 어떤 순서로 정책을 확인할지, 애매한 경우 어떤 FAQ를 볼지, 최종 답변 형식을 어떻게 할지 같은 것들입니다.

그런데 본문 안에 "팁 규정은 FAQ를 확인하라"가 들어 있다면, 그때 references/POLICY_FAQ.md를 추가로 읽습니다. 만약 사용자가 단순히 "출장비 보고서 양식 좀 줘"라고 했다면, 이번에는 FAQ 대신 assets/expense-report-template.md만 읽을 수도 있습니다. 실제 제출 검증까지 해야 한다면, 마지막에 scripts/validate.py가 실행될 수도 있습니다.¹

같은 스킬이어도 요청에 따라 읽는 파일이 달라지는 이유가 바로 여기에 있습니다.

왜 이 구조가 토큰 비용을 줄일까

만약 스킬이 없거나 progressive disclosure가 없다면, 에이전트는 모든 전문 지침을 시작부터 프롬프트에 넣어야 할 가능성이 큽니다. 그러면 다음과 같은 일이 생깁니다.

첫째, 매 요청마다 같은 긴 지침을 계속 실어 나르게 됩니다. 둘째, 현재 질문과 관련 없는 규칙까지 함께 들어와 주의를 분산시킵니다. 셋째, 스킬 수가 늘수록 시스템 프롬프트가 비대해집니다.⁵⁷

반면 점진적 공개 구조에서는 시작할 때는 가벼운 메타데이터만 들고 가고, 실제로 관련 있는 스킬 본문 하나만 먼저 읽고, 더 필요하면 그때 리소스를 붙입니다. 이 방식은 비용 절감에 직접적이고, 동시에 문맥 오염도 줄여 줍니다. 문맥 오염은 지금 필요한 판단보다 관련 없는 정보가 더 많이 들어와 모델의 집중을 흐리는 상태라고 생각하면 됩니다.¹⁷

한마디로, progressive disclosure는 "정보를 덜 주는 기술"이 아니라 필요한 순간에 맞춰 주는 기술입니다.

왜 정확도도 함께 좋아질까

토큰을 아끼는 것만으로는 부족합니다. 스킬은 정확도에도 영향을 줍니다.

에이전트가 아무 지침 없이 일반 상식만으로 답하면, 대체로 그럴듯하지만 팀 규칙이나 도메인 절차를 놓칠 수 있습니다. 반대로 관련 없는 지침이 너무 많이 들어와도 판단이 흐려질 수 있습니다. 좋은 스킬 시스템은 이 둘의 중간을 잡습니다. 필요한 순간에, 필요한 절차만, 필요한 깊이로 넣어 줍니다.

예를 들어 정책 질문인데 템플릿만 잔뜩 읽고 있으면 정확도가 떨어집니다. 반대로 양식 작성인데 정책 FAQ만 들고 있으면 쓸모없는 장비를 들고 전쟁터에 나가는 셈입니다. progressive disclosure는 지금 작업의 종류에 맞는 지식층을 골라 주기 때문에, 정확도와 일관성을 동시에 끌어올리기 쉽습니다.¹⁵

좋은 스킬은 어디서 정확도가 갈릴까

좋은 스킬은 "정보가 많다"보다 "읽히는 순서가 좋다"에서 차이가 납니다.

메타데이터 단계에서는 description이 분명해야 합니다. 어떤 요청에서 이 스킬을 떠올려야 하는지가 보여야 합니다. 본문 단계에서는 절차와 판단 기준이 짧고 또렷해야 합니다. 리소스 단계에서는 파일이 주제별로 잘 쪼개져 있어야 합니다. 그래야 에이전트가 필요한 것만 골라 읽을 수 있습니다.²⁵⁶

반대로 좋지 않은 스킬은 대개 이런 식입니다. description이 모호해서 아예 트리거가 안 되거나, SKILL.md가 너무 길어서 로드되는 순간 집중력이 흐려지거나, references 폴더에 거대한 문서 하나만 넣어 둬서 읽을 때마다 토큰을 크게 낭비합니다.

결국 좋은 스킬 설계는 글쓰기이면서 동시에 컨텍스트 설계입니다.

실무 감각으로 기억할 한 가지

스킬은 "설치되어 있다"와 "지금 쓰이고 있다"가 다릅니다.

이 차이를 놓치면 비용 계산도 틀리고, 디버깅도 어려워집니다. 어떤 스킬이 폴더에 있다고 해서 매 요청마다 그 스킬 본문이 들어가는 것이 아닙니다. 반대로 어떤 스킬이 한 번 활성화되었다고 해서, 그 안의 모든 참고자료와 스크립트까지 자동으로 다 사용된 것도 아닙니다.

디버깅할 때는 늘 이렇게 물어보면 좋습니다.

"지금은 메타데이터만 들어간 상태인가?"

"전체 SKILL.md까지 로드되었는가?"

"추가 리소스는 어떤 파일이 실제로 읽혔는가?"

"스크립트는 읽기만 했는가, 실제 실행까지 했는가?"

이 질문이 분명해지면, 토큰이 어디서 새는지와 정확도가 어디서 흔들리는지도 함께 보이기 시작합니다.

이 장의 핵심 정리

Agent Skills의 동작 원리는 생각보다 단순합니다. 하지만 단순한 만큼, 제대로 이해하면 강력합니다.

스킬은 처음부터 전부 로드되지 않습니다. 먼저 메타데이터가 노출되고, 사용자 요청이 설명과 잘 맞을 때 전체 SKILL.md가 로드됩니다. 그다음에도 끝이 아닙니다. 작업을 수행하는 과정에서 필요할 때만 참고자료, 템플릿, 스크립트가 추가로 읽히거나 실행됩니다.¹

즉, 스킬의 핵심은 "큰 프롬프트를 파일로 옮겨 놓았다"가 아닙니다. 핵심은 필요한 정보만 단계적으로 꺼내 쓰도록 설계된 구조라는 점입니다.

이 감각을 잡으면 왜 어떤 스킬은 싸고 정확하게 동작하는지, 왜 어떤 스킬은 괜히 길고 둔하게 느껴지는지 이해하게 됩니다. 그리고 바로 그 이해가 다음 단계로 이어집니다. 좋은 스킬은 단지 글을 잘 쓴 스킬이 아니라, 읽혀야 할 정보가 읽혀야 할 순간에 도착하도록 설계된 스킬입니다.

다음 장에서는 이 작동 원리를 바탕으로, 좋은 Skill이 내부적으로 어떤 구성 요소를 가져야 하는지 살펴보겠습니다. 특히 SKILL.md를 어떻게 쓰고, 폴더 구조를 어떻게 나누어야 이 점진적 공개가 실제로 잘 작동하는지 본격적으로 파헤쳐 볼 것입니다.

참고

¹Agent Skills | Microsoft Learn

²Specification - Agent Skills

³Agent Skills - Codex | OpenAI Developers

⁴Add Skills to Your Agent

⁵Skill authoring best practices - Claude API Docs

⁶Agent Skills: References, Recipes & Token Loading Behavior - Best practices documentation

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