[Agent Skills 완전정복 #4] 잘 만드는 스킬의 원칙

Agent Skills 시리즈 네 번째 편. 스킬을 "만들 줄" 아는 것과 "잘 만드는" 것은 다릅니다.
이번엔 공식 문서가 권하는 좋은 스킬의 원칙을 정리합니다.

---

🎓 1. 진짜 경험에서 출발하라

가장 흔한 실수는 LLM에게 맥락 없이 "스킬 만들어줘"라고 시키는 것입니다. 그러면 "에러를 적절히 처리하라" 같은 뻔하고 일반적인 문장만 나와요. 가치 있는 스킬은 현장 경험에 뿌리를 둡니다.

• 실제 작업에서 추출 — 에이전트와 진짜 작업을 한 번 끝낸 뒤, 통한 단계 / 내가 교정한 부분 / 입출력 형식 / 내가 알려준 프로젝트 맥락을 스킬로 정리
• 기존 산출물에서 합성 — 사내 문서·런북·API 스펙·코드 리뷰 코멘트·실제 장애 사례를 LLM에 먹여 스킬로 만들기. 핵심은 일반론이 아닌 우리 프로젝트만의 자료

---

🔁 2. 실행으로 다듬어라

초안은 보통 부족합니다. 실제 작업에 돌려보고 결과를 (실패뿐 아니라 전부) 다시 반영하세요. "무엇이 오탐을 유발했나? 무엇을 놓쳤나? 뭘 잘라낼 수 있나?"

최종 출력만 보지 말고 실행 과정(trace)을 읽으세요. 에이전트가 헤맨다면 지침이 모호하거나, 현재 작업과 무관한 지침을 억지로 따르거나, 기본값 없이 선택지만 잔뜩 준 경우입니다.

---

🧠 3. 컨텍스트를 아껴 써라

스킬이 활성화되면 본문 전체가 컨텍스트를 차지합니다. 모든 토큰이 에이전트의 집중력을 두고 경쟁해요.

에이전트가 모르는 것만 넣어라

"PDF가 뭔지, HTTP가 어떻게 동작하는지"는 설명할 필요 없습니다. 프로젝트 고유 규칙, 도메인 절차, 비자명한 엣지 케이스, 써야 할 특정 도구·API에 집중하세요.

# 너무 장황 — PDF가 뭔지 이미 안다
PDF는 텍스트·이미지를 담는 흔한 파일 형식이고, 추출하려면 라이브러리가...

# 더 낫다 — 모를 법한 것으로 바로 진입
텍스트 추출은 pdfplumber 사용. 스캔 문서면 pdf2image + pytesseract로 폴백.

각 내용마다 자문하세요: "이 지침이 없으면 에이전트가 틀릴까?" 아니라면 잘라내세요.

응집된 단위로 설계하라

함수 설계와 같습니다. 너무 좁으면 한 작업에 여러 스킬이 로드되고, 너무 넓으면 정확히 호출하기 어려워요. "DB 조회 + 결과 포매팅"은 한 단위지만, 여기에 "DB 관리"까지 넣으면 과욕입니다.

적당한 상세함을 노려라

지나치게 빠짐없는 스킬은 오히려 해롭습니다. 간결한 단계별 안내 + 동작하는 예시 하나가 방대한 문서보다 낫습니다. 모든 엣지 케이스를 다루고 있다면, 대부분은 에이전트의 판단에 맡길 수 있는지 따져보세요.

큰 스킬은 점진적 로딩으로 쪼개라

SKILL.md는 500줄·5,000토큰 이하로. 상세 자료는 references/로 옮기되, "언제 읽어야 하는지"를 명시하세요. "API가 200이 아닌 응답을 주면 references/api-errors.md를 읽어라"가 그냥 "자세한 건 references/ 참고"보다 훨씬 유용합니다.

---

🎚️ 4. 통제의 강도를 조절하라

모든 부분이 같은 수준의 강제력을 가질 필요는 없습니다. 작업의 취약성에 맞춰 지침의 구체성을 조절하세요.

• 자유를 줘라 — 여러 방법이 유효하고 변형을 허용할 때. 이땐 "어떻게"보다 "왜"를 설명하는 게 효과적 (예: 코드 리뷰에서 무엇을 볼지만 안내)
• 엄격하게 규정하라 — 작업이 취약하거나, 일관성이 중요하거나, 정해진 순서를 꼭 지켜야 할 때 (예: DB 마이그레이션은 "이 명령을 정확히 이 순서로, 플래그 추가 금지")

메뉴가 아니라 기본값을 줘라. "pypdf, pdfplumber, PyMuPDF, pdf2image 중 골라" 대신 → "pdfplumber를 써라. 스캔본은 pdf2image+pytesseract." 기본값 하나 + 탈출구로.

선언이 아니라 절차를 가르쳐라. 특정 정답("orders를 customers에 조인하고...")이 아니라, 재사용 가능한 방법("스키마를 읽고 → FK 규칙으로 조인 → 요청의 필터를 WHERE로 → 집계해 표로")을 적으세요.

---

🧩 5. 효과적인 지침 패턴들

자주 쓰이는 재사용 기법들입니다. 전부 쓸 필요는 없고, 작업에 맞는 것만 고르세요.

• Gotchas(함정) 섹션 — 합리적 추측을 벗어나는 환경 고유 사실. 많은 스킬에서 가장 가치 높은 부분. 예: "users 테이블은 소프트 삭제라 WHERE deleted_at IS NULL 필수." 에이전트를 교정할 일이 생기면 여기에 추가하세요.
• 출력 형식 템플릿 — 형식을 산문으로 설명하기보다 구체적 틀을 제시. 에이전트는 패턴 매칭에 강합니다. 긴 템플릿은 assets/에 두고 참조.
• 체크리스트 — 의존성·검증 게이트가 있는 다단계 워크플로우에서 단계 누락 방지.
• 검증 루프 — "작업 → 검증 스크립트 실행 → 실패 시 수정 → 통과할 때까지 반복."
• Plan-Validate-Execute — 배치/파괴적 작업은 중간 계획을 만들고, 원본(진실의 출처)과 대조 검증한 뒤에만 실행. 핵심은 계획을 검증하는 스크립트.
• 재사용 스크립트 번들링 — 매 실행마다 같은 로직(차트 생성·파싱)을 재발명한다면, 한 번 테스트한 스크립트를 scripts/에 넣으세요.

---

✍️ 마무리

핵심은 하나로 수렴합니다 — 에이전트가 이미 아는 건 빼고, 모르는 것만 간결하게, 실행으로 검증하며 다듬어라.

👉 다음 편 → [#5] 스킬이 '제때' 불려오게 하는 법 (description 최적화)

---

📎 출처: 이 글은 Agent Skills 공식 문서 — Best practices (© Anthropic, CC BY 4.0)를 한국어로 번역·재구성한 것입니다.

---