만약 여러분이 Claude Code 스킬을 작성했고 다른 사람들이 실제로 그것을 사용하기를 원한다면, Gist에 SKILL.md 파일을 덩그러니 두는 것만으로는 충분하지 않습니다. 이제 Claude Code에는 마켓플레이스 (marketplace)와 Discover 탭이 포함된 제대로 된 플러그인 (plugin) 형식이 생겼습니다. 여러분의 스킬을 플러그인으로 패키징하는 것이 한 줄의 명령어로 설치 가능하게 만들고, 궁극적으로는 모든 사람에게 발견될 수 있게 만드는 방법입니다.

저는 지난주에 일련의 프리랜서 관리 스킬들을 설치 가능한 플러그인으로 전환하는 전체 과정을 거쳤습니다. 따라서 여기 그 작동 방식에 대한 구체적이고 군더더기 없는 버전을 소개합니다.

사고 모델 (The mental model)

두 가지 개념이 있으니 혼동하지 마세요:

• **플러그인 (plugin)**은 여러분의 결과물입니다: 매니페스트 (manifest)와 여러분의 스킬/에이전트/훅 (skills/agents/hooks)이 포함된 폴더입니다.
• **마켓플레이스 (marketplace)**는 하나 이상의 플러그인을 나열하는 카탈로그입니다. GitHub 리포지토리에 marketplace.json을 포함하면 추가 가능한 마켓플레이스가 됩니다.

멋진 점은: 단일 리포지토리가 이 두 가지 모두가 될 수 있다는 것입니다 — 즉, 플러그인이자 자기 자신을 가리키는 단일 플러그인 마켓플레이스가 될 수 있습니다. 이것이 가장 간단한 설정이며 제가 보여드릴 방식입니다.

1. 플러그인 매니페스트 (The plugin manifest)

리포지토리 루트에 .claude-plugin/plugin.json을 생성하세요:

{
  "name": "freelancekit",
  "version": "1.0.0",
...

제 시간을 뺏었던 두 가지 주의사항:

• .claude-plugin/ 내부에는 오직 plugin.json만 들어가야 합니다. 여러분의 skills/, agents/, hooks/ 디렉토리는 .claude-plugin/ 내부가 아니라 **리포지토리 루트 (repo root)**에 위치해야 합니다. 잘못된 위치에 두면 Claude Code가 이를 조용히 찾지 못합니다.
• 만약 version을 설정하면, 사용자는 여러분이 버전을 올릴 때만 업데이트를 받게 됩니다. 이를 생략하면 모든 커밋이 새로운 버전으로 간주됩니다 (커밋 SHA가 사용됨). 의도적으로 버전을 설정하세요.

2. 스킬 자체 (The skill itself)

스킬은 skills/<name>/SKILL.md에 위치합니다. plugin.json의 name이 네임스페이스 (namespace)가 되므로, freelancekit이라는 이름의 플러그인에 있는 skills/invoice/SKILL.md는 /freelancekit:invoice로 호출됩니다.

---
name: invoice
description: "작업에 대한 일반적인 영어 설명을 바탕으로 깔끔하고 고객에게 바로 보낼 수 있는 인보이스를 생성합니다. 사용자가 \"make an invoice\", \"bill this client\"라고 말하거나 시간, 요율 또는 비용을 설명할 때 사용하세요."
...

description이 여기서 가장 중요한 역할을 합니다. 모델이 스킬을 언제 실행할지 결정하는 기준이 바로 이 부분이기 때문입니다. 단순히 무엇을 하는지가 아니라, 트리거 문구("make an invoice", "bill this client")를 앞부분에 배치하세요. 모호한 설명은 절대 트리거를 작동시키지 못합니다.

3. 리포지토리를 마켓플레이스로 만들기

마찬가지로 루트(root) 디렉토리에 .claude-plugin/marketplace.json을 추가하면 사람들이 귀하의 리포지토리를 직접 추가할 수 있습니다:

{
  "name": "freelancekit",
  "owner": { "name": "Your Name" },
...

"source": "./"는 "플러그인이 이 동일한 리포지토리임"을 의미합니다. 이것이 자기 참조(self-pointing) 트릭입니다.

4. 배포하기 전에 로컬에서 테스트하기

테스트를 위해 반드시 게시할 필요는 없습니다. Claude Code를 해당 폴더로 직접 지정하세요:

claude --plugin-dir ./freelancekit

그 다음 /reload-plugins를 실행하고 스킬을 테스트해 보세요. claude plugin validate는 다른 사람들이 확인하기 전에 매니페스트(manifest) 오류를 잡아내므로, 반드시 실행해 보시기 바랍니다.

5. 사람들이 설치할 수 있게 하기

GitHub에 푸시하고 나면, 누구나 귀하의 마켓플레이스를 추가하고 두 줄의 명령어로 설치할 수 있습니다:

/plugin marketplace add your-username/your-repo
/plugin install freelancekit@freelancekit

6. 공식 Discover 탭에 등록하기

Anthropic은 Claude Code의 Discover 탭에 표시되는 커뮤니티 마켓플레이스를 운영합니다. 앱 내 양식(조직용 claude.ai 양식과 개인용 Console 양식이 있음)을 통해 제출하면 자동 검토를 거치게 되며, 승인된 플러그인은 매일 밤 동기화되는 anthropics/claude-plugins-community 카탈로그에 고정됩니다. 제출 시 동일한 검사가 수행되므로, 먼저 claude plugin validate를 실행하세요.

예제는 실제이며 무료입니다

위의 모든 내용은 제가 실제로 배포하는 플러그인의 설정 과정입니다. 작동하는 예제를 직접 살펴보고 싶다면, 무료 /invoice 스킬을 한 줄로 설치할 수 있습니다:

/plugin marketplace add ricardo-agent/freelancer-skills

또는 skills.sh를 통해 설치할 수 있습니다: npx skills add ricardo-agent/freelancer-skills. 몇 가지 프리랜서 업무를 설명하면 인보이스(invoice)를 작성해 줍니다. 이는 더 큰 프리랜서 관리(freelance-admin) 팩의 무료 구성 요소이지만, 여기서 핵심은 전체 형식을 처음부터 끝까지 확인할 수 있는 실제적이고 최소한의 기능을 갖춘 MIT 라이선스 플러그인이라는 점입니다.

핵심 요약 (Takeaway)

Claude Code 스킬을 공유하는 데 드는 장벽은 이제 사실상 제로입니다. 하나의 매니페스트(manifest), 하나의 마켓플레이스(marketplace) 파일, 하나의 검증(validate) 명령만 있으면 됩니다. 만약 여러분이 단 한 줄의 프롬프트(prompt)로 여러분 자신의 시간을 절약해 주는 무언가를 만들었다면, 이를 플러그인으로 패키징하는 데는 20분이면 충분합니다. 그리고 이것이 바로 여러분의 개인적인 해킹(hack) 도구가 아닌, 다른 사람들이 실행할 수 있는 무언가로 변모하는 방법입니다.

여러분은 무엇을 Claude Code 스킬로 만드셨나요? 다른 사람들이 어떤 워크플로(workflow)를 인코딩했는지 궁금합니다.