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

AI 에이전트 스킬 정의 파일(SKILL.md)의 품질 결함인 "Skill smell" 개념을 분석한 글이다. UC Irvine 연구진이 실제 SKILL.md 238개를 분석한 결과 결함이 없는 파일은 단 1개였고 평균 10.5개의 결함이 존재했다. 결함 유형 26종을 10개 품질 범주로 분류하고, Frontmatter와 Body 섹션별 구체적인 개선법을 제시한다.

핵심 포인트

238개 실제 SKILL.md 분석에서 평균 결함 10.5개, 결함 없는 파일은 단 1개 — 2026년 7월 arXiv 프리프린트(David Boram Hong 외 2인) 연구 결과다.
26종의 Smell 유형 중 20개는 Body, 6개는 Frontmatter를 대상으로 하며 Frontmatter 결함은 스킬 선택 자체를 방해한다.
3가지 핵심 Frontmatter 요소: '무엇·언제·키워드' 3요소 설명 / 기능이 즉시 전달되는 명칭 / 3인칭 시점.
5가지 Body 핵심 요소: 단계 건너뛰기 방지 명시 / 경고 별도 섹션화 / 계획 단계 포함 / 중단 시점 정의 / 중간 검증 체크포인트 삽입.
한국어 SKILL.md는 주어 생략이 자연스러워 3인칭 시점 검증이 상대적으로 쉽다는 실용적 관찰도 담겼다.

상세 정리

연구 배경: "코드 스멜"에서 착안한 "Skill smell" 개념을 공식 정의하고 실제 마켓플레이스 SKILL.md 238개를 분석했다. 결함 없는 파일 1개라는 결과는 현황이 심각함을 보여준다.
구조 이해: SKILL.md는 에이전트 시작 시 읽는 Frontmatter(name, description)와 스킬 선택 후 읽는 Body로 구성 — 결함 위치에 따라 '선택 실패'와 '실행 품질 저하'로 영향이 달라진다.
10개 품질 범주: 불충분한 가이던스(단계 없는 워크플로우, 미순위 옵션), 과잉 가이던스(경직된 커맨드 시퀀스), 검증 누락, 완료 세이프가드 누락, 컨텍스트 과부하, 가드레일 누락, 근거 불충분, 보안 위험(XML 인젝션), 컨벤션 위반, 출력 구조 누락.
Frontmatter 1 — 3요소 설명: 무엇을 하는지 + 언제 사용하는지 + 관련 키워드 모두 포함. 예: "DevOps 이벤트·GitLab Korea 밋업·DevSecOps 컨퍼런스용 블로그 홍보 텍스트 생성."
Frontmatter 2 — 명확한 명칭: 스킬 이름만으로 기능이 바로 전달돼야 한다 ("blog-review" ← "review").
Frontmatter 3 — 3인칭 시점: Description은 스킬을 에이전트로 표현하는 3인칭 문체로 작성.
Body 1 — 단계 건너뛰기 방지: 필수 단계를 명시하고 에이전트의 합리화를 선제 차단 ("기존 초안이 있더라도 원본 자료를 직접 읽어라"처럼 예외 없음을 명시).
Body 2 — 경고 강조: 중요한 주의사항은 별도 헤더와 "gotcha" 형식으로 분리해 본문에 묻히지 않게 한다.
Body 3 — 계획 단계 포함: 복잡한 태스크는 실행 전 중간 계획 및 방향 확인 단계를 명시적으로 요구한다.
Body 4 — 중단 시점 정의: 에이전트가 사람 입력을 요청해야 하는 상황(불명확한 경우, 되돌릴 수 없는 행동)을 구체적으로 지정한다.
Body 5 — 검증·추적 임베드: 최종 단계뿐 아니라 중간 과정에도 검증 체크포인트와 진행 기록을 포함 — 사후 검증만으로는 부족하다.
한계: 주로 영문 스킬, 단일 마켓플레이스 분석이라 일반화에 한계. 단 결함 역방향 정의를 체크리스트로 활용하면 실용적이다.