Agent Skills 팁 – 스킬 작성·리뷰에서 자주 나오는 5가지 실수

Agent Skills는 사람이 읽는 문서가 아니라 에이전트 시스템의 일부다. 따라서 좋은 스킬은 자세한 설명보다 정확한 트리거, 단계적 정보 공개, 반복 작업의 스크립트화를 우선한다.

1. description을 요약문처럼 쓴다

description의 역할은 스킬 내용을 설명하는 것이 아니라 “언제 이 스킬을 로드해야 하는지”를 알려주는 것이다. 너무 넓거나 추상적이면 과발동·미발동이 모두 생긴다.

좋은 description은 보통 30~55단어 안에서 트리거 조건을 명확히 말한다.

모든 지침을 SKILL.md에 넣으면 매번 불필요한 컨텍스트가 로드된다. 공통 지침만 본문에 두고, 상황별 세부 지식은 references/로 분리해야 한다.

프론트엔드 코드베이스를 다룰 때만 references/frontend.md를 먼저 읽어라.

이런 식으로 언제 추가 파일을 읽을지 명시하는 것이 중요하다.

반복적이고 결정적인 작업은 스킬 지침보다 스크립트가 낫다. 예를 들어 문서 렌더링, 포맷 검증, 메타데이터 추출, 파일 구조 점검은 모델 추론보다 작은 CLI가 더 빠르고 재현 가능하다.

스킬은 인간 교육 자료가 아니다. 한 줄을 지웠을 때 에이전트 행동이 바뀌지 않는다면 그 줄은 필요 없는 줄이다. 비슷한 스킬을 여러 개 만들면 description 경쟁이 생겨 오히려 라우팅 품질이 떨어진다.

반드시 따라야 하는 절차라면 번호를 매기고, 각 단계의 완료 상태를 추적하게 해야 한다. 마지막에는 리뷰 또는 검증 단계를 넣어야 한다.