Claude Code는 디스크에서 실제로 Skills를 설치하는 유일한 Claude 인터페이스이므로, Custom Instructions에 관한 다른 모든 안내와는 접근 방식이 다릅니다. 이 글은 폴더가 작동하는 방식, 보관할 가치가 있는 Skills의 조건, 사람들이 시간을 낭비하는 지점을 다루는 실용적인 가이드입니다.
Claude Code에서 Skills가 작동하는 방식
Skills는 .claude/skills/ 디렉터리에 저장됩니다. 각 Skill은 그 안에 SKILL.md가 들어 있는 하위 폴더입니다. 중요한 위치는 두 곳입니다.
-
프로젝트 - 저장소 내부의
.claude/skills/입니다. Skill이 코드와 함께 이동하므로 팀원 모두가 사용할 수 있습니다. 프로젝트에 특화된 내용은 여기에 둡니다. - 개인 - 홈 디렉터리에 있는 같은 경로입니다. 작업하는 모든 항목에 적용됩니다. 개인적인 작업 습관은 여기에 둡니다.
한 번에 하나의 항목만 저장하는 Custom Instructions와 달리, Claude Code에는 여러 Skills를 저장하고 현재 작업에 맞는 것을 불러올 수 있습니다. 따라서 좋은 Skill의 조건도 달라집니다. 올바른 Skill이 선택될 만큼 설명이 정확해야 하고, 모든 작업에 선택되지 않을 만큼 범위가 좁아야 합니다.
실제로 자리를 차지할 가치가 있는 Skill의 조건
이런 것들을 많이 만들어 보면 일정한 패턴이 보입니다. 좋은 Skill은 정보가 아니라 결정을 기록합니다.
REST API가 무엇인지 나열하는 Skill은 모델이 이미 알고 있는 내용에 토큰을 낭비합니다. 반면 "이 저장소에서는 모든 엔드포인트가 RFC 7807 형식으로 오류를 반환하며, 그렇지 않은 세 곳은 레거시이므로 복사해서는 안 된다"고 말하는 Skill은 영원히 보관할 가치가 있습니다. 모델이 추론할 수 없는 결정이기 때문입니다.
판단 기준은 이렇습니다. 팀에 합류한 유능한 엔지니어에게 알려줘야 하는 내용이라면 Skill에 넣으세요. 이미 알고 있을 내용이라면 빼세요.
갖춰 둘 가치가 있는 카테고리
팀 표준에 따른 코드 리뷰
일반적인 리뷰 의견은 잡음에 불과합니다. 팀의 실제 규칙과 그동안 논의하고 합의한 내용을 담은 리뷰 Skill은 리뷰를 의견이 아니라 체크리스트로 바꿉니다.
테스트 규칙
어떤 프레임워크를 사용하는지, 테스트 이름은 어떻게 정하는지, 무엇을 모킹하고 무엇은 절대 모킹하지 않는지, 이 코드베이스에서 충분한 커버리지로 보는 기준은 무엇인지 정합니다. 이것이 없으면 학습 데이터에서 가장 흔했던 스타일로 테스트가 작성됩니다.
디버깅 및 인시던트 대응
로그가 어디에 있는지, 어떤 대시보드가 어떤 질문에 답하는지, 에스컬레이션 전에 확인할 네 가지가 무엇인지 기록합니다. 새벽 3시에 그 가치를 톡톡히 하는 Skill입니다.
인프라 및 배포
배포 순서, 프로덕션에서 실행해도 안전한 작업과 그렇지 않은 작업, 점검 시간이 필요한 마이그레이션을 기록합니다. 위험한 부분을 명시하는 것이 핵심입니다.
문서화 및 기술 문서 작성
문서가 저장되는 위치, 페이지가 따르는 구조, 팀의 문서 스타일에서 튜토리얼과 레퍼런스가 어떻게 다른지 기록합니다.
건너뛸 항목
언어 튜토리얼. Claude에게 Python 문법을 설명하는 Skill은 이미 Python 문법을 알고 있는 대상에게 Python 문법을 설명하는 것과 같습니다.
거대한 만능 Skill. 프런트엔드, 백엔드, 테스트, 배포를 하나의 Skill에서 다루면 계속 로드되지만 매번 대부분의 내용이 관련 없습니다. 나누세요.
한 달 후면 오래될 내용. 버전 번호, 현재 스프린트 목표, 당번 담당자의 이름 같은 내용입니다. Skills는 오래 유지되는 결정을 위한 것입니다.
모호한 설명. 설명에 Skill이 적용되는 시점이 명확히 드러나지 않으면 선택되지 않거나 항상 선택됩니다. 어느 쪽이든 쓸모가 없습니다.
빈 페이지 대신 템플릿으로 시작하기
가장 어려운 부분은 아이디어가 아니라 형식입니다. 얼마나 구체적으로 작성할지, 무엇을 뺄지, 선택이 제대로 작동하도록 설명을 어떻게 작성할지가 문제입니다. 이미 검증된 결과물에서 그대로 가져올 만한 부분이 바로 이것입니다.
개발자, DevOps 엔지니어, 아키텍트를 위한 역할별 Skill 파일을 일반 .md 형식으로 제공합니다. Claude Code Skill로 사용하거나 Custom Instructions에 붙여 넣을 수 있습니다.
Claude Code Skills →
개발자 Skills →
DevOps Skills →
아키텍트 Skills →
Claude Code를 사용하지 않는데도 이 페이지에 오셨다면, 웹에서 Claude를 사용할 때 이에 해당하는 기능은 Custom Instructions입니다.
KissMySkills는 독립적인 마켓플레이스이며 Anthropic, OpenAI 또는 그 밖의 어떤 AI 기업과도 제휴, 공식 승인 또는 관련이 없습니다. Claude Code는 Anthropic의 제품입니다.
