📌 에이전트에 SKILL, 언제 꼭 필요하고 언제 오히려 독일까 (붙이기 전 판단 기준 한 장 정리)

• SKILL(스킬) : SKILL.md 파일 하나가 든 폴더. 여기에 지시문 + 선택적으로 파이썬 스크립트나 리소스를 같이 묶는 구조

• 점진적 공개(progressive disclosure, 필요할 때만 펼쳐 읽기) : 시작할 땐 이름,설명만 컨텍스트에 올라가고 본문은 그 작업이 떴을 때만 읽음. 스크립트는 bash로 돌려서 출력값만 토큰을 먹음

• 꼭 필요한 경우 : 1) 같은 절차를 반복,결정론적으로 돌릴 때 2) 파이썬 등 실행 스크립트를 묶어 매번 같은 결과를 보장해야 할 때 3) 사내 브랜드,용어,워크플로 같은 조직 지식을 표준화할 때 4) 모델이 기본으론 못 하는 특수 작업(예: 문서 양식 채우기)을 메꿀 때

• 굳이 안 만들어도 되는 경우 : 1) 한 번 쓰고 말 일(그냥 프롬프트) 2) 코드베이스가 이미 알려주는 상시 프로젝트 사실(이건 CLAUDE.md / AGENTS.md 몫) 3) 외부 도구,API 연결(이건 MCP, 외부 도구 연결 프로토콜 몫) 4) 린터,CI가 결정론적으로 강제하는 규칙이나 모델이 이미 잘하는 것

• 엔터프라이즈,서비스 적용 : 효과 맞음. managed settings(엔터프라이즈 관리 설정)로 조직 전체 배포 가능. 단 스킬은 실행 가능한 코드라 "소프트웨어 설치하듯" 감사 필요(외부 호출,데이터 노출 주의). 또 API 커스텀 스킬은 워크스페이스 공유지만, http://claude.ai 업로드 스킬은 사용자별이라 관리자가 중앙에서 못 잠금

💬 결론부터. SKILL은 "많이 붙일수록 똑똑해진다"가 아니라, 반복되는 결정론적 작업을 스크립트까지 묶어 박제할 때 빛납니다. 왜냐면 점진적 공개라서 안 쓰면 컨텍스트를 안 먹고 & 쓰면 파이썬이 매번 같은 결과를 보장해주거든요 (그래서 "결정론"이라는 말이 어울림).

반면에 진짜 흔한 실수는 따로 있는데, 모델이 이미 아는 사실이나 린터,CI가 알아서 강제하는 규칙을 굳이 스킬로 박는 겁니다. 그건 스킬이 아니라 상시 컨텍스트(CLAUDE.md)나 외부 연결(MCP)이 할 일이거든요. 질문 하나, 지금 만들려는 그 스킬 다음 작업에서도 또 쓸 일인가요? 아니라면 프롬프트 한 줄이 더 쌉니다.

엔터프라이즈,서비스로 굴리는 것도 효과는 맞아요. 다만 스킬은 "실행되는 코드"라 설치하듯 감사해야 하고, http://claude.ai 업로드 스킬은 사용자별이라 관리자가 중앙에서 못 잠근다는 점(그래서 보통 Code,API,managed settings로 표준화함)은 미리 알아두면 좋습니다.

물론 다 틀릴 수도. 소규모 팀이면 스킬 만들고,유지하고,감사하는 품이 프롬프트보다 비쌀 수 있고 & 모델이 좋아지면 오늘 공들인 스킬이 다음 업데이트엔 필요 없어질 수도 있으니까. 어쩌면 지금은 안 만드는 게 정답일지도.

(댓글용 출처 — 클릭 이유 먼저)

• 스킬이 왜 컨텍스트를 거의 안 먹는지 원리가 궁금하면 → 공식 개요 docs

• "언제,어떻게 잘 쓰나" 작성 가이드가 필요하면 → 베스트 프랙티스

• 왜 이렇게 설계했는지 아키텍처,철학이 궁금하면 → Anthropic 엔지니어링 블로그

#AgentSkills #ClaudeCode #AI에이전트

🔗 출처 (공식 docs):

• Agent Skills 개요 — https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview

• 스킬 작성 베스트 프랙티스 — https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices

• Anthropic 엔지니어링 블로그(설계 배경) — https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills

• (Claude Code 한정) Skills in Claude Code — https://code.claude.com/docs/en/skills

Claude