Agent Skills (에이전트 스킬)

Agent Skills (에이전트 스킬)

Agent Skills는 특정 작업을 수행하는 절차와 필요한 리소스를 SKILL.md 중심의 디렉터리로 패키징하고, 에이전트가 필요한 시점에 불러 사용할 수 있게 하는 개방형 규격입니다. 새로운 도구 호출 프로토콜을 정의하기보다, 에이전트가 이미 사용할 수 있는 도구와 파일, 실행 환경을 어떤 순서와 기준으로 활용할지 재사용 가능한 작업 지식으로 묶는 방식입니다.

이 구조가 필요한 이유는 모든 작업 절차를 시스템 프롬프트에 항상 넣으면 컨텍스트가 커지고 현재 작업과 무관한 지시까지 함께 들어오기 때문입니다. Agent Skills는 catalog의 name과 description → 활성화된 Skill의 SKILL.md → 필요한 references, scripts, assets 순으로 정보를 사용하는 progressive disclosure를 핵심 원칙으로 둡니다. 따라서 처음에는 어떤 Skill이 있는지만 작게 노출하고, 실제 작업에 필요한 지침과 리소스만 단계적으로 가져올 수 있습니다.

MCP와도 역할이 다릅니다. MCP는 에이전트와 외부 시스템 사이에서 도구와 데이터를 연결하는 protocol이고, Skill은 그 도구와 리소스를 이용해 특정 작업을 어떻게 수행할지 설명하는 절차와 지식의 묶음입니다. 둘은 경쟁하는 구조가 아니라 함께 사용할 수 있습니다. 또한 한 번 활성화한 Skill의 내용이 얼마나 오래 context에 남는지, supporting file을 어떤 방식으로 읽거나 실행하는지는 Agent Skills 파일 형식 자체가 모두 고정하는 것이 아니라 각 agent runtime의 구현과 context 관리 방식에 달려 있습니다.

---

1장. Tool Capability와 Workflow Knowledge의 구분

도구는 에이전트가 무엇을 할 수 있는지를 정의하고, Skill은 그 능력을 어떤 순서와 기준으로 사용할지를 묶습니다. 파일 읽기, API 호출, 셸 실행이 capability라면 “월간 정산은 먼저 원장을 검증하고, 차이가 있으면 예외 목록을 만든 뒤, 승인된 형식으로 보고한다”는 workflow knowledge입니다.

도구만 있어도 작업은 실행할 수 있지만 절차가 매번 달라질 수 있습니다. 검증 단계가 빠지거나 출력 형식이 흔들리고, 결국 사용자가 같은 지시를 반복해서 붙여넣게 됩니다. 이런 반복 절차를 SKILL.md와 필요한 리소스로 패키징하는 것이 Skill의 역할입니다.

프로젝트 전체에서 항상 지켜야 하는 규칙과 필요할 때만 불러야 하는 절차도 구분하는 편이 좋습니다. 예를 들어 Claude Code에서는 저장소 전반의 안정적인 규칙을 CLAUDE.md에 두고, 특정 작업에서만 필요한 긴 workflow나 reference를 Skill로 분리할 수 있습니다. 다만 “사실은 CLAUDE.md, 절차는 Skill”처럼 둘을 완전히 나누는 보편 규칙은 아닙니다. 적용 범위, 재사용 빈도, 컨텍스트 비용을 함께 보고 배치합니다.

2장. SKILL.md와 리소스 디렉터리 구조

폴더 하나가 스킬 하나입니다.

my-skill/
├── SKILL.md           # 본체. 필수
├── template.md        # 채워 넣을 템플릿
├── examples/
│   └── sample.md      # 기대 출력 예시
└── scripts/
    └── validate.sh    # 실행할 스크립트

필수는 SKILL.md 하나뿐이고 나머지는 전부 선택입니다. SKILL.md 는 --- 로 감싼 YAML frontmatter와 그 아래 마크다운 본문 두 부분으로 이루어집니다.

최소 예제입니다.

---
name: weekly-report
description: 주간 업무 보고서를 사내 표준 형식으로 작성한다
---

# 주간 보고서 작성

## 절차

1. 이번 주 커밋 로그를 수집한다
2. 이슈 트래커에서 완료된 항목을 가져온다
3. 아래 형식으로 정리한다
4. 다음 주 계획은 미완료 이슈에서 뽑는다

## 규칙

- 항목당 한 줄을 넘기지 않는다
- 커밋 메시지를 그대로 붙이지 않고 업무 단위로 묶는다

파일 하나, 폴더 하나가 전부입니다.

보조 파일. SKILL.md 는 얇게 유지하고 자세한 자료는 별도 파일로 뺍니다. 중요한 것은 SKILL.md 에서 이 파일들을 언급해 주는 것입니다. 전체 API 상세는 reference.md를 참고하라고 적어 둬야 모델이 무엇이 어디 있는지 알고 필요할 때만 읽습니다.

공식 문서는 SKILL.md 를 500줄 아래로 유지하고 상세 자료는 별도 파일로 옮기라고 권고합니다.

스크립트는 성격이 다릅니다. reference 문서는 모델이 내용을 읽어 컨텍스트에 넣지만, 스크립트는 반복 절차를 코드로 실행하고 모델에는 필요한 결과만 돌려줄 수 있습니다. 스크립트 소스 전체를 매번 읽지 않아도 된다는 점에서 긴 절차를 지시문으로 반복하는 것보다 컨텍스트를 아낄 수 있습니다.

그래서 결정적이고 반복적인 작업은 지시문으로 설명하지 말고 스크립트로 만드는 편이 낫습니다. 이 검증을 이렇게 저렇게 하라를 200줄 쓰는 대신 validate.sh를 만들고 실행하라 한 줄이면, 토큰이 절약되고 결과가 결정적이 되고 사람도 직접 돌려볼 수 있습니다.

---

3장. Progressive Disclosure와 단계적 로딩

Agent Skills의 핵심 설계는 필요한 지침만 단계적으로 공개하는 progressive disclosure입니다. 클라이언트는 먼저 Skill의 식별 정보와 설명을 보고, 작업과 관련 있다고 판단했을 때 SKILL.md 본문을 읽고, 본문이 요구할 때만 scripts/, references/, assets/ 같은 추가 리소스를 사용합니다.

1단계  catalog/discovery
       name + description 같은 작은 메타데이터

          ↓ 관련 Skill을 선택

2단계  instruction
       SKILL.md 본문을 로드

          ↓ 더 자세한 자료가 필요

3단계  resource
       references, scripts, assets 등을 필요한 만큼 사용

이 구조 덕분에 Skill을 많이 설치했다고 해서 모든 본문이 매 요청에 그대로 들어갈 필요는 없습니다. 다만 실제 catalog 구성, discovery 방식, 활성화 뒤 본문을 몇 턴 동안 유지하는지는 각 agent runtime의 구현입니다. 오픈 규격이 보장하는 것은 Skill 패키지의 구조와 progressive disclosure의 기본 계약이지, 모든 제품의 context lifecycle까지 동일하게 만드는 것은 아닙니다.

그래서 SKILL.md는 핵심 절차와 resource 탐색 지침에 집중하고 큰 참고자료는 분리하는 편이 좋습니다. Agent Skills 가이드도 본문을 가능한 한 작게 유지하고 상세 자료는 별도 파일로 옮기도록 권장합니다.

4장. Skill Discovery와 Activation Metadata

먼저 오픈 Agent Skills specification의 계약과 특정 클라이언트가 추가한 확장 필드를 분리해야 합니다.

오픈 규격에서 SKILL.md frontmatter의 핵심은 다음과 같습니다.

필드	상태	역할
name	필수	Skill 식별 이름
description	필수	무엇을 하고 언제 유용한지 설명하는 discovery metadata
license	선택	라이선스 정보
compatibility	선택	필요한 환경이나 호환 조건
metadata	선택	클라이언트가 활용할 수 있는 추가 키-값
allowed-tools	실험적/구현 의존	허용 도구 힌트. 지원 여부를 클라이언트에서 확인

즉 name과 description은 이식 가능한 Skill의 중심이고, 나머지는 현재 specification과 대상 client가 실제로 지원하는지 확인해야 합니다. 특히 권한 필드를 적었다고 해서 모든 runtime이 동일하게 강제하는 것은 아닙니다.

Claude Code 같은 클라이언트는 이 위에 더 많은 frontmatter와 치환 변수를 제공합니다. disable-model-invocation, user-invocable, argument-hint, arguments, model, effort, context, agent, hooks, paths 같은 설정은 Claude Code의 실행·호출 제어 기능으로 읽어야지 Agent Skills 오픈 규격의 필수 요소로 일반화하면 안 됩니다. ${CLAUDE_SKILL_DIR}, ${CLAUDE_PROJECT_DIR}, $ARGUMENTS 같은 변수도 같은 범주입니다.

권한 역시 두 층을 분리합니다. 오픈 Skill은 필요한 도구를 기술할 수 있지만 실제 허용·차단 정책은 host runtime의 permission system이 최종적으로 결정합니다. 예를 들어 Claude Code에서 allowed-tools를 사용하더라도 “목록에 없는 도구는 모든 환경에서 자동 차단된다”는 의미로 해석하면 안 됩니다. 반대로 disallowed-tools를 Agent Skills의 공통 frontmatter 필드로 두는 것도 현재 오픈 규격의 계약이 아닙니다.

이식성을 우선한다면 최소한의 표준 metadata와 본문 절차를 중심으로 만들고, 특정 클라이언트에서만 필요한 invocation·permission·subagent 설정은 별도 문단이나 client-specific 예제로 표시하는 편이 안전합니다.

5장. Skill Scope와 Client별 적용 범위

Skill을 어디서 발견하고 어떤 범위에 적용할지는 오픈 패키지 형식보다 클라이언트 구현의 영역입니다. 따라서 사용자·프로젝트·플러그인·관리자 범위와 이름 충돌 시 우선순위를 보편 표준처럼 외우기보다 사용하는 런타임의 discovery 문서를 확인해야 합니다.

Claude Code를 예로 들면 사용자 범위와 프로젝트 범위의 Skill, 플러그인으로 제공되는 Skill 등을 발견할 수 있고, 프로젝트 디렉터리와 연계한 동작도 지원합니다. 이런 경로와 precedence는 Claude Code의 제품 계약입니다. 다른 Agent Skills 클라이언트가 같은 디렉터리 이름이나 override 규칙을 따라야 하는 것은 아닙니다.

실무에서는 두 가지를 분리해 문서화하는 편이 좋습니다.

portable skill
   SKILL.md의 표준 metadata와 절차
   scripts / references / assets

client integration
   Skill을 어디서 찾는가
   어떤 permission을 적용하는가
   자동 호출과 수동 호출을 어떻게 제어하는가
   충돌과 override를 어떻게 처리하는가

이렇게 나누면 Skill 자체는 다른 클라이언트로 옮기기 쉽고, 제품별 설치·권한 규칙이 바뀌어도 본문 workflow를 다시 쓰지 않아도 됩니다.

6장. Activation 이후의 Context 관리

Skill이 활성화된 뒤 그 본문을 컨텍스트에 얼마나 오래 유지할지는 runtime이 정합니다. 오픈 Agent Skills specification은 discovery와 로딩 구조를 정의하지만, “한 번 읽은 SKILL.md가 세션 끝까지 반드시 남는다”거나 “재호출하면 항상 짧은 안내만 들어간다” 같은 lifecycle을 보편적으로 규정하지 않습니다.

Claude Code의 현재 구현은 이 지점에서 더 구체적인 동작을 갖습니다. 활성화된 Skill 내용이 이후 턴에도 컨텍스트에 영향을 줄 수 있고, context compaction 뒤에는 최근 Skill instruction을 다시 주입하는 정책과 토큰 상한을 둡니다. 이런 수치는 제품 버전에 따라 바뀔 수 있으므로 Skill 파일 자체의 규칙으로 고정해 적기보다 Claude Code 운영 문서에서 확인하는 편이 낫습니다.

이 차이는 Skill 작성에도 영향을 줍니다. 본문에는 작업 동안 반복해서 필요한 절차를 남기고, 큰 reference나 일회성 데이터는 별도 resource로 빼는 것이 안전합니다. 그래야 어떤 runtime이 본문을 길게 유지하더라도 상시 context 비용이 과도하게 커지지 않습니다.

Skill이 기대만큼 작동하지 않을 때도 activation 여부와 instruction adherence를 나눠 봐야 합니다. 먼저 Skill이 실제로 선택되고 본문이 로드됐는지 확인하고, 그다음 다른 상위 지시나 도구 제약과 충돌하는지, description이 너무 넓거나 좁지 않은지, 본문이 실행 가능한 절차로 쓰였는지를 점검합니다.

7장. Description 기반 Skill Trigger 설계

description은 Skill discovery에서 가장 중요한 신호 중 하나입니다. 본문을 읽기 전에 “이 Skill이 지금 필요한가”를 판단해야 하므로 무엇을 하는지뿐 아니라 언제, 어떤 요청에서 쓰는지가 드러나야 합니다.

오픈 Agent Skills specification은 description을 필수 필드로 두고 길이 제한도 정의합니다. 반면 when_to_use 같은 별도 필드와 catalog에서 description을 어떤 방식으로 합치거나 자르는지는 특정 클라이언트의 확장일 수 있습니다. 따라서 description + when_to_use가 항상 1,536자에서 잘린다 같은 제품별 동작을 오픈 규격의 상한으로 설명하면 안 됩니다.

좋은 description은 대상을 구체적으로 적습니다.

# 너무 넓음
description: 코드 리뷰 도우미

# 더 구체적
description: Python 변경사항을 리뷰해 타입 힌트 누락, 예외 처리, 공개 함수의 테스트 누락을 점검한다. PR 작성 전 코드 검토에 사용한다.

핵심은 세 가지입니다. 무엇을 하는가, 언제 쓰는가, 어떤 대상에 쓰는가입니다. 여러 Skill의 설명이 겹치면 모델이나 클라이언트가 activation을 구분하기 어려우므로 역할 경계를 나누는 편이 좋습니다. 클라이언트가 when_to_use나 invocation hint를 별도로 지원한다면 그 필드는 추가 힌트로 쓰되, portable discovery 정보는 description만 읽어도 이해되게 만드는 것이 안전합니다.

8장. Agent Skills와 MCP의 역할 구분

MCP는 도구와 데이터를 앱에 연결하는 프로토콜입니다. GitHub API를 부를 수 있게 하는 배관입니다. 스킬은 그 도구들을 어떤 순서로 쓸지의 절차입니다. PR을 리뷰할 때는 먼저 diff를 받고 그다음 무엇을 한다는 절차입니다.

그래서 경쟁 관계가 아닙니다. MCP로 도구를 붙이고 스킬로 그 도구를 쓰는 법을 가르칩니다.

함께 쓰는 형태. MCP 서버가 jira_search 와 jira_create, jira_transition 을 제공하면 스킬이 버그 리포트 처리 절차를 정의합니다.

1. jira_search 로 중복 이슈를 먼저 찾는다
2. 있으면 코멘트만 달고 끝낸다
3. 없으면 jira_create 로 만들되
   재현 절차와 환경 정보를 반드시 포함한다
4. 심각도가 P1 이면 jira_transition 으로 즉시 할당한다

MCP만 있으면 모델이 매번 다른 순서로 처리하고, 스킬만 있으면 절차는 아는데 실행할 도구가 없습니다.

파일 기반이라는 것이 주는 이점. 스킬은 마크다운 파일이라 git에 올라가고 PR로 리뷰되고 diff로 변경 이력이 보이며 비개발자도 읽고 고칠 수 있습니다. MCP 서버는 코드라 이만큼 가볍지 않습니다.

---

9장. 재사용 가능한 Instruction Package의 발전

Voyager. 2023년의 Voyager는 마인크래프트 안에서 도는 LLM 에이전트였습니다. 할 줄 알게 된 일을 코드로 저장하고 나중에 그 코드를 다시 꺼내 썼는데, 스킬 라이브러리라는 이름을 실제로 썼습니다.

지금의 에이전트 스킬과 공통점은 재사용 가능한 절차를 외부에 저장하고 필요할 때 검색해 불러오며 쌓일수록 능력이 는다는 것입니다. 차이점은 Voyager는 에이전트가 스스로 만들어 저장했고 지금의 스킬은 주로 사람이 작성해 배포한다는 것입니다.

계보로 보면 프롬프트 템플릿이라는 재사용 가능한 지시문 덩어리에서 시작해, 파일로 분리하고 조건부 로딩을 붙이니 슬래시 커맨드가 됐고, 모델도 스스로 부를 수 있게 하고 보조 파일과 메타데이터를 붙이니 에이전트 스킬이 됐습니다.

Claude Code에서는 실제로 이 통합이 일어났습니다. .claude/commands/deploy.md 와 .claude/skills/deploy/SKILL.md 가 둘 다 같은 명령을 만들고 같은 방식으로 동작하며, 기존 커맨드 파일은 그대로 계속 쓰입니다.

---

10장. Skill의 실행 권한과 공급망 보안

스킬은 실행 가능한 지시입니다. 스킬 본문은 모델의 컨텍스트에 그대로 들어갑니다. 즉 스킬 파일에 쓰인 내용은 사실상 시스템 프롬프트에 추가되는 것이고, allowed-tools 로 권한까지 딸려옵니다.

그래서 남이 만든 스킬을 설치하는 것은 남이 만든 셸 스크립트를 실행 권한과 함께 두는 것과 위험도가 비슷합니다.

확인할 것.

설치 전에 SKILL.md 를 직접 읽는다
   실행 코드와 권한 범위를 검토하고 출처를 신뢰할 수 있는지 확인한다

scripts/ 안의 코드를 확인한다
   실행되는 코드다

allowed-tools 에 무엇이 있는지 본다
   Bash 가 광범위하게 허용돼 있으면 위험 신호다

description 과 본문이 일치하는지 본다
   "문서 정리" 라고 해놓고 본문이 네트워크 전송을 시키면
   그게 공격이다

조직에서는 skill을 코드와 비슷한 공급망 자산으로 보고 review·versioning·권한 제한을 두는 편이 안전합니다. allowed-tools 같은 권한 필드는 client가 지원하는 경우 최소 권한으로 설정하고, 외부에서 받은 script와 instruction은 실행 전에 검토합니다.

---

11장. Skill 설계의 주요 실패 패턴

① 본문이 너무 길다
   로드 이후의 유지·compaction·재로딩은 agent runtime의 context 정책에 달려 있다
   500 줄 넘으면 보조 파일로 뺀다

② description 이 부실하다
   가장 흔하고 가장 치명적이다

③ 왜 그런지를 길게 설명한다
   무엇을 할지만 쓴다

④ 결정적 작업을 지시문으로 설명한다
   스크립트로 만든다

⑤ 스킬 하나에 여러 절차를 밀어넣는다
   폴더를 나눈다. description 이 흐려진다

⑥ 부작용 있는 작업의 호출·권한 정책을 따로 설계하지 않는다
   host runtime이 제공하는 승인·권한·호출 제어를 함께 설정한다

⑦ 일회성 지시로 쓴다
   "지금 이걸 해라" 가 아니라
   "이 작업 동안은 이렇게 한다" 로 쓴다

⑧ 남의 스킬을 안 읽고 설치한다

---

12장. 효율적인 Agent Skill 설계 원칙

Agent Skill의 최소 단위는 SKILL.md를 가진 디렉터리입니다. name과 description이 discovery의 출발점이 되고, 본문은 실행 절차를, 보조 디렉터리는 필요한 reference·script·asset을 담습니다.

progressive disclosure의 목적은 모든 작업 지식을 항상 컨텍스트에 넣는 대신 필요한 Skill과 resource만 그때 읽게 하는 것입니다. 실제 activation·permission·context lifecycle은 host runtime의 계약과 함께 봐야 합니다.

MCP는 도구와 데이터를 연결하고 Skill은 그 능력을 사용하는 절차를 패키징하므로 서로 대체하는 개념이 아닙니다.

언제 만드나. 같은 지시를 세 번 이상 붙여넣었거나, CLAUDE.md의 한 섹션이 절차로 자라났거나, 결과가 매번 달라 후속 자동화가 깨지거나, 새로 온 사람에게 매번 같은 설명을 한다면 전부 스킬로 만들 신호입니다.

잘 만드는 순서.

① 실제로 반복하는 절차를 그대로 받아 적는다
② 왜 그런지를 지우고 무엇을 할지만 남긴다
③ 결정적인 부분을 스크립트로 뺀다
④ 긴 참고 자료를 별도 파일로 뺀다
⑤ description 에 무엇을, 언제, 무엇에 를 채운다
⑥ 부작용이 있으면 호출 주체를 제한한다
⑦ 실제로 써 보고 안 불리면 description 부터 고친다

---

용어 정리

용어	한 줄 뜻
에이전트 스킬 (Agent Skill)	폴더 하나와 SKILL.md로 정의하는 재사용 가능한 절차 패키지
SKILL.md	스킬의 진입점. YAML frontmatter와 마크다운 본문으로 구성
frontmatter	---로 감싼 YAML 메타데이터. 이름, 설명, 권한, 실행 방식 지정
progressive disclosure	이름과 설명만 상시 두고, 본문과 보조 파일은 필요할 때만 로드하는 방식
description	무엇을 하고 언제 쓰는지 설명하는 핵심 trigger metadata
when_to_use	일부 클라이언트가 제공하는 추가 activation 힌트. 오픈 규격의 필수 필드는 아님
allowed-tools	지원하는 클라이언트에서 필요한 도구를 기술하는 필드. 권한 의미는 runtime 계약을 확인
disable-model-invocation	Claude Code의 호출 제어 확장 필드
user-invocable	Claude Code의 사용자 호출 노출을 제어하는 확장 필드
context: fork	Claude Code의 별도 실행 컨텍스트 관련 확장 설정
paths	Claude Code에서 경로와 연결해 사용할 수 있는 확장 설정
CLAUDE_SKILL_DIR	Claude Code가 제공하는 Skill 디렉터리 치환 변수
보조 파일	SKILL.md 옆의 참고 문서, 템플릿, 예시. 필요할 때만 읽힘
스크립트	반복적·결정적 작업을 코드로 분리한 리소스. 모델은 필요할 때 실행 결과를 사용
스킬 생애주기	catalog 조회, 본문 로드, resource 추가 로드와 runtime의 context 관리 과정
Voyager	마인크래프트 안에서 습득한 능력을 코드로 저장해 재사용한 2023년 에이전트
MCP	도구와 데이터를 앱에 연결하는 프로토콜. 스킬과 층이 다름

참고자료

• Claude Code 공식 문서, Skills (폴더 구조, frontmatter 전체 목록, 생애주기)
• Agent Skills 오픈 표준
• anthropics/skills (공개 스킬 저장소와 패키징 도구)
• Anthropic API 문서, Skills 가이드
• Voyager: An Open-Ended Embodied Agent with Large Language Models (arXiv 2305.16291, 스킬 라이브러리의 원형). Figure 4 가 스킬 라이브러리의 추가와 검색이고 Figure 5 가 환경 피드백과 실행 오류로 고쳐 나가는 반복 프롬프팅이다. ar5iv
• Agent Skills Specification
• Agent Skills, Adding skills support
• Agent Skills, Best practices