Claude Code가 skills를 찾는 위치
Claude Code는 여러 위치에서 skills를 로드합니다. 문서의 표에는 다음과 같이 나열되어 있습니다.
- Personal:
~/.claude/skills/<skill-name>/SKILL.md, 이 머신의 모든 프로젝트용. - Project: 저장소 내의
.claude/skills/<skill-name>/SKILL.md. - Nested: 하위 디렉터리 내부의
.claude/skills폴더. - Enterprise: 조직에서 관리형 설정을 통해 배포한 skills.
- Plugin: 활성화된 플러그인 내부의 skills (플러그인 접두사로 명명됨).
- claude.ai account: 사용자의 claude.ai 계정에서 활성화된 skills.
마지막 항목이 이 가이드의 핵심입니다. Claude 웹 앱이나 데스크톱 채팅에서 만든 skill은 사용자가 직접 만든 폴더에 저장되지 않습니다. 계정에 저장되며, Claude Code는 가능한 세션에서 복사본을 다운로드합니다.
로드된 항목을 확인하려면 /skills를 실행하세요. 문서에 따르면 동기화된 skills는 claude.ai sync라는 그룹 아래에 나열됩니다.
claude.ai에서 skills가 동기화되는 시점
문서에 따르면 Cowork 또는 cloud 세션을 사용하거나 "터미널에서 claude.ai 계정으로 Claude Code에 로그인"하는 경우 동기화가 적용됩니다.
터미널 세션에서의 작동 방식은 다음과 같습니다. "세션이 시작되면 Claude Code는 백그라운드에서 계정의 skills를 ~/.claude/skills/synced/로 다운로드한 다음, 세션이 실행되는 동안 claude.ai의 변경 사항을 확인합니다."
확인은 지속적으로 실행되지 않습니다. 사용자나 Claude가 작업 중일 때는 약 10분마다 확인이 실행됩니다. 세션이 유휴 상태일 때는 약 40분마다 실행됩니다. 긴 유휴 시간 후 다시 입력을 시작하면 Claude Code는 몇 분 이내에 확인을 수행합니다.
두 가지 세부 사항이 skill이 늦게 나타나는 이유를 설명합니다.
동기화가 시작을 지연시키지 않습니다. 문서에서는 다음과 같이 설명합니다. "Claude는 skill을 호출할 때만 해당 skill의 다운로드를 기다리기 때문에 동기화로 인해 시작이 지연되는 일은 없습니다." claude.ai에 방금 추가한 skill은 도착하는 데 한 번의 확인 주기가 걸릴 수 있습니다.
짧은 비대화형 실행은 새로운 skills를 놓칠 수 있습니다. 빠른 실행은 새로 추가된 skill이 다운로드되기 전에 종료될 수 있으며, 이후 세션에서 이를 가져오게 됩니다. 문서에는 비대화형 실행이 skill 목록을 기다리도록 만드는 설정이 설명되어 있습니다.
어떤 skills가 동기화될지는 claude.ai 설정에 따라 다릅니다. pdf 및 xlsx와 같은 Anthropic의 자체 skills 중 일부는 항상 동기화됩니다. 나머지는 claude.ai의 skills 설정에서 해당 skill이 켜져 있어야 합니다.
동기화되지 않는 세션
터미널에서 claude.ai skill이 보이지 않을 때 가장 먼저 확인해야 할 사항입니다. 문서에는 Claude Code가 동기화되지 않는 세션이 나열되어 있습니다.
/login로그인이 없는 세션: API key로 인증하거나, 인증 토큰 변수 또는 API key 헬퍼 스크립트가 자격 증명을 제공하는 경우.- 기능 플래그(feature flags)를 가져오지 않는 세션: Amazon Bedrock에서의 세션이나 필수적이지 않은 트래픽이 차단된 세션.
- Bare 모드 및 Safe 모드.
- 관리형 설정으로 인해 skills가 플러그인 소스로 고정된 세션, 또는 설정 소스 목록에서 사용자 설정이 제외된 경우.
세션 도중에 로그인하는 경우에도 해당되는 사항이 있습니다. "세션 중에 /login으로 로그인한 경우, 동기화를 시작하려면 Claude Code를 재시작하세요."
이전에 동기화된 skills는 세션이 동기화되지 않는다고 해서 사라지지 않습니다. 문서에 따르면 "이전 세션에서 동기화된 skills는 디스크에 유지됩니다." Claude Code는 claude.ai 연결이 없더라도 동일한 계정으로 로그인된 이후 세션에서 이를 로드합니다.
claude.ai 측면에서도 skills는 계정 설정에 따라 달라집니다. Anthropic 고객 센터에 따르면 skills를 사용하려면 코드 실행(code execution)이 활성화되어 있어야 하며, Enterprise 플랜의 경우 소유자가 조직에 대해 skills를 활성화해야 합니다.
왜 로컬 skill이 같은 이름일 때 우선하는가
모든 동기화된 skill은 두 개의 이름을 가집니다. 문서의 설명은 다음과 같습니다. "동기화된 skill은 짧은 이름인 /<name> 또는 전체 이름인 /anthropic-skills:<name>으로 호출할 수 있습니다."
다른 무언가가 이미 짧은 이름을 사용하고 있다면, 그 다른 것이 우선권을 갖습니다. 문서의 예시는 다음과 같습니다. "로컬 deploy skill과 동기화된 deploy가 있는 경우, /deploy는 로컬 skill을 실행하고 /anthropic-skills:deploy는 동기화된 skill을 실행합니다."
다른 명령은 거의 무엇이든 될 수 있습니다. 내장 명령, 번들 skill, 개인 또는 프로젝트 skill, .claude/commands/에 있는 파일, 플러그인 skill 또는 MCP 프롬프트 등이 해당됩니다. 또한 비교 시 대소문자와 일부 공백 차이는 무시되므로, Commit이라는 이름의 동기화된 skill과 commit이라는 이름의 로컬 skill은 동일한 이름으로 간주됩니다.
이것이 skill이 실제로는 전체 이름으로 존재함에도 불구하고 사라진 것처럼 보일 수 있는 이유입니다. /skills를 실행해 보세요. 문서에 따르면 목록 아래의 메모에 짧은 이름을 잃은 각 동기화된 skill에 대한 설명이 표시되며, ~/.claude/에 있는 사용자 자신의 skill이나 명령 파일이 해당 이름을 사용 중인 경우, 이름을 바꾸거나 삭제하여 이름을 확보하는 방법이 안내됩니다.
동기화된 폴더의 편집 내용이 덮어씌워지는 이유
동기화된 폴더는 다운로드 대상이지 편집하는 장소가 아닙니다. 문서는 명확하게 명시합니다. "사용자나 Claude가 ~/.claude/skills/synced/ 아래의 파일을 편집하더라도 변경 사항은 claude.ai 계정에 저장되지 않으며, 나중에 동기화될 때 덮어씌워지거나 삭제될 수 있습니다."
지침 또한 명확합니다. "동기화된 skill을 변경하려면 claude.ai에서 업데이트하세요. 다음 동기화 때 새 버전이 다운로드됩니다."
삭제 시에도 동일한 논리가 적용됩니다. claude.ai에서 여전히 활성화된 상태에서 동기화된 skill 폴더를 수동으로 제거하면, 다음 동기화 때 다시 다운로드됩니다. 제거하려면 claude.ai에서 해당 기능을 끄세요.
로컬에서 복사본으로 작업하고 싶다면, 다른 폴더 이름으로 개인 skills 폴더에 넣으세요. 폴더 이름을 synced로 짓지 마세요. Claude Code는 해당 이름을 예약해 두었으며 그곳에 작성된 skill은 건너뜁니다.
터미널에서 동기화된 skill 실행 시 변경되는 사항
동기화된 skill이 로드되더라도 claude.ai 버전과 다르게 동작할 수 있습니다. 문서는 터미널이나 VS Code 세션에서 Claude Code가 동기화된 skill의 본문을 처리하는 방식을 설명합니다. 셸 출력을 주입하는 라인을 실행하지 않고, @로 참조된 파일을 첨부하지 않으며, 프로젝트 디렉터리나 세션 ID와 같은 플레이스홀더를 채우지 않습니다. 이러한 요소들은 Claude에게 일반 텍스트로 전달됩니다.
Cloud 세션에서는 세션이 격리된 컨테이너에서 실행되므로 본문이 로컬 skill처럼 동작합니다. 데스크톱의 Cowork 세션에서는 셸 라인이 플레이스홀더로 대체됩니다.
skill이 이러한 기능 중 하나에 의존하는 경우, 한 곳에서는 작동하지만 다른 곳에서는 깨져 보일 수 있습니다.
사용자의 머신에만 존재하는 skills
동기화는 한 방향으로만 진행됩니다. 컴퓨터의 ~/.claude/skills/에 있는 skills는 claude.ai로 전송되지 않습니다.
이는 Cowork 및 cloud 세션에서 중요합니다. 문서에 따르면 이들은 "사용자 머신의 ~/.claude/skills/를 읽지 않습니다." 대신 claude.ai 계정에 활성화된 skills를 로드합니다.
그 결과 반대 방향에서 skill이 누락된 것처럼 보일 수 있습니다. 문서에 따르면 skill이 개인 폴더에만 존재하는 경우, 클라우드 예약 작업(scheduled task)이 이를 호출할 때 Claude Code는 해당 skill을 찾을 수 없다고 보고합니다. 각 실행이 새로운 cloud 세션으로 시작되기 때문입니다. 개인 skill을 그곳에서 사용 가능하게 하려면 claude.ai 계정에서 활성화하세요. 프로젝트 스레드 외부의 cloud 세션의 경우, 저장소의 .claude/skills/에 커밋할 수도 있습니다.
데스크톱 예약 작업은 다릅니다. 사용자의 머신에서 실행되므로 ~/.claude/skills/를 로드합니다.
늦게 로드되거나 트리거되지 않는 skills
파일이 제자리에 있음에도 불구하고 skill이 누락된 것처럼 보이게 하는 몇 가지 다른 원인이 있습니다.
중첩된(Nested) skills는 요청 시 로드됩니다. Claude Code를 시작한 위치보다 하위의 .claude/skills 폴더에 있는 skills는 시작 시 로드되지 않습니다. 문서에 따르면 이들은 "Claude가 해당 하위 디렉터리의 파일을 처음 읽거나 편집할 때" 로드됩니다. 더 빨리 로드하려면 해당 하위 디렉터리와 함께 /add-dir을 실행하세요.
새로운 skills는 다시 로드(reload)가 필요할 수 있습니다. Claude Code는 skill 폴더의 변경 사항을 감시합니다. 새로운 skill이 나타나지 않으면 문서에서는 /reload-skills 실행을 권장합니다.
손상된 frontmatter는 설명을 숨깁니다. SKILL.md 상단의 YAML이 파싱되지 않으면, 필드가 설정되지 않은 상태로 skill이 로드됩니다. 이름은 입력할 수 있지만, Claude는 사용자의 요청을 해당 설명과 매칭할 수 없습니다. Claude Code를 --debug와 함께 실행하면 오류가 표시되며, claude plugin validate로 skills 폴더를 확인할 수 있습니다.
skills가 너무 많으면 설명이 누락될 수 있습니다. Claude Code는 skill 이름과 설명 목록을 컨텍스트에 로드합니다. skills가 너무 많으면 예산에 맞추기 위해 일부 설명을 생략하며, 이로 인해 Claude가 매칭하는 키워드가 제거됩니다. /doctor를 실행하여 목록의 비용을 확인하거나, 우선순위가 낮은 skills는 이름만 나열되도록 설정하세요.
일부 이름은 거부됩니다. anthropic-skills라는 이름의 skill 폴더나, 제로 너비 공백(zero-width space) 또는 꺾쇠괄호와 같은 문자가 포함된 폴더 이름은 로드되지 않습니다.
사라진 skills
사용자가 ~/.claude/skills/에 생성한 skill 폴더가 사라졌다면, 문서에서는 한 곳을 지목합니다. "~/.claude/skills/.trash/를 확인하세요."
몇 가지 상황에서 skills가 그곳으로 이동됩니다. syncClaudeAiSkills 설정으로 동기화를 끄면 동기화된 skills가 휴지통 폴더로 이동합니다. 조직에서 claude.ai의 Skills 기능을 끄면 Claude Code는 다운로드된 skills를 제거하며, 문서에 따르면 이들은 동일한 폴더로 이동합니다. 버전 2.1.280 이전에는 skills 폴더에 manifest.json이라는 파일이 있으면 skills가 그곳으로 이동할 수도 있었습니다.
보존 기간이 지나 휴지통 항목이 삭제되기 전이라면, 폴더를 다시 옮겨서 skill을 복구할 수 있습니다.
Customize 메뉴가 Plugins로 변경된 후 Claude 앱에서 skills가 표시되는 위치는 Claude plugins vs skills 가이드에서 다루었습니다.
사람들이 흔히 시도하는 것
세션 도중에 로그인하기. 동기화를 시작하려면 Claude Code를 재시작하세요.
API key를 사용하면서 동기화 기대하기. 동기화에는 /login 로그인이 필요합니다.
짧은 이름 입력하기. 로컬 명령이 해당 이름을 소유하고 있을 수 있습니다. 전체 이름인 anthropic-skills:를 시도해 보세요.
동기화된 복사본 편집하기. 대신 claude.ai에서 skill을 변경하세요.
Cowork가 로컬 skills를 볼 것이라고 기대하기. Cowork는 claude.ai skills를 로드합니다.
해결책: 각 skill에 대해 하나의 소스 유지하기
1단계: /skills 실행
어떤 skills가 로드되었고 어떤 것이 claude.ai에서 동기화되었는지 확인합니다.
2단계: 로그인 방식 확인
동기화된 skills를 원한다면 /login을 통한 claude.ai 로그인을 사용하세요.
3단계: 이름 충돌 해결
로컬 skill의 이름을 바꾸거나, 동기화된 skill의 전체 이름을 사용하세요.
4단계: 각 skill의 소스 위치 기록
어떤 skills가 claude.ai에서 관리되고 어떤 것이 로컬 폴더에서 관리되는지 메모해 둡니다.
MemoryLake에서 설정하기
Skills는 한 방향으로 동기화되고, 일부 세션에서만 로드되며, 비슷한 이름을 가진 여러 복사본으로 존재할 수 있습니다. 어떤 복사본이 진짜인지, 그리고 왜 skill이 그렇게 작성되었는지 아는 것은 skill 파일 자체가 담지 못하는 컨텍스트입니다.
MemoryLake는 이러한 작업 컨텍스트(관례, 워크플로 결정, skills 이면의 이유 등)를 위한 메모리 레이어입니다. 사용자가 직접 관리하는 한 곳에 보관되며 ChatGPT, Claude Code, Codex 등 연결된 어시스턴트에서 사용할 수 있습니다.
사용자는 자신의 언어로 직접 항목을 작성합니다. 사용자의 claude.ai skills, ~/.claude/skills 폴더, 동기화된 skills, 설정 파일 또는 벤더의 저장소에서 아무것도 읽거나 쓰거나 삭제하지 않습니다. Skill 동기화는 Anthropic이 설명하는 방식 그대로 작동합니다.
1단계: API key 생성
로그인 후 대시보드에서 키를 생성합니다. 다른 자격 증명과 마찬가지로 저장소 외부에 보관하세요.

2단계: 첫 번째 메모리 업로드
해결책의 4단계에서 작성한 내용부터 시작하세요. 각 skill이 어디서 관리되는지, 왜 존재하는지 기록합니다. 항목당 하나의 skill을 권장합니다.

3단계: AI 및 에이전트 연결
Claude Code, Codex 및 사용하는 다른 어시스턴트를 연결합니다. 각 어시스턴트는 사용자의 skills에 관한 동일한 노트를 참조할 수 있습니다.

실제 변화하는 점
첫 번째 차이점은 편집 내용 유실이 줄어든다는 것입니다. 어떤 복사본을 변경해야 할지 알게 됩니다.
두 번째는 더 빠른 문제 해결입니다. skill이 누락되었을 때 어디서 가져와야 하는지 알 수 있습니다.
세 번째는 도구 간의 일관성입니다. skills 이면의 동일한 이유와 근거를 Claude Code와 다른 곳에서도 활용할 수 있습니다.
Claude Code에서의 Claude skills 모범 사례
동기화된 skills는 claude.ai에서 편집하세요. 로컬 편집은 덮어씌워집니다.
이름 충돌을 피하세요. 로컬 명령이 짧은 이름을 선점합니다.
동기화를 위해 /login으로 로그인하세요. API key 세션은 동기화되지 않습니다.
Cowork 및 cloud를 위해 claude.ai에서 skills를 활성화하세요. 이들은 로컬 폴더를 읽지 않습니다.
frontmatter를 유효하게 유지하세요. 손상된 YAML은 설명을 숨깁니다.
다시 만들기 전에 휴지통 폴더를 확인하세요. 제거된 skills는 먼저 그곳으로 이동합니다.
결론
Claude Code는 claude.ai 계정에서 활성화된 skills를 ~/.claude/skills/synced/로 동기화하지만, 이는 기능 플래그를 가져오는 claude.ai 계정으로 로그인된 세션에서만 가능합니다. API key 세션, Bedrock, bare 모드, safe 모드 및 일부 관리형 설정은 동기화를 중단시키며, 세션 도중 로그인한 경우 재시작이 필요합니다. 이전에 동기화된 skills는 디스크에 남습니다.
동기화된 skill은 동일한 이름을 가진 다른 명령에 짧은 이름을 양보하므로, /anthropic-skills: 아래에 여전히 존재할 수 있습니다. 동기화된 폴더에 대한 편집은 업로드되지 않으며 덮어씌워질 수 있으므로, claude.ai에서 skills를 변경하세요. Cowork 및 cloud 세션은 로컬 skills 폴더를 읽지 않으며, 사라진 skill을 찾을 때 가장 먼저 확인해야 할 곳은 ~/.claude/skills/.trash/입니다.