책에 포함된 노트처음부터 이해하는 Agent Skills: AI 에이전트를 제대로 일하게 만드는 설계법

잘 작동하는 Skill 설계법

2026-03-30Views 7약 11분

Skill은 만드는 순간보다, 현장에서 제대로 불릴 때 진가가 드러납니다. 폴더를 만들고 SKILL.md를 적는 일 자체는 생각보다 어렵지 않습니다. 진짜 어려운 일은 따로 있습니다. 사용자의 요청과 맞는 순간에 정확히 호출되고, 너무 많은 일을 떠안지 않으며, 애매한 상황에서는 멈출 줄 알고, 결과물의 모양도 흔들리지 않게 만드는 일입니다.

쉽게 말해, Skill의 품질은 "있다"보다 "믿고 쓸 수 있다"에서 갈립니다.

Agent Skills는 원래 이런 재사용성과 일관성을 높이기 위해 나온 방식입니다. 이름과 설명은 먼저 가볍게 노출되고, 정말 필요할 때만 본문과 추가 자원이 로드되기 때문에, Skill은 많이 만드는 것보다 정확하게 설계하는 것이 훨씬 중요합니다.¹

잘 만든 Skill은 똑똑한 문서가 아니라 좋은 장치다

초보자가 Skill을 처음 만들면 대개 이런 기대를 합니다. "설명을 잘 써 두면 에이전트가 알아서 잘하겠지." 물론 설명은 중요합니다. 하지만 Skill은 단순한 안내문이 아닙니다. 호출 조건, 범위, 금지선, 출력 계약, 예외 처리, 필요하면 스크립트까지 포함한 작은 작업 장치에 가깝습니다.

그래서 잘 작동하는 Skill은 보통 다음 질문에 답할 수 있습니다.

언제 켜져야 하는가?
언제 켜지면 안 되는가?
무엇까지 맡고, 무엇은 맡지 않는가?
어떤 부분은 모델이 판단하고, 어떤 부분은 규칙이나 코드가 맡는가?
실패하거나 애매할 때 어떻게 행동하는가?
결과를 어떤 형식으로 내야 하는가?

이 질문에 답이 흐리면 Skill도 흐려집니다. 반대로 이 질문에 답이 선명하면, Skill은 짧아도 강해집니다.

트리거 키워드는 "마법의 단어"가 아니라 호출 신호다

많은 사람이 트리거 키워드를 정확한 주문처럼 생각합니다. 하지만 실제로는 그렇지 않습니다. 에이전트는 보통 Skill의 name과 description을 먼저 보고, 지금 들어온 요청과 관련이 있는지 판단합니다. 그래서 중요한 것은 특정 단어 하나를 우겨 넣는 일이 아니라, 사용자가 실제로 하는 말과 Skill의 설명이 자연스럽게 만나는 것입니다.¹

예를 들어 description: Helps with documents. 같은 문장은 너무 넓습니다. 문서를 읽는 건지, 요약하는 건지, PDF를 파싱하는 건지, 서식을 맞추는 건지 알 수 없습니다. 이런 설명은 아무 데나 걸릴 수 있고, 반대로 정작 필요한 순간에는 안 걸릴 수도 있습니다.

반면 이런 설명은 훨씬 낫습니다.

Summarizes Korean meeting transcripts and extracts decisions and action items. Use when the user asks to summarize a meeting, clean a transcript, list decisions, or extract follow-up tasks.

이 설명이 좋은 이유는 세 가지입니다. 무엇을 하는지, 언제 써야 하는지, 어떤 표현과 잘 연결되는지가 함께 들어 있기 때문입니다. 실제 공개 Skill 저장소들도 이런 식으로 트리거 문구를 설계합니다. "design multi-agent system", "implement agent memory", "reduce tool complexity"처럼 사용자의 요청 장면이 떠오르는 표현이 있어야 에이전트가 매칭하기 쉬워집니다.²

여기서 기억할 점이 하나 있습니다. 트리거는 많이 넣는다고 좋아지지 않습니다. 오히려 이것도 하고 저것도 하고 모든 표현을 다 넣으려 들면 Skill이 과잉 반응합니다. "문서", "요약", "정리", "분석", "작성", "검토"를 한데 다 넣어 두면, 거의 모든 글쓰기 작업에 달라붙는 끈끈한 Skill이 되어 버립니다.

좋은 트리거 문구는 보통 이런 구조를 가집니다.

행동: summarize, extract, validate, draft, review
대상: transcript, invoice, API schema, email reply
결과: decisions, action items, score, formatted output

즉, 동사 + 대상 + 기대 결과가 드러나야 합니다.

범위는 넓을수록 좋은 게 아니라, 선명할수록 좋다

Skill이 잘 안 맞는 가장 흔한 이유는 성능 부족이 아니라 범위 과욕입니다. 하나의 Skill 안에 "요약도 하고, 계획도 세우고, 이메일도 쓰고, 일정도 뽑고, 액션 아이템도 정리한다"를 모두 넣으면 얼핏 멋져 보입니다. 하지만 이런 Skill은 정작 실전에서 자주 미끄러집니다.

왜 그럴까요? 에이전트 입장에서는 같은 문서라도 어떤 모드로 읽어야 할지 헷갈리기 때문입니다. 사용자는 "회의록 정리해 줘"라고 했는데, Skill은 요약을 해야 할지, 할 일을 뽑아야 할지, 보고서를 써야 할지 흔들릴 수 있습니다.

좋은 Skill은 스스로의 경계선을 압니다. 강한 Skill 정의에는 보통 적용 범위, 비적용 범위, 제약, 출력 모양, 품질 체크가 함께 들어갑니다.³ 다시 말해, "무엇을 할 수 있는가"만큼 "무엇은 하지 않는가"가 중요합니다.

예를 들어 meeting-helper라는 거대한 Skill 하나보다 아래처럼 나누는 편이 더 안정적입니다.

meeting-summary: 회의 내용을 짧게 요약한다.
decision-extractor: 결정 사항만 뽑는다.
action-item-extractor: 담당자와 후속 작업을 정리한다.

이렇게 나누면 트리거도 선명해지고, 테스트도 쉬워지고, 실패했을 때 원인도 빨리 찾을 수 있습니다. Skill은 백과사전이 아니라 공구함 속 도구에 가깝습니다. 드라이버 하나가 망치, 가위, 렌치까지 겸하려 하면 결국 손에 안 맞습니다.

단일 책임은 Skill을 가볍게 만들고, 디버깅도 쉽게 만든다

단일 책임이라는 말은 프로그래밍에서 자주 듣지만, Skill 설계에서도 거의 똑같이 중요합니다. 한 Skill은 한 종류의 문제를 안정적으로 푸는 데 집중해야 합니다.

이 원칙이 중요한 이유는 세 가지입니다.

첫째, 호출 정확도가 올라갑니다. 범위가 좁을수록 어떤 요청에 반응해야 하는지 분명해집니다.

둘째, 컨텍스트 낭비가 줄어듭니다. Agent Skills는 필요한 순간에만 전체 지침과 자원을 불러오는 구조인데, Skill 하나가 너무 많은 책임을 지면 본문도 길어지고 추가 자원도 불어나기 쉽습니다.¹

셋째, 수정이 쉬워집니다. 예를 들어 출력 형식이 흔들린다고 해도, action-item-extractor만 고치면 됩니다. 반대로 모든 회의 관련 일을 한 Skill이 다 떠안고 있으면 작은 수정이 다른 동작까지 흔들 수 있습니다.

실무에서는 "작은 Skill 여러 개 + 필요한 경우 묶음"이 종종 더 낫습니다. 실제 조직에서도 개별 Skill을 쌓고, 역할별로 번들처럼 묶어 쓰는 패턴이 자주 보입니다.⁴

Skill 설계의 핵심: 모델이 결정할 일과 하지 말아야 할 일을 나눠라

이 장에서 가장 중요한 원칙을 하나만 꼽으라면 이것입니다.

일관되어야 하는 것은 모델에게 맡기지 말고, 맥락 이해가 필요한 것은 모델에게 맡겨라.

이 원칙은 여러 실전 사례에서 반복해서 확인됩니다. Block의 설계 원칙은 먼저 "에이전트가 결정하면 안 되는 것"부터 정하라고 말합니다. 점수 계산, 고정된 규칙 적용, 체크리스트 판정, 형식 검증처럼 같은 입력에 같은 결과가 나와야 하는 부분은 스크립트나 템플릿, 하드 룰로 고정해야 합니다.⁵

반대로 모델이 잘하는 일도 분명합니다. 결과 해석, 사용자 상황에 맞춘 설명, 우선순위 제안, 초안 생성처럼 맥락과 언어 감각이 필요한 일입니다.⁵

이걸 아주 단순하게 나누면 두 구역입니다.

구역	맡기는 대상	대표 작업
일관성이 중요한 구역	스크립트·템플릿·고정 규칙	점수 계산, 파싱, 검증, 파일명 규칙, 포맷 검사
해석이 중요한 구역	LLM	설명, 요약, 권장안 제시, 사용자 맞춤 문장 생성

이 구분이 없는 Skill은 위험합니다. 예를 들어 리포지토리 점수를 매기는 Skill인데 점수 계산까지 모델에게 맡기면, 같은 저장소를 두 번 검사해도 점수가 달라질 수 있습니다. 반대로 모든 문장 생성까지 스크립트로 고정해 버리면, 대화형 에이전트의 장점이 사라집니다.

Microsoft의 생성형 오케스트레이션 가이드도 같은 방향을 말합니다. 중요한 작업은 결정론적 계층에 두고, 중간 위험은 승인이나 확인을 거치는 하이브리드 계층에 두며, 비교적 안전한 작업만 AI 오케스트레이터가 자유롭게 처리하게 하라는 것입니다.⁶

Skill을 설계할 때는 항상 물어보세요. "이 판단은 매번 같아야 하는가?" 같아야 한다면 모델의 친절함보다 규칙의 무뚝뚝함이 낫습니다.

예외 처리는 비상구다. 없으면 평소엔 조용해도 한 번에 망한다

처음 만든 Skill이 데모에서는 잘 되다가 실전에서 갑자기 무너지는 이유는, 대개 정상 경로만 써 두고 예외를 안 적었기 때문입니다.

Skill은 생각보다 자주 곤란한 상황을 만납니다. 입력이 비어 있을 수도 있고, 사용자가 핵심 정보를 안 줬을 수도 있고, 스크립트가 실패할 수도 있고, 요청이 Skill 범위를 넘을 수도 있습니다. 이때 아무 규칙이 없으면 에이전트는 아주 자연스럽게 틀립니다. 더 무서운 점은, 틀리면서도 그럴듯하게 말한다는 것입니다.

그래서 예외 처리는 선택이 아니라 기본 설계입니다. 특히 다음 다섯 가지는 거의 항상 미리 적어 두는 편이 좋습니다.

핵심 정보 부족: 날짜, 대상, 파일 경로, 계정, 기준값이 없으면 추측하지 말고 무엇이 필요한지 먼저 묻는다.
범위 خارج 요청: 이 Skill이 다루지 않는 일이라면 억지로 수행하지 말고 범위 밖이라고 분명히 말한다.
민감하거나 되돌리기 어려운 작업: 삭제, 결제, 외부 전송, 승인 같은 행동은 확인을 요구한다.
도구 또는 스크립트 실패: 성공한 척하지 말고 실패 사실, 실패 지점, 다음 선택지를 알려 준다.
출력 불확실성: 확정할 수 없는 값은 빈칸으로 남기거나 확인 필요로 표기한다.

이런 규칙은 신뢰를 높입니다. Microsoft의 가이드는 위험한 작업의 승인 경계선을 명시하라고 권하고, 에이전트 UX 원칙도 사용자가 에이전트의 행동을 보고 제어할 수 있어야 한다고 강조합니다.⁶⁷

좋은 Skill은 모든 답을 주는 Skill이 아닙니다. 멈춰야 할 때 멈추는 Skill입니다.

출력 형식은 장식이 아니라 계약이다

초보자가 Skill 설계에서 자주 놓치는 것이 출력 형식입니다. 하지만 실제로는 출력 형식이 Skill의 성격을 결정하는 경우가 많습니다.

같은 일을 하는 Skill이라도 출력 형식이 고정되어 있지 않으면 결과가 들쑥날쑥해집니다. 어떤 날은 표로 나오고, 어떤 날은 산문으로 나오고, 어떤 날은 핵심 항목이 빠집니다. 사람이 읽기에도 불편하지만, 다른 도구나 다음 단계의 에이전트가 이어받기에는 더 곤란합니다.

그래서 출력 형식은 처음부터 계약처럼 적는 편이 좋습니다. 예를 들면 이런 식입니다.

요약:
결정 사항:
후속 작업:
확인 필요:

또는 더 구조적인 Skill이라면 표나 JSON 스키마, 템플릿 파일을 둘 수도 있습니다. 실제 Skill 생태계에서도 연구, 계획, 구현, 리뷰 같은 작업에 대해 표준 출력 틀을 두어 일관성과 파싱 안정성을 높이려는 시도가 많습니다.⁸⁹

형식이 고정되면 좋은 점이 큽니다.

첫째, 사용자 경험이 안정됩니다. 어디를 보면 되는지 항상 같습니다.

둘째, 평가가 쉬워집니다. 같은 항목이 매번 나오는지 확인하면 되기 때문입니다.

셋째, 후속 자동화가 쉬워집니다. 다른 에이전트나 스크립트가 특정 섹션만 읽어도 됩니다.

출력 형식을 정할 때는 멋보다 사용성을 먼저 보세요. 대단한 문체보다 누락 없이 읽히는 구조가 더 중요합니다.

스크립트는 모델을 못 믿어서가 아니라, 역할을 잘 나누기 위해 쓴다

스크립트를 붙인 Skill은 괜히 고급스럽게 보일 수 있습니다. 하지만 스크립트의 핵심 가치는 화려함이 아니라 안정성입니다.

Skill에 스크립트를 붙이면 좋은 대표적인 장면은 이렇습니다. 파일 형식을 검사해야 할 때, 고정된 규칙으로 점수를 매겨야 할 때, 복잡한 문자열을 정규화해야 할 때, 외부 시스템 호출 전에 파라미터를 검증해야 할 때입니다. 이런 작업은 모델이 "대충 잘"하는 것보다 코드가 "늘 똑같이" 하는 편이 훨씬 낫습니다.⁵

예를 들어 회의록 Skill이라면 모델은 회의 내용을 요약하고 맥락을 설명하게 두고, 스크립트는 발화자 태그 정리나 타임스탬프 정규화만 맡길 수 있습니다. 평가 Skill이라면 모델은 결과 해석과 개선 제안을 맡고, 점수 계산은 스크립트가 하게 둘 수 있습니다.

여기서 중요한 건 비율이 아닙니다. Python을 몇 개 붙였는지가 아니라, 변동하면 안 되는 부분을 어디까지 밖으로 뺐는가가 중요합니다.

좋은 Skill은 헌법처럼 써야 한다

Skill 지침을 "이렇게 해 주면 좋겠어"라는 부탁처럼 쓰면, 모델은 친절하게 변형합니다. 때로는 너무 친절해서 규칙까지 바꿔 버립니다. 점수를 부드럽게 해석하고, 실패를 완곡하게 감추고, 정해진 형식을 슬쩍 생략합니다.

그래서 실전 Skill은 제안문보다 계약문에 가깝게 쓰는 편이 안전합니다. Block은 이를 "헌법처럼 써라"라고 표현합니다. 점수를 다시 계산하지 말 것, 스크립트 결과를 덮어쓰지 말 것, 정해진 보고 형식을 따를 것처럼 분명한 금지와 의무를 적어 두는 방식입니다.⁵

예를 들어 아래 두 문장은 분위기가 꽤 다릅니다.

나쁜 예:

"가능하면 아래 형식으로 답해 주세요."

좋은 예:

"반드시 아래 형식으로 답한다. 항목을 추가하거나 제거하지 않는다. 값이 없으면 없음 또는 확인 필요로 표기한다."

에이전트는 빈칸을 창의력으로 메우는 데 능합니다. 우리가 원하는 건 창의력 자체가 아니라, 창의력이 발휘되어도 되는 구역과 안 되는 구역의 구분입니다.

설계가 좋은지 확인하는 가장 쉬운 방법은 "애매한 요청"으로 흔들어 보는 것

Skill 테스트는 정답이 쉬운 요청만 던져 보면 별 의미가 없습니다. 진짜 설계 품질은 애매한 요청에서 드러납니다.

예를 들어 회의록 관련 Skill을 테스트한다면 이런 식으로 흔들어 볼 수 있습니다.

정상 요청: "이 회의 전사를 요약하고 액션 아이템을 뽑아 줘."
경계 요청: "이 문서를 정리해 줘."
범위 밖 요청: "이 회의 결과를 바탕으로 제안서까지 작성해 줘."
정보 부족 요청: "이번 회의 후속 작업 정리해 줘." 그런데 실제 회의 내용은 없음
실패 상황 요청: 스크립트가 읽지 못하는 파일 형식 제공

이 테스트에서 확인할 것은 화려함이 아닙니다. 올바른 Skill이 켜지는지, 범위를 벗어나면 멈추는지, 모르는 건 묻는지, 출력 형식이 유지되는지입니다. 결국 Skill 설계는 감이 아니라 검증의 문제입니다. 실제 운영에서도 평가와 테스트는 선택이 아니라 필수 작업으로 다뤄집니다.²

바로 써먹는 Skill 설계 체크리스트

새 Skill을 설계하거나 기존 Skill을 고칠 때는 아래 항목만 점검해도 품질이 꽤 올라갑니다.

description만 읽어도 무엇을 하고 언제 쓰는지 보이는가?
트리거 문구가 실제 사용자 표현과 연결되는가, 아니면 너무 추상적인가?
이 Skill의 비적용 범위가 적혀 있는가?
한 Skill이 한 가지 핵심 책임에 집중하고 있는가?
일관되어야 하는 판단은 스크립트·템플릿·규칙으로 고정했는가?
예외 상황에서 추측하지 않고 멈추거나 되묻도록 설계했는가?
출력 형식이 항상 같고, 다음 단계가 읽기 쉬운가?
애매한 테스트 문장으로도 설계가 버티는가?

이 체크리스트를 통과하지 못한 Skill은 대개 똑똑하지 않아서가 아니라, 경계가 흐려서 흔들립니다.

만드는 것보다, 제대로 작동하게 만드는 일이 더 중요하다

이 장의 핵심은 단순합니다. Skill은 작성물이라기보다 설계물입니다.

좋은 트리거는 Skill을 맞는 순간에만 부르고, 명확한 범위는 Skill이 넘어가지 말아야 할 선을 지켜 주며, 단일 책임은 Skill을 가볍고 수정 가능하게 만들고, 예외 처리는 Skill이 그럴듯하게 틀리는 것을 막아 줍니다. 출력 형식은 결과를 계약으로 바꾸고, 스크립트는 변동하면 안 되는 부분을 단단하게 고정합니다.

결국 Skill의 진짜 실력은 문장을 얼마나 잘 썼느냐보다, 모델의 자유와 시스템의 규칙을 얼마나 잘 나눴느냐에서 드러납니다.

Skill은 만들기보다 제대로 작동하게 만드는 일이 더 중요합니다. 그리고 그 차이는 대개 거창한 기술이 아니라, 작은 설계 원칙에서 시작됩니다.

다음 장에서는 이 설계 원칙이 더 큰 그림과 어떻게 연결되는지, 즉 컨텍스트 엔지니어링과 Skill이 만나면 왜 성능과 안정성이 함께 달라지는지를 살펴보겠습니다.