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

핵심 내용

• Agent Skills 표준에서 SKILL.md의 결함을 Skill smell로 정의하고, 실제 238개 파일 분석을 통해 거의 모든 파일에서 평균 10.5개의 결함이 발견됐다고 정리
• 결함은 Frontmatter와 본문에서 다르게 발생하며, Frontmatter는 선택 단계에, 본문은 실행 단계에 영향을 줘 우선순위가 다름
• 결함 유형을 presence-based와 absence-based로 나누고, 이를 뒤집어 8가지 개선 항목으로 전환하는 점검 관점을 제시
• description, name, 3인칭 서술, 건너뛰기 방지, 경고 부각, 계획 단계, 멈출 조건, 검증·진행 기록을 기준으로 스킬 품질을 높이는 방법을 설명

적용해볼 점

• 스킬이 선택되지 않으면 본문은 읽히지 않으므로 Frontmatter부터 점검
• 다단계 스킬일수록 계획, 검증, 진행 기록, 중단 조건을 명시
• 한국어 스킬은 3인칭 표현보다 청자를 상정한 표현 여부를 더 주의 깊게 확인