SKILL.md 작성법

좋은 Skill은 대개 문장 한 줄에서 갈린다. 더 정확히 말하면, frontmatter의 description 한 줄과 본문의 instructions 몇 문장이 그 Skill의 운명을 좌우한다. 같은 업무를 담고 있어도 어떤 Skill은 제때 불리고, 어떤 Skill은 필요할 때도 조용하다. 어떤 Skill은 한결같이 결과를 내고, 어떤 Skill은 매번 조금씩 다른 길로 샌다. 차이는 대개 지식량보다 문장 구조에 있다.

SKILL.md를 처음 쓰는 사람은 종종 이 파일을 친절한 소개서처럼 작성한다. 사람에게 설명하듯 배경을 길게 풀고, 좋은 태도를 권하고, 알아서 잘 판단해 달라고 부탁한다. 하지만 에이전트는 부탁을 잘 이해하는 존재가 아니라, 조건과 절차를 따라 움직이는 존재다. 그래서 SKILL.md는 잘 쓴 안내문보다 잘 오해되지 않는 실행문에 가까워야 한다.

description은 소개 문구가 아니라 활성화 규칙이다

에이전트는 처음부터 모든 Skill의 본문을 다 읽고 출발하지 않는다. 보통 먼저 보는 것은 name과 description 같은 메타데이터다. 다시 말해 description은 사람에게 보여 주는 광고 문구가 아니라, 에이전트가 이 Skill을 지금 열어야 하는지 판단하는 라우팅 문장이다.¹

이 지점을 놓치면 description이 금세 검색 키워드 창고가 된다. 예를 들어 SEO, blog, content, writing, article, publish 같은 단어를 마구 쌓아 넣으면 얼핏 잘 잡힐 것 같지만, 실제로는 경계가 흐려진다. 너무 넓은 description은 관련 없는 작업에도 불쑥 튀어나오고, 너무 추상적인 description은 정작 필요할 때 선택되지 않는다.

좋은 description은 적어도 네 가지를 담는다.

• 이 Skill이 무엇을 하는가

• 어디까지를 다루는가

• 언제 불러야 하는가

• 언제는 부르면 안 되는가

즉, 메타데이터는 검색용 태그가 아니라 활성화 규칙이어야 한다. Skill의 현관문에는 멋진 수사가 아니라 출입 조건이 붙어 있어야 한다.

예를 들어 아래 두 description을 보자.

# 나쁜 예
name: report-writer
description: 보고서 작성에 도움을 줍니다.

이 문장은 거의 아무것도 결정해 주지 않는다. 어떤 보고서인지, 어떤 입력을 기대하는지, 어떤 상황에서 써야 하는지, 어디까지가 범위인지 알 수 없다.

# 좋은 예
name: executive-brief
description: 원자료, 회의 노트, 리서치 메모를 바탕으로 임원용 1페이지 보고서를 작성한다. 주간 보고, 경영진 업데이트, 의사결정용 요약 요청에서 사용한다. 고객 발송용 제안서, 기술 장애 보고서, 장문 분석 보고서에는 사용하지 않는다.

이 문장은 훨씬 작지만 훨씬 많은 결정을 담고 있다. 작업 범위가 보이고, 트리거가 보이고, 예외도 보인다. 이런 description이 있어야 에이전트가 오작동 없이 Skill을 고른다.³

frontmatter는 단순하게, 그러나 경계는 분명하게

여러 구현에서 확장 필드를 지원하더라도, 휴대성과 예측 가능성을 생각하면 SKILL.md의 frontmatter는 먼저 핵심 필드에 충실한 편이 좋다. 이름은 짧고 분명해야 하고, description은 자동 활성화의 기준이 되도록 써야 한다. 특히 공개 문서들은 name과 description을 중심으로 Skill을 식별하고, 디렉터리 이름과 name의 일치를 요구하거나 권장한다. 또한 본문은 길어지기보다 핵심 절차를 담고, 자세한 내용은 별도 파일로 분리하는 구성이 안정적이다.²

이 원칙은 단순해 보이지만 실전에서 큰 차이를 만든다. frontmatter에 너무 많은 의도를 넣으려 하면, 오히려 중요한 정보가 묻힌다. 반대로 핵심만 담으면 에이전트는 발견 단계에서 빠르게 판단하고, 본문에 들어왔을 때 더 정확하게 읽는다.

description을 설계할 때 유용한 문장 틀은 다음과 같다.

[무엇을 한다]. [주요 입력 또는 산출물]. [어떤 요청에서 사용한다]. [어떤 요청에는 사용하지 않는다].

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

description: 녹취록, 회의 메모, 화상회의 요약을 바탕으로 의사결정 사항과 액션 아이템 중심의 회의록을 작성한다. 주간 회의 정리, 프로젝트 스탠드업, 의사결정 기록 요청에서 사용한다. 고객 공지문, 홍보용 요약, 인터뷰 기사 작성에는 사용하지 않는다.

여기서 중요한 것은 키워드를 늘리는 일이 아니라 경계를 또렷하게 만드는 일이다. description은 많이 맞히는 문장이 아니라, 틀릴 일을 줄이는 문장이어야 한다.

instructions는 조언이 아니라 실행 지시문이어야 한다

description이 문을 여는 문장이라면, instructions는 안으로 들어온 뒤 에이전트가 실제로 걷는 길이다. 이때 가장 흔한 실수는 조언형 문장으로 쓰는 것이다.

예를 들어 이런 문장들이 있다.

• 독자가 이해하기 쉽게 쓰면 좋습니다.

• 적절한 근거를 넣는 것이 좋겠습니다.

• 가능하면 간결하게 작성하세요.

사람끼리 일할 때는 이런 말이 통할 수 있다. 하지만 에이전트에게는 너무 넓고, 너무 애매하고, 너무 착하다. 에이전트가 흔들리는 이유는 대개 말을 몰라서가 아니라, 말이 행동으로 바뀌지 않아서다.

같은 내용을 실행 지시형으로 바꾸면 이렇게 된다.

좋은 instructions에는 세 가지 특징이 있다.⁴

• 동작이 보이는 동사를 쓴다

• 판단 기준이 숫자나 조건으로 드러난다

• 하지 말라는 말만 하지 않고 대안을 함께 준다

예를 들어 금지 규칙도 이렇게 써야 한다.

나쁜 금지 규칙은 이렇다.

과장된 표현은 사용하지 않는다.

이 문장은 금지사항은 알리지만 대안을 주지 않는다. 더 나은 문장은 이렇게 바뀐다.

확인되지 않은 성과 표현은 사용하지 않는다. 성과를 언급할 때는 기간, 기준 수치, 비교 대상을 함께 제시한다. 근거가 없으면 성과 문장을 삭제한다.

이제 에이전트는 막히지 않는다. 멈춰야 할 이유와 대신 선택할 행동이 함께 있기 때문이다.

좋은 instructions는 순서보다 분기점을 잘 쓴다

절차를 쓸 때 사람은 자꾸 직선으로 적고 싶어 한다. 먼저 읽고, 다음에 정리하고, 마지막에 출력한다. 물론 그 흐름도 필요하다. 하지만 실제 오작동은 순서보다 갈림길에서 더 자주 생긴다.

그래서 SKILL.md 본문에는 단순 단계 나열만 아니라 결정 조건이 함께 들어가야 한다. 리서치 Skill이라면 최신 출처가 없을 때 어떻게 할지, 이메일 Skill이라면 민감 이슈가 포함될 때 어디서 멈출지, 보고서 Skill이라면 수치가 충돌할 때 어떤 자료를 우선할지를 문장으로 적어 두어야 한다.

이때 useful한 방식이 rigid와 flexible를 구분하는 것이다. 손상 비용이 큰 작업은 딱딱하게, 판단 여지가 필요한 작업은 유연하게 설계하는 편이 낫다. 배포, 마이그레이션, 외부 발송처럼 한 번 잘못하면 손해가 큰 일은 체크리스트와 명시적 단계가 잘 맞는다. 반면 코드 리뷰나 기획 아이디어 발산처럼 여러 해석이 가능한 일은 우선순위, 기준, 출력 형식을 정해 주는 쪽이 더 자연스럽다.⁵

즉, 모든 Skill을 똑같은 문체로 쓸 필요는 없다. 다만 어떤 경우든 에이전트가 갈림길에서 혼자 상상으로 메우지 않게 만드는 문장은 필요하다.

체크리스트, 결정표, 예시 출력이 오작동을 줄인다

많은 사람이 SKILL.md를 전부 산문으로만 쓰려 한다. 하지만 에이전트가 안정적으로 따라야 하는 구간에서는 구조화된 표현이 훨씬 강하다. 특히 세 가지가 자주 효과를 낸다. 체크리스트, 결정표, 예시 출력이다.

체크리스트는 순서를 빼먹으면 문제가 생기는 작업에 좋다. 예를 들어 사내 보고서 작성 Skill이라면 아래처럼 쓸 수 있다.

## 제출 전 확인
- [ ] 요청한 기간의 데이터만 사용했다
- [ ] 핵심 수치 3개를 본문 첫 부분에 배치했다
- [ ] 리스크와 다음 액션을 분리해서 적었다
- [ ] 입력 자료에 없는 사실을 추정하지 않았다

결정표는 갈림길이 많은 작업에 유용하다.

## 문의 유형별 처리
| 조건 | 처리 방식 |
|---|---|
| 환불, 법무, 계약 해지 표현이 있음 | 초안을 작성하지 말고 승인 필요 상태로 정리한다 |
| 배송 지연 문의이며 정책 문서가 확인됨 | 정책 기준으로 답변 초안을 작성한다 |
| 주문 정보가 없거나 핵심 정보가 누락됨 | 필요한 추가 정보를 먼저 요청한다 |

예시 출력은 형식 붕괴를 막는 가장 싼 보험이다. 에이전트는 설명보다 패턴을 더 잘 따른다. 그래서 길게 설명하는 대신 결과물의 뼈대를 보여 주는 편이 훨씬 안정적이다.³

## 출력 형식 예시
요약:
- 이번 주 핵심 변화 2문장

주요 수치:
- 매출:
- 전환율:
- 이탈률:

리스크:
- 

다음 액션:
1. 
2. 

설명이 나쁜 것은 아니다. 다만 형식이 중요한 업무에서는 설명만 있는 Skill보다 체크리스트와 예시를 함께 가진 Skill이 더 꾸준하다.

나쁜 SKILL.md는 대체로 착하고 넓고 흐리다

실패하는 SKILL.md를 읽어 보면 이상할 정도로 비슷하다. 대개 말투는 친절하고, 범위는 넓고, 규칙은 흐리다. 한마디로 좋은 말은 많고 실행 정보는 적다.

아래는 흔히 볼 수 있는 나쁜 예다.

---
name: writing-helper
description: 글쓰기를 도와주는 스킬
---

# Writing Helper

좋은 글을 작성합니다.
독자가 이해하기 쉽게 쓰고, 적절한 예시를 넣고, 논리적으로 전개합니다.
가능하면 전문적으로 보이게 작성합니다.

겉으로 보기엔 틀린 말이 없다. 하지만 실제로는 거의 쓸 수 없다. 어떤 글인지 모르고, 언제 써야 하는지 모르고, 어떤 출력인지 모르고, 무엇을 금지하는지도 모르기 때문이다.

같은 목적을 조금만 더 좁히고 실행 가능하게 바꾸면 이렇게 된다.

---
name: tech-blog-post
description: 개발자 대상 기술 블로그 초안을 작성한다. 코드, 릴리스 노트, 문서에서 핵심 메시지를 뽑아 한글 기술 글로 정리할 때 사용한다. 보도자료, 마케팅 카피, 고객 공지문 작성에는 사용하지 않는다.
---

## 목표
주어진 소스에서 핵심 변화와 실무 영향을 추출해 한글 기술 블로그 초안을 작성한다.

## 입력
- 필수: 코드 변경 내용, 문서 또는 릴리스 노트 중 하나
- 선택: 타깃 독자, 원하는 분량, 회사 문체 가이드

## 작성 절차
1. 소스에서 무엇이 바뀌었는지 한 문장으로 요약한다.
2. 변경 이유와 실무상 의미를 분리해 정리한다.
3. 독자가 바로 이해해야 하는 개념은 예시와 함께 설명한다.
4. 확인되지 않은 배경 추정은 쓰지 않는다.
5. H2 기준으로 구조를 나누고, 도입부에서 문제 상황을 먼저 제시한다.

## 출력 규칙
- 한국어로 작성한다.
- 독자는 개발자라고 가정한다.
- 제목 후보 3개를 먼저 제시한다.
- 본문 끝에는 적용해 볼 다음 단계 2가지를 넣는다.

## 금지
- 마케팅 과장 표현을 쓰지 않는다.
- 소스에 없는 성능 수치를 만들어 넣지 않는다.
- 코드 블록을 넣을 때 언어 태그를 생략하지 않는다.

좋아진 이유는 화려해서가 아니다. 범위, 입력, 절차, 출력, 금지가 분리되었기 때문이다. 에이전트는 이런 문서에서 훨씬 덜 헤맨다.

description과 instructions를 같이 써야 비로소 하나의 Skill이 된다

description만 좋아도 안 된다. instructions만 좋아도 안 된다. 둘은 서로를 보완해야 한다.

description이 너무 넓으면 좋은 instructions가 숨어 버린다. 반대로 description이 정교해도 본문이 모호하면, Skill은 제때 불렸는데 안에 들어가서 길을 잃는다. 이 둘의 관계를 간단히 정리하면 이렇다.

• description은 이 Skill이 불릴 상황을 정의한다.

• instructions는 불린 뒤 어떻게 움직일지를 정의한다.

• 체크리스트와 예시는 흔들릴 지점을 잡아 준다.

그래서 SKILL.md를 쓸 때는 늘 두 번 생각해야 한다. 첫 번째 질문은 이것이다. 이 Skill은 언제 열려야 하는가. 두 번째 질문은 이것이다. 열리고 나서 에이전트는 정확히 무엇을 해야 하는가.

둘 중 하나라도 흐리면 Skill은 반쪽짜리가 된다.

바로 써먹는 SKILL.md 본문 템플릿

처음부터 완벽한 문장을 쓰려 하지 말고, 아래 구조를 뼈대로 시작하면 좋다.

---
name: skill-name
description: 이 Skill이 무엇을 하고, 어떤 요청에서 사용하며, 어떤 경우에는 사용하지 않는지 적는다.
---

## 목표
이 Skill이 최종적으로 만들어야 하는 결과를 2~3문장으로 적는다.

## 입력
- 필수 입력
- 선택 입력
- 입력이 부족할 때의 처리 방식

## 절차
1. 먼저 확인할 것
2. 분기 조건
3. 생성 또는 분석 단계
4. 검토 단계
5. 멈춰야 하는 조건

## 출력 규칙
- 형식
- 길이
- 포함 항목
- 금지 항목

## 확인 체크리스트
- [ ] 필수 항목 포함
- [ ] 추정 금지 준수
- [ ] 승인 필요 여부 확인

## 예시 출력
결과물의 뼈대를 보여 주는 짧은 예시

이 구조의 장점은 복잡한 철학이 없다는 점이다. 대신 에이전트가 오해할 만한 지점을 미리 자리에 앉혀 둔다. 목표, 입력, 절차, 출력, 확인. 이 다섯 덩어리만 분명해도 Skill의 품질은 크게 올라간다.

다 쓰고 나면 꼭 해봐야 하는 세 가지 점검

SKILL.md는 쓰는 순간보다 고쳐 쓰는 순간 좋아진다. 초안을 만들었다면 적어도 세 가지는 꼭 점검하는 편이 좋다.

첫째, 이 description을 보고 정말 이 Skill이 떠오를 만한가를 확인한다. 사용자가 실제로 할 법한 요청 문장을 몇 개 써 보고, 반대로 비슷하지만 이 Skill이 뜨면 안 되는 요청도 같이 적어 본다. 이 과정을 거치면 description의 경계가 훨씬 선명해진다.³

둘째, instructions에서 추상어를 걷어 낸다. 적절히, 충분히, 자연스럽게, 보기 좋게 같은 말이 남아 있으면 거의 항상 더 구체화할 수 있다. 적절히는 무엇인지, 충분히는 몇 개인지, 자연스럽게는 어떤 구조인지로 바꾼다.

셋째, 예외 상황을 일부러 넣어 본다. 자료가 부족한 경우, 상충하는 수치가 있는 경우, 민감한 표현이 들어간 경우를 상상해 본다. 그때 에이전트가 멈춰야 하는지, 질문해야 하는지, 축소해서 진행해야 하는지가 문서 안에 드러나야 한다.

좋은 SKILL.md는 처음부터 똑똑한 문서가 아니다. 실패한 자리마다 문장이 단단해진 문서다.

결국 SKILL.md는 문장력보다 판단력의 문서다

글을 잘 쓰는 사람이라고 해서 SKILL.md를 잘 쓰는 것은 아니다. 오히려 반대인 경우도 많다. 사람을 설득하는 문장은 넓고 유연할수록 좋을 때가 있지만, 에이전트를 움직이는 문장은 좁고 분명할수록 좋기 때문이다.

정리하면 이렇다. 메타데이터는 검색 키워드가 아니라 활성화 규칙으로 쓴다. description에는 작업 범위, 트리거, 예외를 함께 담는다. 본문은 조언형이 아니라 실행 지시형으로 쓴다. 체크리스트, 결정표, 예시 출력은 품질을 올리는 장식이 아니라 오작동을 줄이는 장치다. 그리고 나쁜 SKILL.md를 고치는 가장 좋은 방법은 더 멋지게 쓰는 것이 아니라, 더 정확하게 멈추고 더 분명하게 지시하는 것이다.

에이전트는 좋은 말을 좋아하지 않는다. 잘못 읽지 않을 말을 좋아한다. SKILL.md 작성법의 핵심은 바로 거기에 있다.

참고

¹Claude를 skills로 확장하기 - Claude Code Docs

²Creating custom skills - Claude.ai Documentation

³GitHub - mgechev/skills-best-practices

⁴Agent Skill 만들기: SKILL.md 작성 가이드

⁵How to Write an AI Agent Skill [Step-by-Step Guide 2026]