CPN 한국어 자습서 · Claude Certified Developer — Foundations Prep
3-4 · 워크플로 패키징
Packaging a workflow as a plugin: skills, custom commands, and marketplace install
지금까지 CLAUDE.md·규칙 파일·훅·서브에이전트로 팀에 맞는 Claude Code 설정을 만들어 봤습니다. 이 설정은 .claude 폴더에 담겨 프로젝트와 함께 관리됩니다. 이번에는 그 설정을 동료가 한 단계로 설치할 수 있도록 스킬·커스텀 명령·플러그인으로 묶는 방법을 살펴봅니다. 손으로 매번 다시 맞추는 대신, 설치 한 번으로 같은 환경을 갖추는 것이 목표입니다.
이 장에서 배우는 것What you'll learn
약 18분필요할 때 불러오는 재사용 워크플로 — 스킬과 SKILL.md 파일
같은 스킬이 네 런타임에서 각각 어떻게 불러와지고 실행되는지
런타임을 넘나들며 이식되게 하는 규칙 세 가지
커스텀 명령과 플러그인 명령의 이름 규칙(네임스페이스)
여러 요소를 묶는 플러그인·마켓플레이스 설치와 무엇을 언제 고를지
절대 경로·환경 변수로 남의 컴퓨터에서 깨지는 플러그인과 막는 법
SKILL.md라는 마크다운 파일로 .claude/skills 폴더에 둔다. 파일 앞머리(front matter)에 언제 쓰는 스킬인지 설명을 적고, 본문에 실행 단계를 적는다./이름 형태로 실행한다.스킬은 .claude/skills 폴더에 두는 SKILL.md 마크다운 파일 하나입니다. 파일 앞머리에는 이 스킬을 언제 쓰는지를 설명으로 적고, 본문에는 실제 실행 단계를 적습니다. 같은 스킬 파일 하나를 Claude Code에서도, Messages API 호출에서도, Agent SDK에서도 쓸 수 있습니다.
그런데 이 세 곳에서 달라지는 것은 파일 자체가 아닙니다. 어디서 실행되는지, 어떻게 불러와지는지, 무엇을 건드릴 수 있는지가 런타임마다 다릅니다. Claude Code에서만 스킬을 써 본 개발자라면 API에서는 성립하지 않는 것들을 당연하게 여기기 쉽습니다. 그래서 네 런타임이 스킬을 어떻게 불러오고 어디서 실행하는지 하나씩 정리해 봅니다.
FOUR RUNTIMES — 같은 스킬, 네 곳의 실행 방식
| 런타임 | 불러오는 방식 · 실행 위치 · 알아 둘 점 |
|---|---|
| Claude Code | 불러오기 — 파일시스템의 .claude/skills에서 찾는다. 설명이 요청과 맞거나 이름으로 직접 부르면 불러온다. 실행 위치 — 내 터미널 세션 안. 로컬 파일을 대상으로, 현재 권한 모드와 거부 규칙 아래에서 실행된다. 알아 둘 점 — 파일시스템 기반이고, 설정 계층의 지배를 받는다. |
| Messages API | 불러오기 — 요청과 함께 보내져 코드 실행 컨테이너 안에서 실행된다. code-execution과 skills 베타 헤더가 필요하다. 실행 위치 — 내 컴퓨터가 아니라 Anthropic의 코드 실행 컨테이너 안. 파일·도구 접근 범위는 그 컨테이너가 주는 만큼이다. 알아 둘 점 — 로컬 파일이나 로컬 도구를 가정한 스킬은 여기서 같은 방식으로 작동하지 않는다. 그 파일들이 있는 곳에서 실행되는 것이 아니기 때문이다. |
| Agent SDK | 불러오기 — SDK가 실행하는 에이전트가 불러온다. 다만 파일시스템 설정(CLAUDE.md·스킬)을 불러올지는 settingSources 설정이 정한다. 기본값에 기대지 말고 명시적으로 지정하고, 빌드 시점에 Agent SDK 참고 문서로 현재 기본 동작을 확인한다. 실행 위치 — SDK가 실행되는 프로세스, 곧 내 환경. 단 파일시스템 소스를 불러오라고 지정한 뒤부터다. 알아 둘 점 — 자주 겪는 일: Claude Code에서 되던 스킬이 SDK에서는 아무 동작도 하지 않는다. settingSources를 지정하지 않아 스킬이 아예 로드되지 않은 경우다. |
| 매니지드 에이전트 | 불러오기 — 모델·시스템 프롬프트·도구·MCP 서버·스킬을 담아 API 리소스로 한 번 정의한다. Anthropic이 에이전트 실행 시 서버 쪽에서 스킬을 불러오므로, 내 쪽에는 파일시스템 탐색 단계가 없다. 실행 위치 — Anthropic이 마련해 실행하는 샌드박스 안. 내 애플리케이션은 사용자 이벤트를 보내고 스트림으로 결과를 받는다. 로컬 파일이 아니라 그 샌드박스가 주는 것만 쓸 수 있다. 알아 둘 점 — 현재 managed-agents-2026-04-01 베타 헤더가 필요한 공개 베타다. 세션이 서버에 저장되어, 지금은 Zero Data Retention이나 HIPAA BAA 적용 대상이 아니다. 스킬은 세션이 아니라 에이전트 리소스를 정의할 때 붙이며, 바꾸려면 에이전트 정의를 수정한다. |
스킬 파일은 하나지만, 그 파일이 어디서 실행되는지에 따라 쓸 수 있는 것이 달라집니다. 내 컴퓨터에서 실행될 때와 Anthropic 서버에서 실행될 때는 접근할 수 있는 파일부터 다른 겁니다.
스킬이 여러 런타임에서 작동하게 하려면 파일을 잘 쓰는 것만으로는 부족합니다. 어느 런타임에서 실행되든 성립하도록 아래 세 가지를 지키며 설계해 두는 것이 좋습니다.
정리하면, 스킬은 한 번 작성해 재사용할 수 있지만 여러 터미널에서 쓸 수 있도록 일부러 설계해야 합니다. 설명이 분명하고 로컬 환경 가정이 없는 스킬은 런타임을 넘나들며 매끄럽게 이식되지만, 특정 로컬 환경을 전제한 스킬은 그렇지 않습니다.
스킬이 잘 맞는 자리와 아닌 자리
| 잘 처리하는 일 | 복잡해지는 지점 | 다른 방법이 나은 경우 |
|---|---|---|
| 한 번 작성한 과제별 절차를 대화형 터미널·API 연동·헤드리스 SDK 작업에서 두루 재사용하는 일. | 런타임마다 스킬을 불러오고 격리하는 방식이 달라서, API의 베타 헤더와 SDK의 settingSources를 챙겨야 한다. | 프로젝트의 모든 세션에 적용돼야 하는 지침이라면 여전히 CLAUDE.md가 맞다. 스킬은 필요할 때만 불러오는, 이식 가능한 절차를 위한 것이다. |
커스텀 명령은 정해진 절차를 부르는 단축 명령입니다. 요즘 Claude Code에서는 명시적 호출이든 자동 호출이든 스킬 형식을 권장합니다. 스킬을 /스킬이름으로 직접 부를 수도 있고, 관련이 있을 때 Claude가 알아서 불러오게 둘 수도 있습니다.
예전의 .claude/commands/ 폴더 방식도 아직 작동하지만 이제는 지난 방식입니다. 명시적으로 부를 때만 실행되길 원한다면, 스킬 앞머리에 disable-model-invocation: true를 지정하면 됩니다.
플러그인 명령은 이름 앞에 자동으로 꼬리표가 붙습니다(네임스페이스). 플러그인 이름이 접두어가 되어서, payments라는 플러그인의 run-tests 명령은 /payments:run-tests로 부릅니다. 덕분에 서로 다른 두 플러그인이 똑같이 run-tests 명령을 담아도 부딪히지 않습니다. 플러그인 이름은 인터페이스의 일부라고 보는 것이 좋습니다. 담아 내보내는 모든 명령 앞에 붙고, 플러그인 이름을 바꾸면 그 명령들이 한꺼번에 바뀌기 때문입니다.
커스텀 명령은 이 절차를 이 이름으로 부르겠다고 정해 두는 고정 진입점입니다. 설명 매칭에 기대지 않고, 자주 쓰는 절차를 이름으로 곧장 부르고 싶을 때 씁니다.
플러그인은 스킬·훅(정해진 시점에 자동으로 실행되는 장치)·서브에이전트·MCP 서버를 하나의 설치 단위로 묶은 것입니다. 이렇게 묶은 플러그인은 마켓플레이스로 배포할 수 있습니다. 마켓플레이스는 누군가 만들어 공유한 플러그인 목록입니다.
공식 Anthropic 마켓플레이스는 Claude Code를 시작하면 자동으로 준비됩니다. GitHub 저장소에 올라온 외부 마켓플레이스는 /plugin marketplace add <owner/repo> 같은 명령으로 추가할 수 있습니다. 그러면 동료는 간단한 설치 명령 하나로 같은 설정을 갖추게 됩니다. 손으로 밟던 여러 설정 단계가, 버전이 붙고 이력을 확인할 수 있는 설치 한 번으로 바뀌는 겁니다. 플러그인은 구성 요소를 이렇게 배치합니다.
플러그인 매니페스트가 이 꾸러미를 설명하고, 설치 명령이 대상 설치본에 연결해 줍니다. 플러그인은 개인이 받을 수도 있고, 조직 전체 차원에서 배포할 수도 있습니다.
조직 관리자는 관리 설정조직 차원에서 위에서 내려 적용하는 설정 계층. 사용자·프로젝트 설정보다 우선한다.으로 플러그인을 조직 전체에 배포할 수 있습니다. 관리형 마켓플레이스 허용 목록은 사용자가 추가할 수 있는 마켓플레이스 출처를 제한해서, 플러그인이 어디에서 오는지를 조직이 통제합니다. 다만 허용 목록은 사용자가 추가할 수 있는 범위를 제한할 뿐, 마켓플레이스를 자동으로 등록해 주지는 않습니다. 사용자가 직접 add 명령을 치지 않아도 모두에게 마켓플레이스를 내려 주고 싶다면, 허용 목록 설정과 함께 관리 설정의 extraKnownMarketplaces를 같이 씁니다.
우선순위는 배포 범위에서 나옵니다. 관리 설정이 사용자·프로젝트 설정보다 위에 있어서, 관리 범위로 배포한 플러그인이 우선하고 사용자나 프로젝트 파일이 덮어쓸 수 없습니다. 정확한 설정 이름은 참고 문서에서 확인합니다.
무엇을 언제 고르나 — 스킬 · 커스텀 명령 · 플러그인
| 계층 | 무엇인가 | 누구를 위한 것 | 언제 고르나 |
|---|---|---|---|
| 스킬 | .claude/skills에 두는 마크다운 파일. 설명이 과제와 맞거나 이름으로 부르면 불러온다. | Claude Code를 대화형으로 쓰는 개별 개발자나 팀. | 과제별 절차를 필요할 때까지 문맥 밖에 두고 싶을 때. PR 리뷰나 배포 점검표처럼, 그 작업을 할 때만 불러오면 되는 절차에 맞다. |
| 커스텀 명령 | 정해진 절차를 명시적으로 부르면 실행되는, 이름 붙은 단축. | 자주 쓰는 절차에 예측 가능한 진입점을 두고 싶은 개발자. | 절차에 분명한 이름이 있고, 설명 매칭에 기대기보다 직접 불러 실행하고 싶을 때. |
| 플러그인 | 스킬·훅·서브에이전트·MCP 서버를 버전과 함께 묶어 마켓플레이스로 배포하는 꾸러미. | 공유된 설정을 버전째 한 번에 설치하고 싶은 팀. | 잘 돌아가는 설정이 지금 한 컴퓨터에만 있고, 이를 공유하고 버전을 붙여 팀 전체에서 똑같이 유지해야 할 때. |
COST · COMPLEXITY · RISK — 묶기 전에 따져 볼 것
| 비용 | 스킬은 활성화될 때 문맥 비용이 늘고, 플러그인은 설치·유지 부담이 생깁니다. 물어볼 것은 이것입니다 — 설치 비용을 플러그인 설치처럼 한 번만 치를 것인가, 아니면 모든 개발자가 같은 수작업을 반복하듯 매번 치를 것인가. |
|---|---|
| 복잡성 | 스킬 안에 절대 경로를 넣어 둔 플러그인은 작성자에게는 제대로 설치되지만 다른 사람에게는 실패합니다. 스킬이나 훅 명령에 넣어 둔 경로·환경 가정이야말로 컴퓨터를 옮길 때 가장 먼저 깨지는 지점이기 때문입니다. |
| 리스크 | 플러그인은 자기가 묶은 구성 요소를 모든 설치본으로 함께 나릅니다. 그런데 작성자가 로컬에서 기대던 거부 규칙이나 훅은, 꾸러미에 명시적으로 담기지 않으면 함께 가지 않습니다. 스킬이나 훅이 꾸러미에 포함되지 않은 보호 장치에 묶여 있다면, 그 보호는 동료의 컴퓨터로 옮겨 오지 않습니다. |
같은 리뷰 체크리스트 스킬을 서로 다른 곳에서 다시 쓰려는 네 가지 상황입니다. 각 상황에서 스킬이 불러와져 실행되려면 무엇을 설정해야 하는지 골라 보세요.
정답을 먼저 떠올려 본 뒤 골라 보세요. 맞히면 설명이 나옵니다.
Q1한 개발자가 Claude Code 터미널에서 리뷰를 요청할 때 스킬이 불러와지길 원합니다.
Claude Code는 파일시스템의 .claude/skills에서 스킬을 찾습니다. 그래서 설명이 리뷰 요청과 맞게 SKILL.md를 그 폴더에 두면 됩니다. 베타 헤더나 settingSources는 다른 런타임에서 필요한 설정입니다.
Q2어떤 서비스가 Messages API를 호출하면서, 그 요청의 일부로 스킬이 실행되길 원합니다.
Messages API에서는 스킬이 코드 실행 컨테이너 안에서 실행됩니다. code-execution과 skills 베타 헤더가 필요하고, 컨테이너에는 내 로컬 파일·도구가 없으므로 그것들에 기대지 않게 작성해야 합니다.
Q3예약 실행되는 헤드리스 작업이 Agent SDK를 쓰는데, 저장소에 있는 스킬이 불러와지길 기대합니다.
Agent SDK는 settingSources를 지정해야 파일시스템의 스킬을 불러옵니다. 기본값에 기대면 스킬이 아예 로드되지 않는 일이 흔합니다. 예약 실행되는 헤드리스 작업이라도 이 설정을 명시해야 저장소의 스킬이 올라옵니다.
Q4한 제품 팀이 같은 스킬을, Anthropic이 호스팅하는 오래 사는 에이전트 안에서 세션을 넘나들며 에이전트 ID로 부를 수 있게 실행하려 합니다.
Anthropic이 호스팅하는 매니지드 에이전트는 스킬을 API 리소스 정의에 담고, 호출에 managed-agents-2026-04-01 베타 헤더를 지정합니다. 스킬은 Anthropic 샌드박스에서 실행되므로 로컬 파일에 기대지 않게 작성합니다. 같은 SKILL.md라도 런타임마다 불러오고 격리하는 방식이 달라, "어디서나 돌아간다"는 것은 저절로 얻는 게 아니라 런타임에 맞춰 설정하는 것입니다.
플러그인이 깨끗하게 설치됐다는 것은 꾸러미가 제대로 조립됐다는 뜻이지, 잘 실행된다는 뜻은 아닙니다. 설치와 실행은 서로 다른 일이기 때문입니다. 설치는 파일을 제자리에 복사합니다. 실행은 그 파일이 가리키는 경로와 변수를, 실제로 실행되는 컴퓨터를 기준으로 풀어냅니다.
그래서 작성자가 자기 컴퓨터의 폴더 구조를 스킬에 넣어 두면, 설치는 어디서나 성공하지만 실행은 작성자 컴퓨터 말고는 다 실패합니다. 작성자 눈에는 보이지 않는 차이라서 놓치기 쉽습니다.
WHAT HAPPENED — 실제로 있었던 일
한 개발자가 배포 워크플로 스킬을 만들어 플러그인으로 묶고, 자기 컴퓨터에서 시험했습니다. 로컬 시험은 통과했고, 사내 마켓플레이스로 팀에 배포됐고, 동료들의 설치도 모두 성공했습니다. 그런데 어느 동료가 스킬을 실행하는 순간 실패했습니다.
원인은 스킬의 SKILL.md 안에 있었습니다. 한 명령이 /Users/alexmorgan/projects/deploy-utils/validate.sh를 가리키고 있었는데, 그 폴더는 작성자 컴퓨터에만 있고 다른 어디에도 없었습니다. 스킬이 작성자 홈 디렉터리의 절대 경로를 담고 있었으니, 동료의 실행은 자기 컴퓨터에 없는 파일을 찾다가 멈춘 겁니다.
같은 플러그인의 두 번째 스킬은 환경 변수 DEPLOY_TOKEN에 기대고 있었습니다. 작성자가 자기 셸 프로파일에 설정해 둔 변수였는데, 플러그인 설명 문서(README)에는 언급이 없었습니다. 동료 세 명이 두 시간을 헤맨 뒤에야 두 번째 실패의 원인이 빠진 변수라는 것을 찾아냈습니다.
두 실패 모두 작성자의 컴퓨터를 팀의 컴퓨터로 착각한 데서 나왔습니다. 다만 성격은 다릅니다. 절대 경로는 SKILL.md에 글자 그대로 적혀 있어서, 파일을 읽는 검토자가 잡아낼 수 있습니다. 환경 변수 쪽이 더 위험한데, 꾸러미 어디에도 그 의존성을 알리는 곳이 없기 때문입니다. 스킬은 그 변수가 필요한 단계에 이르기 전까지는 멀쩡히 실행되다가, 바로 그 지점에서야 실패합니다. 세 사람이 두 시간을 쓴 이유가 여기에 있습니다.
$CLAUDE_PROJECT_DIR로, 플러그인 안에 동봉한 스크립트는 ${CLAUDE_PLUGIN_ROOT}로 참조하면, 누구 컴퓨터에서 실행하든 어느 폴더에서 세션을 시작하든 경로가 제대로 풀립니다.아래 SKILL.md는 작성자 컴퓨터에서는 되지만, 동료가 프로젝트를 복제해 플러그인을 설치하면 실패합니다. 결함 하나를 먼저 찾고, 이어서 올바른 수정을 골라 보세요.
BROKEN SKILL.md — 결함이 하나 있는 정의
--- name: deploy-validate description: Validates a deployment configuration before release. --- ## Steps 1. Run the validation script: /Users/alexmorgan/projects/deploy-utils/validate.sh ← 절대 경로 2. If the script exits with a non-zero code, report the error to the developer. 3. If validation passes, confirm the deployment configuration is safe to proceed.
결함을 먼저 짚어 본 뒤 골라 보세요. 맞히면 설명이 나옵니다.
Q11부 · 이 정의의 결함은 무엇일까요?
결함은 1단계의 절대 경로입니다. 그 경로는 작성자의 홈 디렉터리로 풀리는데, 저장소를 다른 위치에 복제한 동료에게는 그런 경로가 없어서 스크립트 참조가 실패합니다. 이름 불일치나 짧은 설명, 보고 대상은 이 실패의 원인이 아닙니다.
Q22부 · 올바른 수정은 무엇일까요?
수정은 CLAUDE_PROJECT_DIR(또는 동일한 변수)로 프로젝트 루트를 기준 삼아 스크립트를 참조하는 것입니다. 그러면 프로젝트를 어디에 복제하든 저장소 루트에서 경로가 풀립니다. 다른 절대 경로나 홈 단축 경로는 같은 문제를 되풀이하고, 단계를 지우는 것은 검증 자체를 없애 버립니다.
$CLAUDE_PROJECT_DIR·${CLAUDE_PLUGIN_ROOT} 사용, 의존 자산 동봉, 환경 변수 문서화와 설치 시점 검증, 깨끗한 컴퓨터에서의 설치 시험으로 막습니다.모듈 3의 다음 레슨은 MCP 서버를 다룹니다. 한 걸음 더 들어가 봅니다. → 3-5 · MCP 서버
전 코스는 계속 무료입니다. 등록하면 이 코스의 남은 38개 레슨을 끝까지 읽을 수 있습니다.
이미 등록하셨다면 그때 쓰신 이메일을 넣어 주세요.