처음 만드는 Agent Skill

손으로 한 번 만들어 봐야 진짜 이해된다

Agent Skill은 설명만 들으면 꽤 추상적으로 느껴집니다. 폴더가 있고, SKILL.md가 있고, 필요하면 스크립트와 참고 자료도 붙는다고 배웠지만, 막상 빈 파일 앞에 앉으면 손이 멈추기 쉽습니다. 바로 이 지점에서 실전이 필요합니다.

처음 만드는 Skill은 거창할 필요가 없습니다. 오히려 작고, 실패해도 덜 위험하고, 결과를 바로 확인할 수 있는 주제가 좋습니다. Skill은 원래 거대한 인공지능 성격을 만드는 장치가 아니라, 특정 일을 더 안정적이고 반복 가능하게 만드는 작은 작업 모듈이기 때문입니다.¹⁴

이번 장에서는 초보자도 바로 따라 할 수 있도록 아주 단순한 Skill 하나를 직접 만들어 보겠습니다. 주제는 polite-email-reply입니다. 이름 그대로, 업무용 이메일에 정중한 답장 초안을 만드는 Skill입니다.

이 주제를 고른 이유는 간단합니다. 거의 누구나 상황을 이해할 수 있고, 좋은 설명문, 단계별 지침, 출력 형식, 예시, 경계조건을 모두 연습하기에 딱 좋기 때문입니다. 게다가 아직 메일을 실제로 보내는 자동화까지 가지 않으니, 첫 실습으로 부담도 적습니다.

오늘 만들 Skill: polite-email-reply

우리가 만들 Skill의 목표는 한 문장으로 정리할 수 있습니다.

받은 이메일 내용을 바탕으로, 정중하고 실무적인 한국어 답장 초안을 만든다. 다만 필요한 정보가 빠져 있으면 지어내지 말고 먼저 확인할 내용을 드러낸다.

이 한 문장 안에는 첫 Skill에 꼭 필요한 세 가지가 이미 들어 있습니다.

• 무엇을 하는가: 이메일 답장 초안을 만든다

• 언제 쓰는가: 받은 메일에 답해야 할 때 쓴다

• 어떻게 안전하게 동작하는가: 부족한 정보는 추측하지 않는다

처음 Skill을 만들 때 가장 흔한 실수는 범위를 너무 넓게 잡는 것입니다. 예를 들어 '모든 업무 커뮤니케이션을 도와주는 Skill'처럼 시작하면 멋있어 보이지만, 실제로는 설명도 흐려지고 테스트도 어려워집니다. 반대로 '업무 메일 답장 초안'처럼 작게 잡으면, 잘 되는지 안 되는지가 눈에 바로 들어옵니다.

1단계: 먼저 무엇을 잘하게 만들지 고른다

처음에는 기능보다 장면을 고르는 편이 쉽습니다. 초보자에게는 '어떤 상황에서 이 Skill이 호출되면 좋은가'를 떠올리는 방식이 더 잘 맞습니다.

polite-email-reply가 쓰일 장면은 대체로 이렇습니다. 누군가가 일정 확인 메일을 보냈다거나, 자료를 요청했다거나, 부탁을 거절해야 한다거나, 아직 정보가 부족해서 추가 질문이 필요한 경우입니다. 이런 장면은 반복적이고, 말투와 구조가 중요하며, 사람이 매번 처음부터 문장을 짜느라 시간을 쓰기 쉽습니다.

이렇게 장면을 먼저 고르면 Skill이 덜 흔들립니다. Skill은 만능 지식이 아니라, 특정 순간에 꺼내 드는 작은 작업 매뉴얼에 가깝기 때문입니다.¹

2단계: description부터 쓴다

많은 사람이 본문부터 쓰고 싶어 하지만, 실제로는 description이 먼저입니다. 이유는 분명합니다. 에이전트는 처음부터 Skill의 긴 본문을 다 읽는 것이 아니라, 이름과 설명을 보고 어떤 Skill이 지금 맞는지 판단하기 때문입니다.¹²

예를 들어 이런 설명은 너무 약합니다.

description: Helps with email.

이 문장을 읽고는 무엇을, 언제, 어느 정도까지 도와주는지 알기 어렵습니다. 반면 아래 문장은 훨씬 낫습니다.

description: Drafts polite Korean workplace email replies. Use when the user wants to answer a work email, acknowledge a request, ask for missing details, or decline politely.

좋은 description은 화려할 필요가 없습니다. 대신 에이전트가 연결할 수 있는 단어가 들어 있어야 합니다. 여기에는 work email, acknowledge, ask for missing details, decline politely 같은 단서가 있습니다. 이런 단서가 있어야 사용자의 요청과 Skill이 잘 만납니다.¹²

쉽게 말해 description은 자기소개가 아니라 호출 버튼입니다.

3단계: 출력 모양을 먼저 정한다

초보자가 Skill을 만들 때 결과가 들쑥날쑥해지는 가장 큰 이유 중 하나는, 출력 형식을 미리 정하지 않기 때문입니다. 지침은 열심히 써 놓았는데, 어떤 날은 한 문단으로 답하고, 어떤 날은 장황한 설명을 붙이고, 어떤 날은 핵심이 빠지는 식입니다.

그래서 첫 Skill은 결과 틀을 먼저 고정하는 편이 좋습니다. Microsoft의 지침 작성 가이드도 톤, 길이, 출력 형식을 명시하라고 권합니다. 그래야 모델이 애매한 부분을 제멋대로 추론할 가능성이 줄어듭니다.³

이번 Skill의 출력은 아래처럼 단순하게 정하겠습니다.

제목:
답장 초안:
확인 필요:

이 형식이 좋은 이유는 아주 실용적입니다. 사용자는 바로 복사해 쓸 수 있고, 에이전트는 누락된 정보가 있으면 확인 필요 아래에 정리할 수 있습니다. 결과적으로 답장을 만들어 놓고도 속으로 '근데 이거 날짜는 어디서 나온 거지?' 하고 식은땀 흘릴 일이 줄어듭니다.

4단계: 지침은 짧고 행동 중심으로 쓴다

좋은 Skill 지침은 똑똑해 보이는 문장이 아니라, 행동이 보이는 문장입니다. '정중하게 잘 답하라'는 말은 사람에게도 애매하고, 모델에게는 더 애매합니다. 대신 무엇을 먼저 보고, 무엇을 확인하고, 어떤 순서로 답을 만들지 드러내야 합니다.³

이번 Skill의 핵심 절차는 다섯 단계면 충분합니다.

1. 받은 이메일의 목적을 파악한다.

2. 요청, 일정, 질문, 거절 여부를 구분한다.

3. 답장에 꼭 필요한 정보가 빠져 있으면 추측하지 말고 확인이 필요한 항목으로 분리한다.

4. 정중하고 간결한 한국어 답장 초안을 작성한다.

5. 최종 문장을 다시 보고 과도한 약속, 단정, 공격적인 표현이 없는지 확인한다.

여기서 중요한 점은 단계가 길지 않다는 것입니다. 처음 Skill은 '잘게 쪼개되, 너무 많이 쪼개지 않는 것'이 좋습니다. 절차가 지나치게 길어지면 오히려 핵심이 흐려지고, 테스트할 때 어느 단계가 문제인지 잡기 어려워집니다.

5단계: 예시를 넣어야 Skill이 덜 헤맨다

예시는 옵션처럼 보이지만, 실제로는 꽤 강력합니다. 특히 답장의 톤이나 형식을 다뤄야 하는 Skill에서는 더욱 그렇습니다. Microsoft 가이드도 복잡한 시나리오일수록 예시가 모호함을 줄여 준다고 설명합니다.³

예시가 하는 일은 단순합니다. '이런 입력이 오면 이런 스타일로 움직여라'라는 감각을 줍니다. 말하자면 Skill에 작은 리허설을 붙여 두는 셈입니다.

예를 하나 보겠습니다.

입력:
팀장님이 내일까지 초안 보낼 수 있냐고 메일을 보냈어. 가능은 한데 오전은 어렵고 오후 3시쯤 가능해.

출력:
제목: Re: 초안 전달 일정
답장 초안:
안녕하세요.
보내주신 메일 확인했습니다.
초안은 내일 오후 3시경 전달드릴 수 있습니다.
필요하신 방향이나 우선 반영할 사항이 있다면 함께 알려 주시면 반영하겠습니다.
감사합니다.
확인 필요:
없음

이 예시는 '가능하지만 조건이 있음'이라는 상황을 보여 줍니다. Skill은 여기서 단순히 예의 바른 문장을 배우는 것이 아니라, 일정 조정과 확인 표현을 어떤 식으로 섞는지 함께 배웁니다.

하나 더 보겠습니다.

입력:
협업 제안을 정중하게 거절해야 해. 지금은 일정상 어렵고, 다음 분기에는 다시 이야기할 수 있다고 전하고 싶어.

출력:
제목: Re: 협업 제안 감사합니다
답장 초안:
안녕하세요.
좋은 제안 보내 주셔서 감사합니다.
현재 일정상 이번 기간에는 함께 진행하기 어려운 상황입니다.
다만 다음 분기에 다시 논의할 기회가 있다면 검토해 보고 싶습니다.
양해 부탁드리며, 제안 주셔서 다시 한 번 감사드립니다.
확인 필요:
다음 분기 중 구체적으로 다시 논의 가능한 시점

이 예시는 '거절'이라는 민감한 장면을 다룹니다. 초보자가 만든 Skill이 이런 예시 없이 동작하면, 생각보다 퉁명스럽거나 지나치게 장황한 답을 만들 가능성이 큽니다.

6단계: 경계조건을 써야 Skill이 안전해진다

Skill이 자주 망가지는 이유는 '무엇을 해야 하는지 몰라서'가 아니라 '어디까지 해야 하는지 몰라서'인 경우가 많습니다. 그래서 첫 Skill일수록 경계조건이 중요합니다.

쉽게 말해, 이 Skill이 하지 말아야 할 일을 써 두는 것입니다. Microsoft는 지침 작성에서 제한사항과 오류 처리, 필요한 경우 사용자에게 되묻는 규칙을 명확히 두라고 권합니다.³ 또 Skill을 실제 에이전트에 붙일 때는 발견, 로드, 활성화, 실행 단계가 분리되므로, Skill 안에 무엇을 할지뿐 아니라 언제 멈출지도 적혀 있어야 안정적입니다.²

이번 Skill의 경계조건은 이렇게 잡겠습니다.

• 사실을 모르면 추측하지 않는다.

• 사용자가 주지 않은 날짜, 금액, 약속, 승인 여부를 지어내지 않는다.

• 법률, 인사, 계약처럼 민감한 판단이 필요한 메일은 최종 결정문처럼 쓰지 않고 검토 필요를 드러낸다.

• 메일을 실제로 전송한 것처럼 말하지 않는다. 이 Skill은 초안을 만드는 역할만 한다.

이 네 줄만 있어도 Skill의 성격이 훨씬 또렷해집니다. 한마디로, 친절하지만 함부로 확정하지 않는 비서가 되는 것입니다.

7단계: 이제 SKILL.md를 직접 써 보자

처음 Skill은 욕심내지 말고 파일 하나로 끝내는 편이 좋습니다. 폴더 구조를 크게 벌리지 않아도 됩니다.

polite-email-reply/
└── SKILL.md

이제 완성본을 보겠습니다.

---
name: polite-email-reply
description: Drafts polite Korean workplace email replies. Use when the user wants to answer a work email, acknowledge a request, ask for missing details, or decline politely.
---

# Polite Email Reply

## When to use this skill
Use this skill when the user wants a polite Korean reply to a workplace email.
Typical cases include:
- acknowledging a request
- confirming or adjusting a schedule
- asking for missing information
- declining politely

## Workflow
1. Read the user's situation or the original email carefully.
2. Identify the main intent of the reply.
3. If important details are missing, do not invent them. Put them under `확인 필요`.
4. Draft a concise and polite Korean email reply.
5. Check that the reply does not make unsupported promises or claims.

## Output format
Always return the result in this format:

제목:
답장 초안:
확인 필요:

## Style rules
- Keep the tone polite, calm, and practical.
- Prefer short sentences over long explanations.
- Avoid slang, sarcasm, or emotional wording.
- If the context is unclear, be conservative.

## Boundaries
- Do not fabricate dates, approvals, amounts, or commitments.
- Do not provide legal, HR, or contractual final wording as if it is officially approved.
- Do not say the email has been sent.
- This skill drafts text only.

## Examples
### Example 1
Input:
A manager asked whether a draft can be shared tomorrow. It is possible after 3 PM.

Output:
제목: Re: 초안 전달 일정
답장 초안:
안녕하세요.
메일 확인했습니다.
초안은 내일 오후 3시경 전달드릴 수 있습니다.
추가로 우선 반영이 필요한 사항이 있다면 알려 주시면 함께 반영하겠습니다.
감사합니다.
확인 필요:
없음

### Example 2
Input:
The user needs to decline a collaboration request because the schedule is full, but wants to reopen the discussion next quarter.

Output:
제목: Re: 협업 제안 감사합니다
답장 초안:
안녕하세요.
좋은 제안 보내 주셔서 감사합니다.
현재 일정상 이번 기간에는 함께 진행하기 어려운 상황입니다.
다만 다음 분기에 다시 논의할 기회가 있다면 검토해 보고 싶습니다.
양해 부탁드립니다.
확인 필요:
다음 분기에 다시 논의 가능한 시점

이 정도면 첫 Skill로 충분히 훌륭합니다. 거대한 자료실도 없고, 스크립트도 없지만, 이미 재사용 가능한 작업 흐름이 생겼습니다. Agent Skills의 핵심은 처음부터 복잡한 구조를 만드는 데 있는 것이 아니라, 반복되는 일을 안정적인 형태로 묶는 데 있습니다.¹⁴

8단계: 실제로 테스트해 본다

Skill은 쓰는 순간보다, 테스트하는 순간 더 많은 것을 가르쳐 줍니다. 직접 돌려 보면 설명문이 너무 넓은지, 출력 형식이 흔들리는지, 경계조건이 약한지 바로 드러납니다.

처음 테스트는 어렵게 하지 마세요. 아래처럼 아주 짧은 요청 세 개만 던져 봐도 충분합니다.

• 자료 요청 메일에 오늘 중 회신하겠다는 답장 초안 써 줘.

• 일정 제안을 받았는데 그 시간은 어렵고 금요일 오전이 가능하다고 답장해 줘.

• 계약 관련 문구가 있는 메일인데 내가 확정 답변을 해도 되는지 애매해. 안전하게 초안 만들어 줘.

이때 확인할 것은 단순합니다. 첫째, Skill이 정말 호출될 만한 설명을 가지고 있는가. 둘째, 항상 정해 둔 출력 형식으로 답하는가. 셋째, 위험한 상황에서 함부로 확정하지 않는가.

Skill 지원 에이전트는 보통 시작할 때 메타데이터를 보고 어떤 Skill이 있는지 파악하고, 필요할 때 전체 SKILL.md를 불러와 사용합니다. 어떤 구현은 추가 자원까지 필요할 때만 읽습니다. 이런 흐름 덕분에 모든 지식을 한꺼번에 프롬프트에 넣지 않고도 필요한 순간에만 불러 쓸 수 있습니다.¹²

처음 만든 Skill이 자꾸 어색하게 작동한다면

이상하게도 첫 Skill은 대체로 망하지 않습니다. 대신 어색합니다. 지나치게 설명이 길거나, 자신감이 과하거나, 아무 말이나 정중하게 꾸미는 식으로 비틀거립니다.

그럴 때는 대부분 아래 셋 중 하나입니다.

• description이 흐려서 엉뚱한 상황에도 호출된다.

• 출력 형식이 약해서 답의 모양이 매번 달라진다.

• 경계조건이 약해서 없는 사실도 자연스럽게 지어낸다.

이 문제는 대개 큰 수술이 아니라 작은 수정으로 해결됩니다. description에 언제 쓰는지 한 줄 더 보태고, 출력 형식을 더 단순하게 고정하고, '추측하지 말 것' 같은 제한을 분명히 적으면 결과가 눈에 띄게 안정됩니다.

첫 Skill의 목표는 완벽함이 아니라 재사용성이다

처음 만드는 Skill에서 가장 중요한 것은 '얼마나 대단한 기능을 넣었는가'가 아닙니다. 오히려 같은 일을 다시 시켰을 때 비슷한 품질로 반복되는가가 더 중요합니다.

polite-email-reply는 아주 작은 Skill입니다. 하지만 이 작은 Skill 안에는 Agent Skills의 핵심이 거의 다 들어 있습니다. 언제 쓸지 정했고, 어떤 결과를 낼지 정했고, 어떤 순서로 움직일지 정했고, 어디서 멈춰야 하는지도 정했습니다. 바로 이 네 가지가 Skill을 단순한 좋은 프롬프트와 구별해 줍니다.

한 번 직접 만들어 보면 감이 옵니다. Skill은 생각보다 거대한 기술이 아니라, 잘 정리된 작은 작업 습관입니다. 그리고 그 습관이 쌓이면, 에이전트는 점점 덜 흔들리고 더 믿을 만한 도우미가 됩니다.

다음 장에서는 여기서 한 걸음 더 나아가, '만든 Skill이 실제로 더 잘 작동하도록' 설계하는 방법을 본격적으로 다뤄 보겠습니다.

참고

¹Agent Skills | Microsoft Learn

²How to Write and Implement Agent Skills

³Write effective instructions for declarative agents

⁴Overview - Agent Skills