AI 에이전트 스킬이 발동하지 않는 이유: SKILL.md 결함과 개선법

스킬을 만들었는데 필요한 순간에 실행되지 않은 적이 있으신가요? 발동은 했는데 엉뚱한 절차를 밟거나, 처음에는 잘 되다가 컨텍스트를 보탤수록 결과의 만족도가 떨어진 경험도 있으실 겁니다.

Agent Skills는 2025년 개방형 표준으로 공개된 뒤 특정 제품에 종속되지 않는 형식으로 자리 잡았습니다. SKILL.md 파일 하나에 절차와 맥락을 담아 두면 여러 에이전트가 이를 읽고 작업을 수행합니다. 도입이 빠른 만큼 스킬을 직접 만들어 쓰는 실무자도 늘고 있죠.

그러나 이 파일을 어떻게 쓰는 게 효과적인지와 같은 기준은 아직 정리되는 중입니다. Agent Skills 명세는 Frontmatter의 필드와 제약을 정하지만, 본문에는 형식 제약을 두지 않습니다. 무엇을 어떤 순서로 담을지는 작성자에게 맡겨져 있죠.

2026년 7월 arXiv에 공개된 프리프린트(동료 심사 전 공개 논문)는 이 지점을 파고들었는데요. UC Irvine 연구진이 실제로 쓰이는 SKILL.md 파일 238개를 분석했더니, 결함이 하나도 없는 파일은 단 1개였습니다. 나머지는 파일당 평균 10.5개의 결함을 안고 있었고요. 연구진은 이 결함을 ‘Skill smell’이라 부릅니다.

이 글에서는 Skill smell이 무엇이고 어디서 왜 생기는지, 어떤 유형이 있는지 정리합니다. 아울러 Skill smell을 방지하고 해결하는 방법을 Frontmatter 3가지 항목과 본문 5가지 항목으로 나눠 살펴봅니다. 마지막으로 그 8가지 항목을 제 업무용 스킬 5개에 적용해 본 결과도 다룹니다.

Skill smell이란 무엇인가

먼저 Skill smell의 정의와 발생 원인, 문제가 드러나는 시점을 짚고, 26가지 유형을 살펴보겠습니다.

정의와 유래

Skill smell은 SKILL.md 작성 모범 사례를 위반한 안티패턴을 뜻합니다. 예를 들어, "SKILL.md 본문은 높은 수준을 유지하고 맥락에 특화된 안내는 참조 문서로 위임하라"는 모범 사례가 있는데요. 이를 뒤집으면 "저수준 구현 세부사항을 참조 문서나 스크립트로 위임하지 않고 본문에 담는다"가 되죠. 이는 Skill smell 중 하나인 Undelegated Detail(위임하지 않은 세부사항)입니다.

이 개념은 업계에서 널리 합의된 건 아닌데요. 2026년 7월 arXiv에 공개된 프리프린트에서 UC Irvine의 David Boram Hong, Aaron Imani, Iftekhar Ahmed 연구진이 제안했습니다. 연구진은 SKILL.md 작성법을 다룬 온라인 자료 29개를 검토해 모범 사례 26개를 추렸는데요. 이를 각각 뒤집어 위반 사례를 정의하고 Skill smell이라 명명했죠. 이름은 코딩 모범 사례를 어긴 상태를 뜻하는 'Code smell'에서 따왔고요.

어디서 왜 발생하나

Skill smell은 SKILL.md의 두 영역에서 서로 다른 이유로 발생합니다. SKILL.md는 크게 Frontmatter와 본문으로 나뉘는데요. Frontmatter는 name과 description 두 필수 항목을 채우게 돼 있습니다. 본문은 마크다운으로 정해진 양식 없이 자유롭게 쓰면 되고요.

본문에는 '무엇을 어떤 순서로 담을지'와 같은 규정이 없다 보니 작성자는 쓰고 싶은 내용을 제약 없이 넣을 수 있죠. UC Irvine 연구진이 정리한 26개 Skill smell 중 20개가 이 본문을 대상으로 합니다.

Frontmatter는 사정이 다릅니다. 명세가 정하는 건 형식과 최소 요건까지입니다. name은 길이와 표기 규칙만 규정하고, description은 무엇을 하는지와 언제 쓰는지를 담으라고 정하지만 이를 지켰는지 기계적으로 확인할 방법은 없죠. 따라서 이름만으로 무슨 일을 하는지 알 수 없거나, 설명에 언제 쓰는지가 빠지거나, 3인칭으로 쓰이지 않아도 형식 검증은 통과합니다. 나머지 6개 Skill smell이 여기서 나오는데, 이 가운데 절반이 형식 검증으로는 잡히지 않는 항목입니다.

문제가 언제 드러나나

SKILL.md는 두 영역이 서로 다른 시점에 읽힙니다. Frontmatter의 name과 description은 에이전트가 시작할 때 설치된 모든 스킬에 대해 로드됩니다. 본문은 에이전트가 해당 스킬을 활성화하기로 결정했을 때 로드되고요.

SKILL.md 로드 시점과 스킬 선택 단계

두 영역의 문제는 각기 다른 결과로 나타나는데요. Frontmatter에 문제가 있으면 스킬이 선택되는 단계에서 걸립니다. 이름만으로 무슨 일을 하는지 알 수 없거나 설명에 언제 쓰는지가 빠져 있으면, 본문이 아무리 충실해도 에이전트가 그 스킬을 고르지 않을 수 있죠.

본문의 문제는 스킬이 선택된 다음에 나타납니다. 넣지 않아도 될 내용을 넣거나, 넣어야 할 내용을 빠뜨리는 경우인데요. 전자는 컨텍스트를 잡아먹고, 후자는 에이전트가 올바르게 판단하는 데 필요한 근거를 제공하지 못합니다. 지시와 무관한 정보를 담거나, 중요한 안내를 누락하거나, 지시를 효과적이지 않은 방식으로 제시한 스킬은 에이전트에게 공급되는 정보의 질을 낮춰 성능에 부정적 영향을 미칠 수 있습니다.

연구진은 이처럼 제약 없는 SKILL.md 본문이 스킬 품질에 큰 편차를 만들 수 있다고 지적합니다. 실제로 연구진이 분석한 SKILL.md 파일 238개 가운데 Skill smell이 하나도 없는 파일은 1개뿐이었고요. 분석 대상 스킬은 파일당 평균 10.5개의 Skill smell이 있는 것으로 나타났습니다.

26개 스멜은 어떻게 나뉘는가

연구진은 26개 Skill smell을 두 가지 기준으로 분류했습니다. 하나는 ‘무엇 때문에 결함이 되는가’이고, 다른 하나는 ‘결함의 성격이 무엇인가’입니다.

첫 번째 기준으로는 26개 Skill smell이 presence-based 6개와 absence-based 20개로 나뉩니다. presence-based는 잘못된 내용이 파일에 들어 있어서 결함이 되는 경우고, absence-based는 있어야 할 내용이 빠져서 결함이 되는 경우죠. 앞서 살펴본 Frontmatter 6개, 본문 20개와는 숫자만 같을 뿐 다른 묶음인데요. 본문을 대상으로 한 Series of Commands가 여기서는 presence-based 6개에 들어갑니다.

이 구분에 따라 스킬을 고치는 방식도 달라지는데요. 잘못된 내용이 파일에 들어 있어서 문제인 결함은 해당 줄을 찾아 수정하면 되지만, 있어야 할 내용이 빠져서 문제인 결함은 내용을 새로 넣어야 하죠.

두 번째 기준으로는 근본적인 품질 결함의 성격에 따라 10개 범주로 나뉩니다.

위 표에 정리한 10개 범주는 앞서 살펴본 Frontmatter와 본문 구분과는 다른 축입니다. Frontmatter를 대상으로 한 6개 Skill smell은 컨텍스트 비대, 보안 위험, 관례 위반 세 범주에 나뉘어 들어가죠.

표만 봐서는 각 Skill smell 유형이 실제 파일에서 어떤 모습인지 잡히지 않는데요. 대표적인 세 가지 Skill smell을 예로 살펴보겠습니다. 아래는 논문에서 인용한 게 아니라 설명을 위해 구성한 예시입니다.

예시 1. Confusing Skill Description (컨텍스트 비대)

SKILL.md 파일 238개 중 75개(32%)에서 발견된 항목입니다.

# 문제가 있는 예
---
name: blog-review
description: 블로그 원고를 검토합니다.
---

Frontmatter에 무엇을 하는지는 나와 있지만 언제 쓰는지와 키워드가 없습니다. 세 요소 중 하나라도 빠지면 에이전트가 해당 스킬을 고르지 못할 수 있는데요. 에이전트는 name과 description만 읽고 스킬 선택 여부를 판단하기 때문입니다. 본문에 아무리 좋은 절차를 써 두어도 이 단계를 넘지 못하면 스킬 실행 자체가 이뤄지지 않죠.

# 개선한 예
---
name: blog-review
description: >-
  기술 블로그 원고를 문체 기준과 용어 표준에 따라 검토합니다.
  초안 검토, 용어 확인, 문장 길이 점검이 필요할 때 사용합니다.
---

무엇을 하는지에 더해 언제 쓰는지를 명시하고, '초안 검토'와 '용어 확인', '문장 길이 점검'이라는 키워드를 넣었습니다. 사용자가 요청에 이런 표현을 쓰면 에이전트가 스킬을 찾아 실행할 수 있습니다.

예시 2. Series of Commands (지침 과잉)

238개 중 148개(62%)에서 발견된 항목으로, 잘못된 내용이 들어 있어서 결함이 되는 6개 Skill smell 가운데 가장 흔합니다.

# 문제가 있는 예
## 원고 검토 절차
1. `cd /home/user/blog/drafts` 로 이동한다
2. `python3 /opt/tools/style_check.py --input draft.md --config /etc/style.yaml` 을 실행한다
3. 출력된 `result.json` 을 연다

본문에 경로와 인자까지 구체적으로 명시돼 있습니다. 이때 파일 위치가 바뀌거나 도구 옵션이 달라져도 에이전트는 본문에 기재한 명령을 그대로 실행하려 하고, 그 지점에서 작업이 어긋납니다. 상황에 맞게 실행 방식을 조정할 여지를 주지 않았기 때문입니다.

# 개선한 예
## 원고 검토 절차
1. 검토 대상 원고를 찾는다. 경로는 프로젝트 설정을 따른다
2. 문체 점검 도구를 실행한다. 사용법은 `references/style-check.md` 를 참고한다
3. 점검 결과를 확인한다

각 단계에서 달성할 목표만 남기고 실행 방법은 에이전트에게 맡겼습니다. 도구 사용법은 참조 문서로 옮겨서 도구가 바뀌어도 참조 문서만 고치면 됩니다.

예시 3. Rationalization Loophole (완수 보장 장치 부재)

238개 중 223개(94%)에서 발견된 가장 흔한 항목입니다.

# 문제가 있는 예
## 원고 검토 절차
1. 문체를 점검한다
2. 용어 표준을 확인한다
3. 결과를 보고한다

본문에 기재한 절차 자체는 문제가 없습니다. 다만 각 단계를 반드시 거쳐야 한다는 지침이 없는데요. 에이전트가 '이 원고는 짧으니 용어 확인은 생략해도 되겠다'고 판단하면 2번을 건너뜁니다. 잘못 작성한 줄이 없기 때문에 파일만 봐서는 문제를 발견하기 어렵습니다.

# 개선한 예
## 원고 검토 절차
1. 문체를 점검한다
2. 용어 표준을 확인한다
3. 결과를 보고한다

원고가 짧거나 이미 검토된 것으로 보여도 2번을 건너뛰지 않는다.

본문에 절차를 건너뛸 만한 이유를 미리 적고 그럼에도 수행하라고 명시했습니다. 앞의 두 예시는 잘못 쓴 부분을 고치는 작업이었지만, 이 경우는 원래 절차를 그대로 두고 지침을 덧붙이는 작업입니다.

SKILL.md를 어떻게 써야 하나

앞서 살펴본 26개 Skill smell을 없애는 방법은 원칙적으로 간단합니다. 각 유형의 정의를 뒤집으면 그대로 모범 사례가 되기 때문이죠. 다만 모든 Skill smell을 한꺼번에 개선하기는 어려운데요. 앞서 살펴본 구분을 활용하면 어디부터 개선할지 정하는 데 도움이 됩니다.

SKILL.md의 Frontmatter는 에이전트가 시작할 때 읽히고, 본문은 스킬이 선택된 다음에 읽힙니다. Frontmatter에서 Skill smell로 걸리면 본문은 읽히지도 않으니, Frontmatter를 먼저 손보는 게 좋습니다.

본문 Skill smell은 대부분 있어야 할 내용이 빠져서 생기는 결함입니다. 잘못 쓴 줄을 찾아 고치는 게 아니라 없는 내용을 새로 써 넣어 개선해야 하죠.

지금부터 Skill smell을 개선하기 위해 Frontmatter에서 반드시 갖춰야 할 3가지 항목과 본문에 채워 넣어야 할 5가지 항목을 차례로 살펴보겠습니다.

SKILL.md 점검 항목 8가지와 점검 순서

먼저 스킬이 선택되게 만든다

에이전트는 시작 시점에 name과 description만 읽고 어떤 스킬을 쓸지 판단합니다. 이 단계를 통과하지 못하면 본문에 무엇을 써뒀든 읽히지 않습니다.

SKILL.md의 형식은 Agent Skills 명세(agentskills.io)가 정합니다. 2025년 공개된 개방형 표준으로, 특정 제품에 종속되지 않고 여러 에이전트가 이 형식을 함께 씁니다. 명세가 Frontmatter에 대해서는 필드와 제약을 못 박아 뒀는데요. 다만 형식을 넘어선 부분은 권장에 그치거나 아예 다루지 않습니다. 아래 3가지는 명세가 정한 선이 어디까지인지를 함께 짚으면서 살펴보겠습니다.

1. description에 세 요소를 모두 담습니다

   명세는 description에 세 가지를 담으라고 권합니다. 스킬이 무엇을 하는지, 언제 사용하는지, 에이전트가 관련 작업을 알아보는 데 도움이 될 키워드입니다. 명세가 강제하는 건 1024자 이내라는 길이뿐이고, 세 요소는 권장에 머무릅니다. 즉 셋 다 빠져도 형식 검증은 통과합니다. 첫 문장에 스킬이 하는 일을 쓰고, 둘째 문장을 '~할 때 사용합니다'로 시작해 발동 조건을 적습니다. 이때 사용자가 실제로 쓸 법한 표현을 함께 넣습니다. '원고 검토'보다 '초안 검토, 용어 확인, 문장 길이 점검'처럼 구체적인 작업명이 매칭에 유리하고요. 특히 '언제 쓰는지'가 없으면 에이전트가 지금 상황이 이 스킬을 실행해야 할 상황에 해당하는지 판단할 근거가 없습니다.

2. name만으로 무슨 일을 하는지 알 수 있게 짓습니다

   명세가 name에 대해 정하는 건 형식뿐입니다. 1자 이상 64자 이하, 소문자와 숫자와 하이픈만, 하이픈으로 시작하거나 끝낼 수 없고, 하이픈을 연달아 쓸 수 없으며, 상위 디렉터리 이름과 정확히 일치해야 합니다. 이름을 어떻게 지을지는 정하지 않죠. 따라서 형식만 맞추고 뜻은 비어 있는 이름이 나옵니다. review나 check처럼 대상이 빠진 이름, 팀 안에서만 통하는 약어가 그렇습니다. 무슨 일을 하는지가 이름에 드러나야 합니다. blog-review나 review-blog처럼 대상과 동작을 함께 넣으면 충분하고요. 명세가 유효한 이름으로 든 예시도 pdf-processing, data-analysis, code-review처럼 이 형태입니다. 이름이 구체적일수록 스킬을 여러 개 설치했을 때 서로 구분됩니다.

3. description을 3인칭으로 씁니다

   명세에 인칭 규정은 없습니다. 다만 명세가 제시한 description 예시 어디에도 작성자나 사용자를 주어로 둔 문장은 없습니다. 좋은 예로 든 것도 'Extracts text and tables from PDF files, fills PDF forms...'처럼 스킬이 하는 일을 그대로 서술하죠. 작성자나 사용자가 아니라 스킬을 주어로 삼습니다. '제가 원고를 검토해 드립니다'가 아니라 '기술 블로그 원고를 검토합니다'처럼 씁니다. '이 스킬을 쓰면 원고를 검토할 수 있습니다'처럼 사용자를 주어로 둔 문장도 마찬가지고요. 한국어는 주어를 생략할 때가 많아 인칭이 겉으로 드러나지 않는데요. 따라서 '~해 드립니다', '도와드립니다'처럼 청자를 상정한 표현이 섞이지 않았는지를 기준으로 삼으면 됩니다. description은 시작 시점에 설치된 모든 스킬의 것이 한자리에 모여 읽힙니다. 목록 안에서 줄마다 화자가 달라지면 에이전트가 무엇을 고를지 판단하기 어려워집니다.

본문에 빠진 것을 채운다

여기서부터는 스킬이 선택된 다음의 이야기입니다. 명세는 본문에 형식 제약을 두지 않습니다. 권장 섹션을 몇 가지 들 뿐, 무엇을 어떤 순서로 담을지는 정하지 않죠. 따라서 아래 5가지는 규정이 아니라 작성 가이드와 실무 관행을 기준으로 삼았습니다. 본문 Skill smell은 대부분 있어야 할 내용이 빠져서 생기는데요. 다음 내용이 누락됐다면 새로 써 넣어야 합니다.

1. 건너뛰면 안 되는 단계를 명시합니다

   절차 아래에 한 줄을 덧붙이면 됩니다. 이때 단계 번호가 아니라 단계 이름으로 지목하는 편이 안전한데요. 절차가 바뀌면 번호가 어긋나기 때문입니다. '2번을 건너뛰지 않는다'보다 '용어 표준 확인은 생략하지 않는다'가 낫습니다. 건너뛸 만한 이유를 미리 적고 그럼에도 수행하라고 쓰면 더 분명해지고요. 절차를 나열하는 것만으로는 각 단계가 필수인지 선택인지 알 수 없습니다. 에이전트가 '이번엔 생략해도 되겠다'고 판단할 여지가 남죠. 명시해 두면 어느 단계가 협상 대상이 아닌지가 파일에 남습니다.

2. 놓치면 안 되는 경고를 눈에 띄게 표시합니다

   주의사항은 별도 섹션으로 분리하고 헤더를 답니다. 흔히 발생하는 문제와 그 해결 방법도 함께 적습니다. 본문 중간에 한 문장으로 적어 두면 다른 지침과 구분되지 않기 때문인데요. 별도로 표시해 두면 지침이 길어져도 중요한 내용이 묻히지 않습니다.

3. 복잡한 작업 앞에 계획 단계를 둡니다

   절차 맨 앞에 '작업을 분해하고 계획을 제시한 뒤 실행한다'는 단계를 넣습니다. 상황에 따라 접근 방식이 나뉘는 작업이라면 조건과 그때의 선택을 함께 적습니다. 여러 단계를 거치는 작업을 바로 실행시키면 방향이 어긋났을 때 확인할 지점이 없기 때문인데요. 계획 단계를 두면 실행 전에 방향을 점검할 기회가 생깁니다.

4. 멈추고 물어야 하는 조건을 적습니다

   판단이 갈리는 지점, 되돌릴 수 없는 작업 직전, 입력이 불충분한 경우를 기준으로 삼습니다. 각각에 대해 무엇을 물어야 하는지까지 적으면 더 분명해집니다. 스킬이 모든 상황을 담을 수는 없기 때문인데요. 현재 스킬로 다루지 못하는 상황을 만났을 때 어떻게 해야 하는지가 적혀 있지 않으면 에이전트가 스스로 판단해 임의로 작업을 진행합니다. 그 결과물은 기대했던 바와 어긋날 수 있죠. 작업을 멈추고 물어야 하는 상황을 조건으로 적어 두면 스킬 범위 밖의 상황도 뜻에 최대한 부합하게 통제할 수 있습니다. 물론 모든 예외를 본문에 담지는 않아도 됩니다.

5. 검증과 진행 기록을 절차 안에 둡니다

   검증은 마지막에 붙이는 것이 아니라 절차 중간에 둡니다. 각 단계의 산출물이 무엇이고 그것이 어떤 조건을 충족해야 하는지를 적습니다. 진행 기록은 단계별 상태를 남기게 하면 되고요. 출력을 한 번에 만들고 끝내면 중간에 어긋난 지점을 확인할 수 없고, 다단계 작업이라면 어디까지 처리했는지도 남지 않기 때문입니다. 기록을 남기면 작업이 중단됐을 때 어디부터 이어갈지 알 수 있습니다.

SKILL.md 점검, 실제로 해보면 무엇이 걸리나

앞서 정리한 Frontmatter 3가지와 본문 5가지 점검 항목을 제 업무용 스킬 5개의 SKILL.md에 적용해봤습니다.

점검 결과는 다음과 같습니다.

Frontmatter 3항목은 5개 SKILL.md 모두 통과했고, 본문 5항목에서 스킬별로 결과가 갈렸습니다.

이 글에서는 핵심 특징 세 가지를 짚어보고자 합니다. Frontmatter가 전부 통과한 이유, 3인칭 항목이 한국어에서 작동하는 방식, 건너뛰기 방지가 한 스킬에만 있었던 이유가 그 내용입니다.

Frontmatter는 첫 스킬의 형식이 그대로 복제됐습니다

무엇이 나왔나

세 항목 모두 5개 SKILL.md에서 문제가 없었습니다. description에는 무엇을 하는지와 함께 Use when: 뒤에 발동 조건이 적혀 있었고, 트리거 명령어와 대상 행사명 같은 키워드도 들어 있었습니다.

description: "인포그랩 DevRel 행사 홍보 문구 자동 생성.
  Use when: (1) /event-promo로 전체 홍보 콘텐츠 생성,
  (2) GitLab Korea 밋업, n8n Korea 밋업, DevSecOps 유저 컨퍼런스 홍보.
  Outputs in Korean."

왜 그랬나

5개 스킬을 비슷한 시기에 만들면서 SKILL.md에 처음 쓴 형식을 그대로 반복했습니다. Use when: 뒤에 번호를 붙여 조건을 나열하고 Outputs in Korean.으로 닫는 구조가 5개 중 4개에서 같았죠.

무엇을 알게 됐나

SKILL.md 형식을 처음에 잘못 잡았다면 5개 파일 모두 같은 결함이 있었을 것입니다. Frontmatter는 첫 스킬을 만들 때 한 번 잘 정해두면, 이후 다른 스킬을 만들 때 좋은 참조 모델이 됩니다.

3인칭 항목은 한국어로 쓰면 대체로 통과합니다

무엇이 나왔나

5개 SKILL.md 모두 통과했습니다. 형태는 조금씩 달랐지만 모두 동일하게 3인칭 요건을 충족했죠.

왜 그랬나

한국어는 주어를 생략해도 문장이 성립합니다. 명사구로 끝내든 서술형으로 쓰든 작성자나 사용자가 주어로 드러나지 않습니다. 영어라면 I review...나 You can use this to...처럼 인칭이 표면에 나타나지만, 한국어에서는 그런 문장이 반드시 나오지 않고, 주어가 없어도 문장이 자연스럽습니다.

무엇을 알게 됐나

한국어로 쓴 SKILL.md라면 '~해 드립니다' 같은 표현만 확인하면 되고, 3인칭 준수 여부를 점검하는 데 시간이 크게 걸리지 않습니다. 그러나 영어로 쓴 SKILL.md라면 꼼꼼하게 문장을 살펴야 해 3인칭 준수 여부를 확인하는 데 시간이 더 걸릴 수 있습니다.

건너뛰기 방지는 다단계 스킬에 있었습니다

무엇이 나왔나

건너뛰기 방지 문구는 infoletter 스킬의 SKILL.md 한 곳에만 명시적으로 있었습니다. 이 스킬은 콘텐츠 수집, 기획, 작성, 검토가 각각 별도 명령으로 나뉘어 있어 앞 단계의 산출물이 파일로 남는데요. SKILL.md에서는 그 산출물을 '기존 초안'이라고 부릅니다.

1. 원문 확인 필수: 기존 초안이 있어도 원문(릴리즈 노트, 블로그, 외부 콘텐츠)을
   직접 읽고 요약

SKILL.md에는 '기존 초안이 있어도'를 명시해 건너뛸 만한 이유를 미리 기재했고, '직접 읽고 요약'이라는 문구를 담아 ‘그럼에도 지시를 수행해 건너뛰기를 방지하라’는 뜻을 담았습니다.

왜 그랬나

infoletter 스킬은 콘텐츠 수집 단계에서 이미 내용 핵심을 요약해 둡니다. 그래서 작성 단계에서는 참고 자료 원문 대신 그 요약 결과물을 보고 쓸 수 있죠. 그러면 원문을 거치지 않고 요약을 다시 요약하게 되는데요. 뉴스레터에 담는 내용을 정확하게 반영하려고 이 문구를 넣었습니다.

무엇을 알게 됐나

나머지 네 스킬의 SKILL.md에 건너뛰기 방지 문구가 없는 건 필요하지 않아서이기도 합니다. 앞서 본 것처럼 infoletter 스킬은 단계가 많고 각 단계에서 참조할 자료도 많아 중간에 특정 작업을 건너뛸 여지가 큽니다. 반면 단계가 적고 한 번에 끝나는 스킬은 건너뛸 지점 자체가 적기에 이런 방지 조치를 하지 않아도 되고요.

맺음말

지금까지 Skill smell의 정의와 발생 지점, 26가지 유형의 분류, 이를 방지하고 해결하는 8가지 방법, 실제 업무용 스킬에 적용해 본 결과를 살펴봤습니다. 요점은 다음과 같은데요.

1. Skill smell은 SKILL.md의 두 영역에서 서로 다른 이유로 생깁니다. 본문은 명세가 형식 제약을 두지 않아 작성자가 무엇이든 넣을 수 있고, Frontmatter는 형식이 정해져 있지만 그 형식을 지켰는지만 확인될 뿐 내용의 충실도는 검증되지 않습니다. 26개 중 20개가 본문에서, 6개가 Frontmatter에서 나옵니다.
2. 두 영역은 읽히는 시점이 달라 문제도 다르게 드러납니다. Frontmatter의 name과 description은 에이전트가 시작할 때 모든 스킬에 대해 로드되고, 본문은 스킬이 선택된 다음에 로드됩니다. Frontmatter에서 걸리면 본문은 읽히지도 않으니, Frontmatter를 먼저 개선하는 편이 낫습니다.
3. 각 유형의 정의를 뒤집으면 그대로 모범 사례가 됩니다. Frontmatter에서는 description에 세 요소를 담고, name에 하는 일이 드러나게 하고, 3인칭으로 씁니다. 본문에서는 건너뛰면 안 되는 단계를 명시하고, 경고를 부각하고, 계획 단계를 두고, 멈추고 물어야 하는 조건을 적고, 검증과 진행 기록을 절차 안에 둡니다. 이때 잘못된 내용이 들어 있어서 문제인 결함은 해당 줄을 고치면 되지만, 있어야 할 내용이 빠져서 문제인 결함은 새로 써 넣어야 합니다.
4. 점검해 보니 Frontmatter는 5개 스킬 모두 통과했습니다. 다만 품질보다 습관에 가까웠는데요. 처음 쓴 형식을 다음 파일로 그대로 옮겨 갔기 때문입니다. 뒤집어 말하면 첫 스킬의 형식을 잘못 잡았다면 5개가 모두 같은 결함을 안고 있었을 겁니다. 한국어로 쓴 SKILL.md라면 3인칭 항목의 무게도 다릅니다. 주어를 생략해도 문장이 성립해 작성자나 사용자가 주어로 드러나는 경우가 드물기 때문에 '~해 드립니다' 같은 표현만 걸러도 충분합니다.
5. 본문 항목은 스킬의 성격을 따라 갈렸습니다. 건너뛰기 방지 문구는 다단계 워크플로인 infoletter 스킬에만 명시적으로 있었습니다. 단계가 많고 참조할 자료가 많을수록 건너뛸 여지가 크기 때문이죠. 반대로 한 번에 끝나는 스킬에 계획 단계나 진행 기록이 없는 건 결함이라기보다 그럴 필요가 없었던 것에 가깝습니다.

참고 자료

1. David Boram Hong, Aaron Imani, Iftekhar Ahmed, "From Anatomy to Smells: An Empirical Study of SKILL.md in Agent Skills", arXiv:2607.01456, 2026, https://arxiv.org/abs/2607.01456
2. "Specification", Agent Skills, https://agentskills.io/specification
3. "Skill authoring best practices", Claude Docs, https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
4. "Agent Skills", agentskills/agentskills GitHub, https://github.com/agentskills/agentskills