🧠 Claude Code Skills, 진짜 쓸 줄 아는 사람은 따로 있다

 

"그냥 마크다운 파일 아닌가요?"

Claude Code를 조금 써본 분들이라면 한 번쯤 이렇게 생각하셨을 거예요. Skills라는 기능을 처음 보고 "어, 그냥 프롬프트 적어두는 파일이네"라고 가볍게 넘겨버리는 거죠. 솔직히 저도 처음엔 그랬어요.

그런데 Anthropic이 직접 공개한 Skills 활용 경험을 보면 생각이 완전히 달라집니다. 지금 Anthropic 사내에서는 수백 개의 Skills가 실제 업무에 활용되고 있고, 이걸 제대로 이해한 팀과 그렇지 않은 팀 사이에는 개발 속도에서 눈에 띄는 차이가 생기고 있어요. 또 2025년 10월 정식 출시 이후 커뮤니티에서 자체 제작된 Skills 수만 8만 5천 개를 넘었다는 통계도 있을 정도입니다.

오늘은 "Skills를 제대로 쓰는 법"을 처음 접하는 분들도 이해할 수 있도록 풀어서 정리해드릴게요.

Skills가 '그냥 마크다운'이 아닌 이유

Skills에 대한 가장 흔한 오해가 바로 "텍스트 파일일 뿐"이라는 건데요.

실제로는 많이 달라요. Skills는 폴더 단위로 구성되며, 마크다운 파일 외에도 스크립트, 예시 코드, 데이터 파일, 템플릿 에셋 등 무엇이든 담을 수 있습니다. Claude Code는 이 폴더 전체를 탐색하고, 상황에 따라 적절한 파일을 스스로 골라 활용해요.

쉽게 말하면, Skills는 Claude에게 건네는 "업무 인수인계 패키지"예요. 지침서(SKILL.md)만 있는 게 아니라 실제로 쓸 수 있는 도구들이 한 묶음으로 들어있는 거죠. 신입 직원에게 업무 가이드 파일만 주는 게 아니라, 참고 자료, 자주 쓰는 양식, 실제 사례까지 통째로 주는 것과 같은 개념이에요.

그리고 중요한 점 하나 — Skills는 Claude.ai 웹앱, Claude Code, API 등 모든 Claude 플랫폼에서 수정 없이 동일하게 작동합니다. 한 번 잘 만들어두면 어디서든 재사용이 가능한 거예요.

Anthropic이 분류한 9가지 Skills 유형

Anthropic이 사내 Skills를 전수 조사하니 크게 9가지 유형으로 나뉘더래요. 하나씩 살펴볼게요.

첫 번째는 라이브러리 & API 레퍼런스입니다. 내부 라이브러리나 외부 SDK를 Claude가 올바르게 사용하도록 안내하는 Skills예요. 흔히 빠지는 실수들과 코드 스니펫이 포함되면 효과가 훨씬 커져요.

두 번째는 제품 검증(Product Verification)입니다. 코드가 실제로 잘 작동하는지 확인하는 Skills인데요. Playwright나 tmux 같은 도구와 연동해서 회원가입 플로우, 결제 흐름을 자동으로 검증하도록 만들 수 있어요. Anthropic은 "검증 Skills를 잘 만드는 데 엔지니어가 일주일을 써도 아깝지 않다"고 할 정도입니다. 자동화된 QA 팀을 하나 만드는 셈이거든요.

세 번째는 데이터 조회 & 분석입니다. 모니터링 스택과 연결해서 "지난 화요일에 무슨 일이 있었어?"라는 자연어 질문에 Claude가 데이터를 직접 뽑아 분석하게 만드는 Skills예요.

네 번째는 업무 프로세스 & 팀 자동화입니다. 스탠드업 포스팅, 티켓 생성, 주간 요약 등 반복 업무를 한 명령어로 처리하는 Skills죠. 이전 실행 결과를 로그로 남기면 다음 번에 더 자연스러운 결과가 나온다는 것도 포인트예요.

다섯 번째는 코드 스캐폴딩 & 템플릿입니다. 새 기능 개발 시 프레임워크 보일러플레이트를 자동으로 생성해주는 Skills예요. 인증, 로깅, 배포 설정이 기본으로 들어간 앱 생성기를 만들어두면 팀 전체가 혜택을 봐요.

여섯 번째부터 아홉 번째는 코드 품질 & 리뷰, CI/CD & 배포, 런북(Runbooks), 인프라 운영입니다. 이 네 가지는 특히 DevOps 관점에서 강력해요. PR 모니터링부터 점진적 배포, 롤백까지 자동화할 수 있거든요. 실제로 한 개발자가 6개월간 Claude Code를 혼자서 30만 줄 코드 리라이트 작업에 활용하면서, 이런 전문화된 Skills들을 만들어 운영했다고 해요. 이전에는 시도조차 못 했을 규모의 프로젝트를 혼자 해낸 거죠.

잘 만든 Skills의 비밀 3가지

Anthropic이 실제로 수백 개의 Skills를 운영하며 얻은 핵심 조언 세 가지를 정리해드릴게요.

첫 번째는 "당연한 것은 쓰지 말 것"입니다. Claude는 이미 코딩에 대해 많은 걸 알고 있어요. Skills에 쓸 내용은 Claude의 기본 사고방식에서 벗어나야 할 부분, 즉 회사 특유의 컨벤션이나 자주 빠지는 함정들이어야 해요. Anthropic 프론트엔드 디자인 Skills가 좋은 예인데요, "Inter 폰트와 보라색 그라데이션은 쓰지 마라"처럼 구체적인 지침으로 Claude의 기본 미감을 교정하는 방식이에요. Claude한테 UI 만들어달라고 하면 항상 비슷한 결과가 나왔다는 얘기를 들어보셨죠? 커뮤니티에서는 이걸 "AI 슬롭(AI Slop)"이라고 부른다고 해요. Skills는 그 문제를 정면에서 해결하는 방식이에요.

두 번째는 "Gotchas 섹션을 공들여 만들 것"입니다. Skills 중 가장 정보 밀도가 높은 부분이 Gotchas 섹션이에요. Claude가 실제로 자주 실수하는 지점들을 모아두고, 운영하면서 계속 추가해나가는 게 좋아요. 처음엔 몇 줄 짜리 메모였던 게 쌓이다 보면 굉장히 강력한 가이드가 돼요.

세 번째는 "파일시스템을 적극 활용할 것"입니다. 폴더 안에 참조 문서, 스크립트, 예시 파일을 넣어두면 Claude가 필요할 때마다 찾아서 씁니다. 예를 들어 최종 결과물이 마크다운 문서라면 assets/ 폴더에 템플릿 파일을 미리 넣어두는 거예요. 토큰도 아낄 수 있어요 — 참조 파일들은 필요할 때만 로드되니까요.

Description 필드가 왜 그렇게 중요한가

Skills를 잘 만들고도 제대로 트리거가 안 되는 경우가 꽤 있는데요, 대부분 description 필드 문제예요.

Claude Code는 세션을 시작할 때 모든 Skills의 description을 훑으며 "이 요청에 어떤 Skills을 써야 하나"를 판단합니다. 시작 시점에는 각 Skills의 이름과 설명 메타데이터만 미리 로드되거든요. 즉, description은 Skills에 대한 소개가 아니라 "언제 이 Skills을 발동해야 하는지"를 알려주는 트리거 문구예요.

"배포 자동화 도구입니다"보다는 "서비스를 스테이징 또는 프로덕션 환경에 배포할 때"처럼 쓰는 게 훨씬 효과적이에요. 마치 검색 키워드를 잘 잡아야 노출이 되듯, description도 Claude가 매칭하기 쉽게 상황 중심으로 써야 해요.

Skills에도 메모리를 심을 수 있다

Skills 디렉토리 안에 파일을 저장해두면 일종의 기억 기능을 구현할 수 있어요.

예를 들어 스탠드업 포스팅 Skills에 standups.log를 두면, 다음 실행 시 Claude가 지난 기록을 읽고 "어제와 달라진 것"만 골라서 포스팅합니다. 컬리(Kurly) 기술 블로그에서도 비슷한 사례를 공유했는데요, CLAUDE.md에 금지 사항을 넣으면 대화가 길어질수록 잊혀지는 문제를 Skills로 해결했다고 해요. Skills는 단순히 룰을 나열하는 게 아니라, 실제로 검사하고 검증하는 코드까지 포함할 수 있거든요.

단, Skills 업그레이드 시 파일이 삭제될 수 있으니 중요한 데이터는 안정적인 폴더에 따로 저장해두는 게 좋아요.

Skills를 팀 전체로 확장하는 법

Skills의 진짜 가치는 개인이 쓸 때보다 팀 전체가 공유할 때 나타납니다.

작은 팀이라면 리포지토리의 .claude/skills 폴더에 바로 체크인하면 돼요. 팀 레포에 넣어두면 팀원 모두가 같은 기준으로 리뷰하고, 같은 방식으로 배포하게 되거든요. "리뷰 기준이 사람마다 달라요"라는 문제가 자연스럽게 해소되는 거예요.

규모가 커지면 내부 Skills 마켓플레이스를 만드는 게 효율적이에요. Anthropic도 GitHub 샌드박스 폴더에 공유하고, 충분히 검증된 Skills만 마켓플레이스 PR로 올리는 방식을 사용하고 있어요.

중요한 건 품질 관리예요. 잘못 만든 Skills나 중복 Skills는 오히려 컨텍스트를 오염시킬 수 있어서, 어느 정도의 검수 프로세스가 있어야 해요. 그리고 신뢰할 수 없는 출처의 Skills는 코드 실행 권한을 가질 수 있으니, 외부 Skills를 쓸 때는 반드시 내용을 검토하는 습관이 필요합니다.

Skills를 반복 입력의 무덤으로 만들지 마세요

솔직히 말해서, 처음에 Claude Code를 쓸 때 많은 분들이 같은 내용을 반복 입력하고 있을 거예요. "이 코드 리뷰해줘, 한국어로, 보안 이슈 먼저 봐줘, 설명은 초보자 눈높이로." 한 세션 끝나면 또 처음부터. 다음 날도 또.

Anthropic 공식 문서에는 이런 말이 나와요. "같은 프롬프트를 반복해서 입력하고 있다면, 그건 스킬로 만들 때가 된 것"이라고요. 실제 데이터에 의하면 개발자들이 하루 평균 3~7회 같은 형태의 프롬프트를 재입력한다고 해요. Skills를 잘 만들어두면 이 시간이 고스란히 절약되는 거예요.

마무리

Claude Code의 Skills는 단순한 자동화 스크립트가 아닙니다.

팀의 암묵지를 Claude가 이해할 수 있는 형태로 문서화하는 작업이에요. 신입 개발자 온보딩 문서를 쓰듯, 우리 팀만의 방식과 함정을 Skills에 담으면 Claude는 매번 처음부터 배우지 않고 팀의 일원처럼 일하게 됩니다. 처음에는 몇 줄 짜리 메모였던 Skills가 Gotchas가 쌓이고, 스크립트가 추가되면서 점점 강력해져요. 지금 당장 한 개부터 만들어보세요.