Where the Skills Live

The problem

Claude Code 에 스킬이라는 게 있는데, 반복해서 쓰는 절차를 문서로 적어 두면 필요할 때 알아서 꺼내 쓰는 구조입니다. 편한데 읽히는 자리가 정해져 있어요. 흔히 쓰는 건 셋입니다 — 작업 중인 저장소 안, 사용자 폴더, 그리고 설치한 플러그인.

저는 저장소를 여러 개 굴리다 보니 A 에서 만든 규칙이 B 에서는 안 보이고, 그때마다 복사해서 붙였는데 그러면 그때부터 둘이 따로 늙습니다. 나중엔 어느 쪽이 최신인지도 모르게 되고요.

한 대의 컴퓨터에서만 쓸 거면 사실 사용자 폴더(~/.claude/skills/)에 넣으면 끝납니다. 그 컴퓨터의 모든 프로젝트에서 읽히니까요. 굳이 아래처럼 만들 필요가 없습니다.

저는 그게 안 됐습니다. 사용자 폴더의 스킬은 클라우드 세션에서 읽히지 않고, 예약해 둔 작업은 매번 새 클라우드 세션으로 뜹니다. 거기서도 같은 스킬이 필요했어요. 여러 대에서 쓰거나, 스킬 말고 에이전트나 실행 엔진까지 같이 실어야 하면 그때 플러그인입니다.

The idea — a warehouse

그래서 스킬만 모아 두는 저장소를 하나 만들었습니다. 창고라고 부르고 있습니다.

Claude Code 가 플러그인으로 바깥 스킬을 읽을 수 있고, 플러그인 여러 개를 묶어 둔 것을 마켓플레이스라고 부르더군요. 이름은 거창한데 까 보면 GitHub 저장소 하나에 약속된 이름의 파일 몇 개 두는 게 전부였습니다.

What it looks like

your-repo/
  .claude-plugin/
    marketplace.json        ← 창고 목록표
  plugins/
    my-plugin/
      .claude-plugin/
        plugin.json         ← 플러그인 정보
      skills/
        my-skill/
          SKILL.md          ← 언제 쓰고 어떻게 하는지

목록표는 이렇게 생겼습니다.

{
  "name": "my-warehouse",
  "owner": { "name": "your-name" },
  "plugins": [
    {
      "name": "my-plugin",
      "source": "./plugins/my-plugin",
      "description": "이 묶음이 무엇을 하는지",
      "version": "0.1.0"
    }
  ]
}

플러그인 정보는 더 짧고요.

{
  "name": "my-plugin",
  "description": "무엇을 하는 묶음인지",
  "version": "0.1.0",
  "author": { "name": "your-name" }
}

스킬 본문은 맨 위에 이름과 설명을 달고 시작하는데, 이 설명이 생각보다 중요합니다. 이걸 읽고 언제 꺼낼지를 정하다 보니, 실제로 입에서 나올 법한 말을 넣어 두는 쪽이 훨씬 잘 걸리더군요.

---
name: my-skill
description: 언제 쓰는지. "차트", "그래프 그려줘" 처럼 실제로 나올 말을 넣어 둡니다.
---

# 제목

여기에 절차를 적습니다.

How to install it

쓰는 쪽에서는 두 줄이면 끝납니다.

/plugin marketplace add your-name/your-repo
/plugin install my-plugin@my-warehouse

저장소마다 자동으로 잡히게 하려면 그 프로젝트의 .claude/settings.json 에 적어 둡니다. 다만 조건이 하나 붙습니다. 아래를 보시고요.

{
  "extraKnownMarketplaces": {
    "my-warehouse": {
      "source": { "source": "github", "repo": "your-name/your-repo" }
    }
  },
  "enabledPlugins": { "my-plugin@my-warehouse": true }
}

이 방법은 내 컴퓨터에서 도는 세션에만 통합니다. 저장소의 settings.json 에 선언한 플러그인과 사용자 설정에만 켜 둔 플러그인은 클라우드 세션에서 로드되지 않습니다. 클라우드 세션에서도 그 스킬이 필요하면, 그 저장소의 .claude/skills/ 에 직접 커밋해 두는 쪽이 확실합니다. 창고 하나로 전부 덮이지는 않는다는 뜻이고요.

What caught me

여기가 본론인데요.

설정에 다 적어 놨는데 안 잡힙니다. 위의 두 항목을 모두 적어도 외부 플러그인은 처음 한 번은 직접 /plugin install 을 해줘야 켜지더라고요. 이게 은근히 무서운 게, 설정만 믿고 있으면 스킬이 없는 채로 작업이 그냥 흘러갑니다. 있는 줄 알았는데 없는 상태라 결과를 보기 전까지는 모릅니다.

하나 더 있습니다. 플러그인으로 옮기고 나면 스크립트가 자기 위치를 착각해요.

검수 스크립트를 "내 옆 폴더" 기준으로 작업 파일을 찾게 짜 뒀는데, 저장소 안에 있을 때는 맞지만 플러그인은 저장소 밖 캐시에 설치되다 보니 그때부터 엉뚱한 데를 봅니다. 한참 헤맸습니다.

// 플러그인이 되면 틀립니다 — 스크립트 옆을 봅니다
const ROOT = path.resolve(HERE, '../..');

// 작업 중인 저장소를 봅니다
const ROOT = process.env.CLAUDE_PROJECT_DIR || process.cwd();

반대로 플러그인이 들고 다니는 자기 자산(팔레트나 예제 같은 것)은 스크립트 옆에서 읽어야 맞고요. 둘을 이렇게 나눠 두면 헷갈릴 일이 없습니다. · 작업 대상 → 프로젝트 기준 (CLAUDE_PROJECT_DIR) · 자기 자산 → 플러그인 기준 (CLAUDE_PLUGIN_ROOT)

Did it actually help

이틀 뒤에 답이 나왔습니다.

다른 저장소에서 이 스킬을 실제로 쓰다가 선 굵기를 읽는 함수가 빈 값을 내고 있는 걸 발견했는데, 속성에 적힌 굵기를 찾고 있었고 정작 그쪽은 CSS 변수로 선언하고 있었거든요. 창고에서 한 번 고치니 쓰는 곳 전부에 반영됐습니다.

복사해 붙였더라면 저장소마다 따로 찾아 고쳐야 했을 텐데, 그러면 대개 한 곳은 빠뜨립니다. 그리고 빠뜨린 그 한 곳을 한참 뒤에 발견하고요.

복사해서 붙인 순간부터 둘은 따로 늙는다.

What this does not cover

스킬을 무엇으로 채울지는 여기서 다루지 않았습니다. 이 글은 어디에 두느냐까지입니다. · 렌더 엔진처럼 무거운 걸 같이 실으면 처음 한 번 npm install 이 필요합니다 · 저장소를 비공개로 두면 본인만 설치할 수 있습니다. 나눠 쓸 생각이면 공개여야 하고요 · 스킬이 읽히는 자리는 위의 셋 말고도 더 있습니다. 하위 디렉터리, --add-dir 로 붙인 폴더, 조직이 배포한 것까지 문서에 정리돼 있습니다

공식 문서와 대조해서 쓴 글입니다. https://code.claude.com/docs/en/plugin-marketplaces