에이전트 스킬 설치: Claude Code와 데스크톱 앱

에이전트 스킬 설치 위치는 제품마다 다르다

에이전트 스킬을 설치하는 위치는 Claude Code와 Claude 데스크톱 앱이 서로 다릅니다. Claude Code는 디스크에 있는 디렉터리를 직접 읽습니다. Claude 데스크톱 앱은 디렉터리를 읽지 않고, 앱 화면에서 ZIP 파일을 업로드받습니다.

이름이 같아서 하나의 기능처럼 보이지만 두 개의 다른 제품입니다. 그래서 한쪽의 설치 방법을 다른 쪽에 그대로 적용하면 스킬은 로드되지 않습니다. 에러 메시지도 거의 나오지 않습니다. 그냥 조용히 없는 것처럼 동작합니다. 이 글이 막으려는 실패가 정확히 그것입니다.

스킬이 무엇인지, 마크다운 파일 하나가 왜 모델의 행동을 바꾸는지는 에이전트 스킬의 구조와 점진적 공개 방식에서 따로 다룹니다. 여기서는 그다음 단계만 봅니다. 파일을 어디에 두는가, 그리고 로드되었는지 어떻게 확인하는가.

Claude Code에 에이전트 스킬 설치하기

Claude Code는 세 종류의 위치에서 스킬을 찾습니다. 공식 문서가 적어둔 경로는 다음과 같습니다.

• 개인 스킬: ~/.claude/skills/<skill-name>/, 이 머신의 모든 프로젝트에서 사용됩니다.
• 프로젝트 스킬: .claude/skills/<skill-name>/, 해당 저장소에서만 사용됩니다.
• 플러그인 스킬: <plugin>/skills/<skill-name>/, 플러그인이 켜진 곳에서 사용됩니다.

파일 이름은 SKILL.md입니다. 대문자입니다. 리눅스와 WSL의 파일 시스템은 대소문자를 구분하기 때문에 Skill.md는 SKILL.md와 다른 파일이고, 그 디렉터리는 스킬로 인식되지 않습니다. macOS의 기본 파일 시스템은 대소문자를 구분하지 않아서 맥에서는 그냥 동작할 수도 있습니다. 맥에서 만든 스킬을 리눅스 서버로 옮겼을 때만 깨지는 경우가 여기서 나옵니다.

깃허브에서 받은 스킬 하나를 개인 스킬로 넣는 절차입니다.

git clone https://github.com/owner/repo.git /tmp/skill-src
mkdir -p ~/.claude/skills
cp -r /tmp/skill-src/my-skill ~/.claude/skills/
ls ~/.claude/skills/my-skill/

마지막 ls가 SKILL.md를 출력해야 합니다. 대신 또 다른 디렉터리 이름만 나온다면 한 단계 깊게 복사한 것입니다. 아래의 중첩 깊이 항목에서 고치는 방법을 설명합니다.

프로젝트 스킬은 저장소 안에 두고 커밋합니다. 팀원이 clone하면 스킬도 같이 따라옵니다.

mkdir -p .claude/skills/my-skill
$EDITOR .claude/skills/my-skill/SKILL.md
git add .claude/skills/my-skill

여러 저장소에서 같은 스킬을 쓰려고 파일을 복사해서 뿌리면 곧 버전이 갈라집니다. 그 문제를 다루는 방법은 여러 저장소에 스킬을 공유하는 방식에 따로 정리했습니다.

프런트매터는 파일의 첫 줄부터 시작해야 한다

SKILL.md의 맨 위에는 YAML 프런트매터가 옵니다. 공식 문서는 여는 ---가 파일의 첫 줄일 때만 Claude Code가 프런트매터를 읽는다고 명시합니다. 첫 줄이 빈 줄이면 파일 전체가, --- 기호까지 포함해서, 그냥 스킬 본문으로 취급됩니다. 이 경우 스킬은 로드되기는 하지만 아무 필드도 설정되지 않은 상태가 됩니다. 목록에는 보이는데 모델이 쓰지 않는 상태가 이렇게 만들어집니다.

---
description: 커밋되지 않은 변경을 요약하고 위험한 부분을 표시한다
---

## 지시

위 변경을 두세 줄로 요약하고 위험 요소를 나열한다.

description은 권장 필드입니다. 모델이 이 스킬을 언제 써야 하는지 판단하는 근거가 여기뿐이기 때문에, 비워두면 자동 호출이 사실상 일어나지 않습니다. name은 선택입니다. 스킬 목록에 표시되는 이름만 바꿀 뿐이고, 슬래시 명령 이름은 디렉터리 이름에서 나옵니다. 즉 ~/.claude/skills/my-skill/에 넣으면 명령은 /my-skill입니다.

설명문을 어떻게 써야 모델이 스킬을 제때 집어드는지는 스킬을 직접 작성하는 방법에서 더 깊게 다룹니다.

플러그인 마켓플레이스에서 온 스킬은 어떻게 설치하나

손으로 파일을 옮기지 않는 경로가 하나 더 있습니다. 플러그인입니다. 마켓플레이스를 먼저 등록하고, 그다음 플러그인을 설치합니다. 둘 다 세션 안에서 실행하는 슬래시 명령입니다.

/plugin marketplace add owner/repo
/plugin install plugin-name@marketplace-name

첫 번째 명령은 여러 형태의 인자를 받습니다. 깃허브 축약형 owner/repo, 전체 git URL https://gitlab.com/team/plugins.git, 로컬 경로 ./my-marketplace, 그리고 태그를 붙인 owner/repo@v2.0.0 형태입니다.

설치된 플러그인은 ~/.claude/plugins/cache 아래 캐시에 저장됩니다. 직접 편집할 디렉터리가 아닙니다. 플러그인을 업데이트하면 그 내용이 덮어써지기 때문입니다.

중요한 차이가 하나 있습니다. 플러그인으로 들어온 스킬은 이름 앞에 플러그인 이름이 붙습니다. quality-review-plugin 플러그인의 quality-review 스킬은 /quality-review가 아니라 /quality-review-plugin:quality-review로 호출합니다. 콜론 앞부분을 빼먹고 "설치했는데 명령이 없다"고 결론 내리는 경우가 많습니다. 플러그인이 스킬과 명령과 훅을 어떻게 한 덩어리로 묶는지는 플러그인의 구조에서 볼 수 있습니다.

claude.ai 계정에서 동기화되어 내려오는 스킬

설치한 적 없는 스킬이 목록에 보일 수 있습니다. 버그가 아닙니다. claude.ai 계정으로 로그인한 터미널 세션에서 Claude Code는 계정에 켜져 있는 스킬을 내려받습니다. 문서에 적힌 동작은 이렇습니다. 세션이 시작되면 백그라운드로 ~/.claude/skills/synced/에 내려받고, 세션이 도는 동안 약 10분마다 claude.ai를 확인합니다. 스킬이 추가되거나 수정되거나 꺼지면 세션 재시작 없이 반영됩니다.

이 동기화는 Claude Code v2.1.273 이상에서 동작합니다. 버전이 낮으면 계정 쪽에서 아무리 켜도 터미널에는 내려오지 않습니다. claude --version으로 먼저 확인하세요.

동기화는 한 방향입니다. claude.ai에서 터미널로만 갑니다. 그래서 ~/.claude/skills/synced/ 안의 파일을 손으로 고치는 것은 의미가 없습니다. 다음 확인 주기에 원래대로 돌아오기 때문입니다. 고칠 내용이 있으면 계정 쪽에서 고쳐야 합니다.

Claude 데스크톱 앱은 폴더가 아니라 ZIP을 받는다

여기서 방향이 완전히 바뀝니다. 데스크톱 앱에는 여러분이 파일을 떨어뜨릴 스킬 폴더가 문서화되어 있지 않습니다. 공식 도움말이 안내하는 설치 경로는 앱 안의 업로드 화면 하나입니다.

1. Settings > Capabilities로 가서 "Code execution and file creation"을 켭니다. 스킬 기능 자체가 코드 실행을 필요로 하기 때문에, 이것이 꺼져 있으면 스킬을 쓸 수 없습니다.
2. Customize > Skills로 이동합니다.
3. + 버튼을 누르고 + Create skill을 고릅니다.
4. Upload a skill을 선택하고 ZIP 파일을 올립니다.
5. 목록에 나타난 스킬의 토글을 켭니다.

스킬 기능은 Free, Pro, Max, Team, Enterprise 요금제에서 쓸 수 있습니다. Team이나 Enterprise 계정이라면 조직 소유자가 Organization settings > Plugins & skills의 Policy 탭에서 먼저 허용해야 개인 화면에 나타납니다.

ZIP의 내부 구조에는 규칙이 있습니다. 스킬 폴더가 ZIP의 최상위여야 하고, 파일들이 ZIP 루트에 바로 흩어져 있으면 안 됩니다. 도움말이 보여주는 올바른 구조입니다.

my-skill.zip
└── my-skill/
    ├── skill.md
    └── resources/

폴더 이름은 스킬 이름과 같아야 합니다. 그리고 파일 이름을 잘 보세요. 데스크톱 앱과 claude.ai 쪽 도움말은 skill.md를 소문자로 적고, Claude Code 문서는 SKILL.md를 대문자로 적습니다. 두 문서가 각자의 제품에 대해 다른 표기를 쓰고 있으므로, 한쪽 표기를 다른 쪽에 옮겨 적지 말고 각 제품 문서의 표기를 그대로 따르세요.

맥에서 폴더를 우클릭해 압축하면 __MACOSX 디렉터리가 함께 들어갑니다. 터미널에서 만들면 그 문제가 없습니다.

cd ~/work
zip -r my-skill.zip my-skill -x '*.DS_Store'
unzip -l my-skill.zip

unzip -l의 목록이 전부 my-skill/로 시작해야 합니다. skill.md가 맨 앞에 바로 보이면 폴더 안에서 압축한 것이고, 그 ZIP은 도움말이 "잘못된 구조"로 표시한 형태입니다.

앱 쪽 프런트매터에는 길이 제한이 있습니다. name은 최대 64자, description은 최대 200자입니다.

데스크톱 앱의 스킬 폴더 위치를 단언하는 글이 인터넷에 많습니다. 그 경로를 믿고 파일을 복사하기 전에 앱의 Customize > Skills 화면을 먼저 여세요. 앱이 실제로 인정하는 설치 방법은 그 화면에 있는 것뿐이고, 화면에 없는 경로는 다음 업데이트에 사라져도 아무도 알려주지 않습니다.

WSL의 ~/.claude와 윈도우 사용자 폴더는 다른 곳이다

한국에서 가장 흔한 조합입니다. Claude Code는 WSL 안의 Ubuntu에서 돌리고, Claude 데스크톱 앱은 윈도우 쪽에 설치되어 있습니다. 이 구성에서 ~는 두 개입니다.

• WSL 안에서 ~/.claude는 /home/<사용자>/.claude입니다.
• 윈도우에서 ~는 C:\Users\<사용자>이고, 네이티브 설치된 실행 파일은 %USERPROFILE%\.local\bin\claude.exe에 놓입니다.

이 둘은 서로 다른 파일 시스템입니다. 윈도우 탐색기에서 C:\Users\<사용자>\.claude\skills\를 만들어 스킬을 넣어도, WSL 안에서 실행 중인 Claude Code는 그 디렉터리를 절대 보지 않습니다. WSL 안에서 실행되는 프로세스의 홈 디렉터리가 리눅스 쪽이기 때문입니다. 반대도 마찬가지입니다.

탐색기에서 WSL 쪽 홈을 열고 싶다면 주소창에 \\wsl.localhost\Ubuntu\home\<사용자>를 입력하면 됩니다. 다만 편집은 WSL 안에서 하는 편이 낫습니다. 윈도우에서 그 경로를 다루면 네트워크 파일 시스템을 거치기 때문에 느리고 파일 감시가 깨집니다.

추측하지 말고 확인하세요. WSL 터미널에서 한 줄이면 끝납니다.

echo "$HOME" && ls -la "$HOME/.claude/skills/"

출력된 $HOME이 /home/...이면 스킬을 넣어야 할 곳은 그 아래입니다. /mnt/c/Users/...가 나온다면 윈도우 홈을 홈으로 쓰는 비표준 설정이므로, 그 경로를 기준으로 다시 잡아야 합니다.

데스크톱 앱 쪽 주의점도 하나 있습니다. 데스크톱 앱의 Code 탭에서 WSL 배포판 안으로 세션을 여는 기능이 있는데, 공식 문서는 WSL 세션에서 아직 쓸 수 없는 기능 목록에 커넥터와 플러그인을 넣어두었습니다. 그래서 그 세션에서는 플러그인 마켓플레이스를 기대하면 안 됩니다. WSL 배포판 안에서 CLI로 직접 실행하는 Claude Code는 평범한 리눅스 설치이므로 이 제약을 받지 않습니다. 또 하나, 폴더 신뢰는 배포판별로 따로 관리됩니다. 한 배포판에서 신뢰한 폴더는 다른 배포판에서도, 윈도우의 같은 경로에서도 신뢰되지 않습니다.

리눅스에서 GUI 앱과 CLI를 같이 쓸 때의 차이는 리눅스 데스크톱과 CLI를 함께 쓰는 방법에 정리되어 있습니다.

설치했는데 아무 일도 일어나지 않는다

세 가지를 순서대로 확인하세요.

이름이 이미 있는 스킬과 겹쳤다

Claude Code는 같은 이름이 여러 곳에 있을 때 정해진 규칙으로 하나를 고릅니다. 밀려난 쪽은 조용히 사라지기 때문에 설치가 실패한 것처럼 보입니다.

디렉터리를 한 단계 깊게 넣었다

가장 흔한 실수입니다. 스킬 모음 저장소를 통째로 클론한 다음 그 구조를 그대로 복사하면 이렇게 됩니다.

~/.claude/skills/
└── awesome-skills/
    └── my-skill/
        └── SKILL.md

Claude Code가 찾는 구조는 딱 한 단계입니다. <skills 디렉터리>/<skill-name>/SKILL.md입니다. 위 배치에서 Claude Code가 보는 스킬 이름은 awesome-skills이고, 그 디렉터리에는 SKILL.md가 없으므로 스킬이 아닙니다. 안쪽의 my-skill은 한 칸 더 들어가 있어서 탐색 대상이 아닙니다. 고치는 방법은 한 줄입니다.

mv ~/.claude/skills/awesome-skills/my-skill ~/.claude/skills/my-skill
rmdir ~/.claude/skills/awesome-skills

제대로 놓인 개인 스킬만 한 번에 보고 싶으면 깊이를 2로 제한해서 찾으면 됩니다.

find ~/.claude/skills -maxdepth 2 -name 'SKILL.md'

여기에 나오지 않는 스킬은 Claude Code도 찾지 못합니다.

프로젝트 스킬에는 반대 방향의 함정이 있습니다. Claude Code는 세션을 시작한 디렉터리와 그 위의 모든 상위 디렉터리를 저장소 루트까지 올라가며 .claude/skills/를 찾습니다. 그래서 packages/frontend/에서 시작해도 루트의 스킬은 잡힙니다. 그런데 시작 위치보다 아래에 있는 스킬은 시작할 때 로드되지 않습니다. Claude가 그 하위 디렉터리의 파일을 처음 읽거나 편집하는 순간에 로드됩니다. 그 전에는 / 메뉴에도 나오지 않고 이름으로 호출할 수도 없습니다. 먼저 로드하고 싶으면 /add-dir에 그 하위 경로를 넘기세요. 이 명령은 v2.1.257 이상이 필요합니다.

모델이 실제로 그 스킬을 보고 있는지 확인한다

추측하지 말고 목록을 여세요. 세션 안에서 실행합니다.

/skills

이 메뉴가 사용 가능한 스킬을 출처별로 보여줍니다. 동기화된 스킬은 claude.ai sync 아래에 모입니다. 방금 넣은 스킬이 이 목록에 없다면 문제는 파일 위치입니다. 목록에는 있는데 모델이 쓰지 않는다면 문제는 description입니다. 두 증상은 원인이 다르므로 고치는 곳도 다릅니다.

각 스킬이 컨텍스트에서 차지하는 비용과 실제 사용 빈도까지 보려면 /skill-doctor를 실행하세요. 스킬을 잔뜩 설치한 뒤 응답이 느려졌다고 느낄 때 보는 화면입니다.

데스크톱 앱에서는 Customize > Skills 목록이 같은 역할을 합니다. 업로드한 스킬이 목록에 있고 토글이 켜져 있는지 확인하세요. 목록에 아예 없으면 ZIP 구조를 다시 보세요.

설치 전에 SKILL.md를 한 번은 읽으세요

스킬은 모델에게 주는 지시문입니다. 그런데 allowed-tools 같은 프런트매터 필드로 도구 권한을 미리 승인할 수 있고, 본문에 실행할 명령을 넣을 수도 있습니다. 그래서 출처를 모르는 스킬을 넣는 것은 출처를 모르는 셸 스크립트를 실행하는 것과 성격이 비슷합니다.

cat ~/.claude/skills/my-skill/SKILL.md

읽는 데 1분 걸립니다. 그 스킬이 어떤 권한을 요구하고 무엇을 실행하는지는 그 1분 안에 다 드러납니다. 특히 프런트매터의 allowed-tools와 본문의 명령 실행 부분을 보세요.

FAQ

Claude Code에 넣은 스킬이 Claude 데스크톱 앱에도 나타나나요?

아닙니다. 흐름은 반대 방향으로만 갑니다. claude.ai 계정에 켜둔 스킬은 같은 계정으로 로그인한 Claude Code 터미널 세션에 ~/.claude/skills/synced/로 내려옵니다. 이 동기화는 한 방향이고 Claude Code v2.1.273 이상이 필요합니다. ~/.claude/skills/에 손으로 넣은 스킬은 계정으로 올라가지 않으므로, 앱에서도 쓰려면 ZIP으로 묶어 Customize > Skills에서 따로 업로드해야 합니다.

WSL에서 Claude Code를 쓰는데 스킬을 어디에 넣어야 하나요?

WSL 배포판 안의 /home/<사용자>/.claude/skills/입니다. 윈도우의 C:\Users\<사용자>\.claude\가 아닙니다. WSL 안에서 실행되는 프로세스의 홈 디렉터리는 리눅스 쪽이라서 윈도우 사용자 폴더는 전혀 읽지 않습니다. 확실히 하려면 WSL 터미널에서 echo "$HOME"을 실행하고, 출력된 경로 아래에 .claude/skills/를 만드세요.

SKILL.md인가요, skill.md인가요?

제품별로 문서 표기가 다릅니다. Claude Code 문서는 SKILL.md로, 데스크톱 앱과 claude.ai 도움말은 ZIP 안의 skill.md로 적습니다. 각 제품 문서의 표기를 그대로 쓰세요. 리눅스와 WSL의 파일 시스템은 대소문자를 구분하기 때문에, 이름을 다르게 적으면 같은 파일로 인식되지 않습니다.

플러그인으로 설치한 스킬이 왜 슬래시 명령에 안 보이나요?

이름 앞에 플러그인 이름이 붙기 때문입니다. quality-review-plugin 플러그인의 quality-review 스킬은 /quality-review-plugin:quality-review로 호출합니다. 플러그인 스킬은 이렇게 이름 공간이 나뉘어 있어서, 같은 이름의 개인 스킬이 있어도 둘 다 로드됩니다. /skills 메뉴에서 플러그인 항목을 열면 정확한 전체 이름을 볼 수 있습니다.

프로젝트에 커밋한 스킬이 왜 개인 스킬에 밀리나요?

우선순위가 그렇게 정해져 있습니다. 엔터프라이즈가 개인보다, 개인이 프로젝트보다 우선합니다. ~/.claude/skills/deploy와 프로젝트의 .claude/skills/deploy가 둘 다 있으면 /deploy는 개인 쪽을 실행합니다. 프로젝트 버전을 테스트하려면 개인 쪽 디렉터리를 잠시 다른 이름으로 옮기고 /skills로 다시 확인하세요.