클라우드 개발 환경에서도 로컬 스킬 사용하기! 【Claude Code on the web】

서론

Claude Code on the Web을 사용하고 계신가요?

유명 스킬 grill-me의 제작자인 Matt 씨가 로컬 개발을 떠나 클라우드 개발로 전환하고 있다는 트윗 정도의 시점부터 '클라우드 개발', '클라우드 에이전트'라는 화제를 자주 듣게 되었습니다.

저 역시 사용해보고 싶다고 생각하면서도, **'로컬 스킬을 사용할 수 없다'**는 핑계 때문에 조금 망설였었는데, 이번 설정을 통해 상당히 적극적으로 클라우드 개발을 개발 플로우에 통합할 수 있게 되었습니다! (이 이야기는 다른 글로 하겠습니다.)

여러 가지 시도와 시행착오를 거쳤지만, 설정 방법은 이 외에도 몇 가지 방식이 있을 것 같아 예시로 공유해 드립니다.

할 수 있게 되는 것들

Claude Code on the Web에서 로컬 스킬을 모두 사용할 수 있게 됩니다.

참고로, Claude Web 앱이나 스마트폰 앱 등 (일반 채팅)에서도 로컬 스킬을 사용할 수 있게 됩니다!

전제

로컬의 ClaudeCode에서 사용하던 스킬을 클라우드 환경(Claude Code on the web)이나 Claude Web 앱에서 사용할 수 있도록 하는 것입니다.

로컬 스킬은 chezmoi를 사용하여 다른 PC 설정과 함께 dotfiles (개인 리포지토리)로 관리하고 있습니다.

dotfiles/ # chezmoi의 소스 (개인 리포지토리)
├── .chezmoiroot # 내용은 "home". home/ 하위만 chezmoi의 소스로 취급합니다
├── home/
...

구체적인 방법

단도직입적으로 결론부터 말씀드리자면, 자신의 스킬을 플러그인으로 패키징함으로써 상당히 간단하게 구현할 수 있었습니다.

1. dotfiles에 마켓플레이스와 플러그인 정의 추가하기

claude.ai는 리포지토리 직하위의 .claude-plugin/marketplace.json을 읽고, source에 작성된 디렉토리를 플러그인으로 배치합니다. 플러그인 내부의 skills/ 하위가 스킬로 로드됩니다. 여기서는 home/dot_agents를 그대로 플러그인으로 사용했습니다.

dotfiles/
├── .chezmoiroot
+├── .claude-plugin/
...

{
"name": "yasu-dotfiles",
"owner": { "name": "yasu-888" },
...

{
"name": "dotfiles"
}

참고: Create a marketplace, Marketplace reference, Plugins reference

2.

3. 추가 > 마켓플레이스 추가하기

4. 리포지토리에서 추가하기

참고: Plugins (Find and add a plugin)

5. dotfiles를 선택하여 동기화하기

참고: Plugins (Find and add a plugin), Plugin feature support across platforms

'추가한 마켓플레이스에서' dotfiles에 있는 스킬이 추가됩니다.

참고: Skills overview

https://claude.ai/code 의 클라우드 세션에서 사용하기

7.

명시적으로 지정하고 싶을 때는, 'hello' 등과 입력한 후 사용할 수 있습니다.

플러그인의 스킬은 /dotfiles:grilling처럼, 플러그인 이름이 앞에 붙은 이름으로 나타납니다.

참고: Claude Code on the web, Skills

막혔던 점

• chezmoi의 파일명이 그대로 전달됨

claude.ai는 리포지토리 내부를 그대로 배치하기 때문에, executable_start-server.sh나 literal_run_eval.py와 같은 chezmoi 접두사가 붙은 이름 그대로 도착하여, 스킬이 호출하는 스크립트를 찾을 수 없게 되었습니다. 스킬 하위에서는 chezmoi 접두사를 사용하지 않는 이름으로 변경했습니다.

• 실행 비트가 사라짐

플러그인은 zip 형태로 전달되기 때문에 스크립트의 실행 권한(chmod+x)이 사라집니다. ./scripts/x.sh처럼 직접 실행하면 Permission denied가 발생하므로, 스크립트는 bash scripts/x.sh나 uv run scripts/x.py처럼 인터프리터를 붙여 호출하는 방식으로 변경했습니다 (공식 스킬도 같은 방식이었습니다). -
settings.json 설정은 전달되지 않습니다.

로컬의 settings.json에서 skillOverrides를 통해 수동으로 지정했던 스킬이 웹에서는 자동으로 호출되는 상태가 됩니다. SKILL.md의 frontmatter에 disable-model-invocation: true라고 작성하면 로컬과 웹 모두에서 적용됩니다. 마찬가지로, 전역의 CLAUDE.md와 사용자 설정의 hook도 웹에는 전달되지 않습니다.

참고: Skills (Control who invokes a skill) -
description에 꺾쇠괄호(<>)를 쓰면 경고가 발생합니다.

<repo> 같은 꺾쇠괄호는 claude.ai가 제거하고 저장하기 때문에 동기화할 때마다 경고가 나타납니다. {repo}처럼 수정했습니다. -
push해도 동기화되지 않는 경우가 있습니다.

'자동으로 동기화'를 켜 두었더라도 push만으로는 재동기화되지 않는 경우가 있었습니다. '마켓플레이스 관리'에서 '업데이트 확인'을 누르면 가져와집니다 (첫 번째 시도는 실패할 수 있으니, 잠시 기다렸다가 다시 눌렀더니 성공했습니다).

참고: Plugins (Manage installed plugins) -
로컬의 Claude Code에도 같은 플러그인이 전달됩니다.

claude.ai에서 활성화한 플러그인은 로컬의 Claude Code에도 dotfiles@synced로 읽혀져서, 사용자의 스킬과 중복되게 됩니다. 로컬의 settings.json에서 enabledPlugins를 `