클로드(Claude) 웹앱에서 공들여 만든 스킬(Skill)을, 정작 실제 작업은 대부분 Claude Code에서 한다면 어떻게 옮겨야 할까. 결론부터 말하면 방법은 두 가지다. 환경변수 하나로 자동 동기화하거나, zip 파일을 직접 내려받아 로컬 디렉토리에 넣는 것이다. 둘 다 어렵지 않지만, 언제 어떤 방식을 써야 하는지 헷갈리는 사람이 많다. 이 글에서는 두 방법을 실제 순서대로 정리한다.
왜 웹앱 스킬과 Claude Code 스킬은 다르게 취급될까
먼저 헷갈리는 이유부터 짚고 가야 한다. claude.ai(웹앱)와 Claude Code는 이름은 같은 “스킬”을 쓰지만 저장 방식이 완전히 다르다.
웹앱은 스킬을 zip 파일 업로드 방식으로 관리한다. Settings의 Capabilities(또는 Customize > Skills) 메뉴에서 zip을 올리면 그 계정에 스킬이 등록되고, 이후 대화에서 자동으로 감지되어 사용된다.
반면 Claude Code는 파일시스템 기반이다. SKILL.md라는 마크다운 파일 하나(와 필요하면 리소스 파일들)를 특정 디렉토리에 넣어두기만 하면 된다. 업로드 UI 자체가 없다. 이 차이 때문에 “웹앱에 스킬이 있는데 왜 Claude Code에서는 안 보이지?”라는 질문이 자주 나온다.
다행히 둘 다 기반 포맷은 동일하다. YAML frontmatter(name, description)로 시작하는 SKILL.md 구조를 공유하기 때문에, 형식을 변환할 필요 없이 파일 위치만 옮기면 된다.
방법 1 — 자동 동기화: 파일을 직접 옮기지 않는 방식
가장 손이 덜 가는 방법은 Claude Code에 동기화 기능을 켜는 것이다. 환경변수 CLAUDE_CODE_SYNC_SKILLS를 1로 설정하고, -p 플래그를 붙여 non-interactive 모드로 실행하면 계정에 등록된 스킬을 자동으로 내려받는다.
export CLAUDE_CODE_SYNC_SKILLS=1
claude -p "hello"
이렇게 실행하면 동기화된 스킬은 ~/.claude/skills/synced/ 경로에 저장된다. 몇 가지 알아둘 점이 있다.
- interactive 세션에서는 동작하지 않는다. 터미널에서 그냥
claude만 입력해서 들어가는 일반 대화형 세션에서는 적용되지 않고, 반드시-p옵션을 붙인 non-interactive 실행이어야 한다. - 이름이 겹치면 로컬 스킬이 우선한다. 같은 이름의 스킬을 로컬에서 직접 작성해뒀다면, 동기화된 버전 대신 로컬 버전이 적용된다.
- Cowork나 클라우드 세션에서는 별도 설정 없이도 계정에 등록된 스킬이 그대로 로드된다. 이 방식이 필요한 쪽은 어디까지나 “내 컴퓨터에서 로컬로 돌리는 세션”이다.
tmux 등으로 세션을 상시 유지하며 interactive하게 작업하는 흐름이라면, 이 자동 동기화보다는 아래 수동 방식이 실질적으로 더 맞을 수 있다.
방법 2 — 수동 이전: zip을 직접 내려받아 배치하기
자동 동기화가 번거롭거나, 세션 구조상 non-interactive 실행이 어려운 경우에는 수동으로 옮기는 편이 확실하다. 순서는 다음과 같다.
1) claude.ai에서 스킬 zip 다운로드
웹앱 좌측 하단 Settings > Capabilities(또는 Customize > Skills)로 이동해, 옮기려는 스킬 옆 다운로드 버튼을 누른다. 파일이 .skill 확장자로 내려오는 경우가 있는데, 이때는 확장자만 .zip으로 바꿔주면 정상적으로 압축 해제된다.
2) 압축 해제 후 SKILL.md 확인
zip을 풀면 SKILL.md와 관련 리소스 파일이 든 폴더 하나가 나온다. 이 폴더명은 소문자-하이픈 형식(예: my-skill)이어야 하고, SKILL.md 내부의 name 필드와 정확히 일치해야 Claude Code가 제대로 인식한다. 폴더명과 name 필드가 어긋나면 스킬이 로드되지 않거나 엉뚱하게 동작할 수 있으니 이 단계에서 반드시 확인한다.
3) 리눅스 서버로 전송
로컬 PC가 아니라 원격 리눅스 서버(예: 클라우드 VM)에서 Claude Code를 돌리고 있다면, scp나 rsync로 폴더째 옮기면 된다.
scp -r ./my-skill user@서버주소:~/my-skill
VS Code의 Remote-SSH를 쓰고 있다면 명령어 없이 탐색기에서 드래그 앤 드롭으로도 충분하다.
4) 스킬 디렉토리에 배치
이제 목적지를 정할 차례다.
- 모든 프로젝트에서 공통으로 쓸 스킬 → 개인 디렉토리인
~/.claude/skills/에 넣는다. - 특정 프로젝트에서만 쓸 스킬 → 해당 프로젝트 루트의
.claude/skills/에 넣는다.
두 위치는 이름이 겹칠 경우 프로젝트 로컬 스킬이 우선 적용되는 구조이므로, 여러 스킬을 조합해서 쓰더라도 충돌만 조심하면 문제없다.
5) 동작 확인
마지막으로 Claude Code를 실행해 관련 컨텍스트를 주거나 /스킬명으로 직접 호출해서 정상적으로 인식되는지 테스트한다. 여기까지 하면 배치는 끝난 것이다.
자동 동기화 vs 수동 이전, 뭘 골라야 할까
두 방법은 상황에 따라 장단이 갈린다.
| 상황 | 추천 방식 |
|---|---|
| 스킬을 자주 수정하며 웹앱-Claude Code를 계속 오간다 | 자동 동기화 |
non-interactive(-p) 실행 흐름을 이미 쓰고 있다 |
자동 동기화 |
| interactive 세션(tmux 등)에서 상시 작업한다 | 수동 이전 |
| 스킬 파일 자체를 버전 관리(git)하고 싶다 | 수동 이전 |
특히 스킬을 팀 단위로 공유하거나 git으로 버전을 추적하고 싶다면, 애초에 동기화에 의존하지 말고 수동으로 받아 로컬 저장소에 커밋해두는 편이 관리하기 쉽다.
자주 묻는 질문
Q. zip을 풀었는데 SKILL.md가 하위 폴더 안에 또 있어요.
압축 파일 구조가 잘못된 경우다. SKILL.md는 최상위 스킬 폴더 바로 아래에 있어야 하며, 폴더 안에 또 폴더가 있는 구조라면 한 단계 위로 올려서 정리해야 한다.
Q. 동기화된 스킬과 로컬 스킬을 동시에 쓸 수 있나요?
가능하다. 이름이 다르면 둘 다 로드되고, 이름이 같으면 로컬 스킬이 우선 적용된다.
Q. 스킬을 수정하고 싶으면 어디서 편집해야 하나요?
웹앱에서 만든 스킬은 원본을 웹앱에서 수정한 뒤 다시 다운로드하거나, 아예 로컬로 옮긴 뒤부터는 SKILL.md를 직접 텍스트 에디터로 편집하면 된다. 이후 다시 동기화하고 싶다면 웹앱에도 같은 내용을 반영해줘야 두 환경이 어긋나지 않는다.
마무리
웹앱 스킬과 Claude Code 스킬은 이름만 같을 뿐 저장 구조가 다르다는 점만 이해하면, 옮기는 작업 자체는 단순하다. 빠르게 한 번 옮기고 끝낼 거라면 zip 다운로드 후 ~/.claude/skills/에 넣는 수동 방식이 직관적이고, 웹앱과 로컬을 계속 오가며 반복적으로 동기화해야 한다면 CLAUDE_CODE_SYNC_SKILLS 환경변수를 활용하는 쪽이 손이 덜 간다. 두 방식을 상황에 맞게 섞어 쓰는 것도 물론 가능하다.