Claude Code의 스킬을 쓰다 보니 질문이 생겼다. 필요할 때마다 만들 것인가, 범용적인 하나를 잘 깎아 쓸 것인가. 답을 찾기 위해 내 경험을 정리해본다.

스킬이 필요했던 순간

나는 셀프호스팅 블로그를 운영하고 있다. 글을 쓰고 나면 블로그 플랫폼의 Admin API를 통해 발행하는데, 이 과정에는 사소하지만 까다로운 것들이 많다.

  • JWT 인증 토큰 생성
  • 내부 네트워크로 접속하되 Host 헤더는 공개 도메인으로 설정 (301 방지)
  • 이미지 업로드는 Python urllib이 아닌 curl로 해야 동작
  • 플랫폼 고유의 에디터 포맷으로 HTML을 감싸야 함
  • 이미지 중복 업로드 방지를 위한 MD5 캐싱

처음에는 이 내용을 문서에 정리해두고, 필요할 때마다 Claude에게 "이 문서 읽고 발행해줘"라고 시켰다. 되긴 된다. 하지만 매번 문서를 읽히는 것 자체가 토큰 낭비이고, 문서를 어디에 둘지도 애매했다. 프로젝트 A에서도 쓰고, 프로젝트 B에서도 쓰고 싶은데, CLAUDE.md에 넣자니 프로젝트마다 복붙해야 한다.

그래서 스킬로 만들었다. /blog-publish 한 줄이면 어떤 프로젝트에서든 동작한다. 토큰도 스킬이 호출될 때만 소비된다.

어떤 작업이 스킬 감인가

블로그 발행 스킬을 만들고, 다른 프로젝트에서도 위키 글쓰기나 테스트 자동화 스킬을 만들어 쓰면서 패턴이 보이기 시작했다.

외부 시스템 연동

블로그 API, Confluence API, Jira, Slack — 이런 외부 시스템과의 연동에는 인증 방식, 엔드포인트, 요청 포맷 같은 환경 특화 지식이 필요하다. AI가 매번 추론해서 알아낼 수 있는 게 아니다. 한번 정리해두면 그 다음부터는 확실하게 동작한다.

삽질의 결과물

"이미지 업로드는 curl로 해야 한다" — 이건 삽질을 통해 알아낸 사실이다. urllib로 하면 빈 응답이 온다. 이런 종류의 지식은 문서에도 잘 안 나와 있고, AI가 추론으로 도달하기 어렵다. 한 번 겪은 삽질을 다시 겪지 않기 위한 장치로서 스킬은 아주 효과적이다.

프로젝트 독립성

특정 프로젝트에서만 쓸 작업이라면 CLAUDE.md에 넣으면 된다. 스킬은 어떤 프로젝트에서든 불러 쓸 수 있어야 할 때 빛난다.

스킬 파일을 놓는 위치에 따라 범위가 달라진다.

  • ~/.claude/skills/ — 내 모든 프로젝트에서 사용 가능. 어디서 Claude Code를 열든 쓸 수 있음
  • .claude/skills/ (프로젝트 루트) — 해당 프로젝트에서만 사용. git에 포함시켜 팀과 공유 가능

나는 전부 홈 디렉토리에 둔다. 블로그 발행이든, 다른 도구든, 어차피 내가 Claude Code를 어디서 열든 필요한 것들이기 때문이다.

구체적으로 어떤 것들이?

작업 왜 스킬인가
블로그 발행 API 인증 + 포맷 변환 + 이미지 처리. 삽질 결과물이 많음
위키/문서 작성 Confluence/Notion API 연동. 환경마다 템플릿과 규칙이 다름
테스트 환경 세팅 환경 변수, 시드 데이터, 의존성 순서 등 환경마다 다른 암묵지
인프라 상태 점검 서버 접속 정보 + 확인 절차가 고정적. 반복 빈도 높음
릴리즈 노트 생성 git log 파싱 + 포맷팅 규칙이 정해져 있음. 매 릴리즈마다 반복

반대로, 이런 건 스킬로 만들 필요가 없다.

  • 한 번만 할 작업 — "이 CSV를 파싱해서 정리해줘" 같은 일회성 요청
  • 프로젝트에 종속된 규칙 — 특정 레포의 코딩 컨벤션은 CLAUDE.md에 넣으면 충분
  • AI가 이미 잘하는 것 — 코드 리팩토링, 버그 수정 같은 범용 작업은 추가 지시 없이도 잘 됨

반복이 보이면 스킬로 만든다

처음부터 스킬을 설계하려고 하지 않았다. 그냥 필요한 작업을 시키다가, 같은 걸 또 시키고 있다는 걸 알아챈 순간 스킬로 올렸다.

블로그 발행이 그랬다. 처음에는 "이 글 발행해줘"라고 시켰다. 두 번째도 시켰다. 세 번째 시키려는 순간, 매번 같은 인증 방식과 포맷 변환을 설명하고 있다는 걸 깨달았다. 그때 스킬로 만들었다.

그리고 쓸수록 스킬이 자란다. 처음에는 글 올리기만 됐는데, 이미지 캐싱이 추가되고, draft/publish 옵션이 생기고, frontmatter 파싱이 붙었다. 반복 사용이 범용성을 만들어준 것이지, 처음부터 범용으로 설계한 게 아니다.

필요 → 반복 발견 → 스킬로 추출 → 사용하며 확장
이 사이클을 반복하다 보면, 점점 나만의 도구 세트가 갖춰진다. 각 스킬에는 삽질의 기록이 담겨 있고, 쓸수록 범용성이 커진다.

한 작업 안에서만 반복되는 패턴도 마찬가지다. 마이그레이션 중 같은 변환을 여러 번 해야 한다면, 그것도 스킬로 만들 가치가 있다. 작업이 끝나면 버려도 되지만, 작업 중에는 매번 설명하는 것보다 훨씬 효율적이다.

결국 스킬을 잘 쓰는 방법은 간단하다. 반복을 알아채는 것. 그러면 범용성은 따라온다.

지금 바로 해볼 수 있는 것

그래서, 나는 어떤 작업을 반복하고 있을까? 직접 떠올리려 하면 의외로 잘 안 떠오른다. 이럴 때 Claude에게 물어보면 된다.

프롬프트

내가 지금까지 Claude Code에서 작업한 대화 기록들을 분석해줘. 1. 내가 반복적으로 시킨 작업 패턴을 찾아서 리스트업 2. 빈도순으로 정렬 3. 각각이 스킬로 만들 가치가 있는지 판단 4. 가장 가치 있는 것부터 스킬화를 제안

이걸 실행하면 자신의 사용 패턴을 객관적으로 볼 수 있다. 의외의 반복이 발견될 수도 있다.