저는 Claude Code를 사용하여 플러그인 릴리스를 구축하고 있었고, 변경 로그(changelog) 초안이 아주 잘 만들어졌습니다. 마지막 태그부터 현재까지의 git log를 가져와서 == Changelog == 아래에 넣는 방식입니다. 이것은 하나의 절차(procedure)였기에 문제없이 작동했습니다.

다음 단계에서 저는 실수를 했습니다. 릴리스 게시물에 현재 WordPress.org의 활성 설치 수를 추가하고 싶어서

Plugin (플러그인)은 배포 컨테이너 (distribution container)입니다. 그 안에는 Skill (스킬), MCP 설정, slash commands (슬래시 명령어), subagents (서브에이전트), 그리고 hooks (훅)가 들어갑니다. Skill (스킬)은 절차나 지식의 번들 (bundle)이며, 스킬 내부에서 MCP 도구(tool)나 CLI를 호출할 수 있습니다. 이제 slash commands (슬래시 명령어)는 Skill (스킬) 내부에 존재합니다. 레시피 카드 (Skill), 주방을 외부 시장과 연결하는 배관 (MCP), 그리고 이 모든 것을 패키징한 식재료가 가득 찬 주방 전체 (Plugin)라고 생각해보세요. 레시피 카드가 배관보다 나은지에 대해 논쟁하는 사람은 아무도 없습니다. 그것들은 서로 다른 일을 하기 때문입니다. 여기서도 마찬가지입니다. 비교하는 것이 아니라, 당신의 문제가 어느 계층 (layer)에 있는지를 물어야 합니다.

이 계층 구조를 머릿속에 담아두면, 제가 서두에 저지른 실수가 한 줄로 설명됩니다. 저는 Skill (스킬, 절차를 가르침)로 MCP (외부 수치를 가져오는 역할)의 일을 하려고 했습니다. 저는 계층을 혼동하고 있었습니다.

규칙: 가장 가벼운 것부터 시도하라

다음은 전체적인 결정 과정입니다. 위에서 아래로 적용하세요.

1. 단순히 절차나 지식을 가르치는 것인가? Skill (스킬).
2. 실시간 외부 데이터가 필요한가? 그것을 위한 CLI가 있는가? 만약 있다면, 그리고 드물게 사용한다면, Skill (스킬)에서 CLI를 호출하세요.
3. CLI가 없거나, 매일 깊이 있게 사용하는가? MCP.
4. 위의 모든 것을 묶어서 재사용하거나 공유하고 싶은가? Plugin (플러그인).

제가 "가장 가벼운 것부터"라고 말하는 이유는 아래로 내려갈수록 컨텍스트 (context) 비용과 노력이 증가하기 때문입니다. 당신이 원하는 대부분은 1번 항목입니다. 하지만 반짝이는 새로운 도구에 눈이 팔리면, MCP나 Plugin (플러그인)부터 생각하기 시작합니다. 제가 그랬습니다. Skill (스킬)로 충분한지 먼저 묻고, 그다음 CLI로 도달 가능한지 확인한 뒤, 그제야 무거운 도구들을 찾으세요.

최근의 몇 가지 사례를 이 기준에 따라 검토해 보겠습니다. 커밋 메시지 스타일 표준화: 하나의 절차이므로 Skill (스킬). 스테이징 포스트 수 확인: 외부 데이터이지만 wp-cli가 이를 처리하고 제가 드물게 사용하므로, Skill (스킬)에서 CLI를 호출합니다. 운영 대시보드를 매일 깊이 있게 조작: CLI로는 부족하고 빈도가 높으므로 MCP. 여러 플러그인에 걸쳐 공유된 lint 설정과 릴리스 단계를 배포: 배포 목적이므로 Plugin (플러그인).

나머지 내용은 해당 순서대로 각 계층에 대해 다룹니다.

Skill (스킬): 절차와 지식

SKILL.md가 포함된 폴더: 상단에는 YAML frontmatter가 있고, 그 아래에 Markdown 본문이 위치합니다. 설명(description)은 가볍게 준비되어 있으며, 관련 작업이 발생할 때만 본문이 열립니다.

---
name: release-build
description: "플러그인을 위한 릴리스 준비. 버전 업, 변경 로그(changelog) 기록, 배포용 zip 파일 빌드."
...

사람들이 흔히 오해하는 것 중 하나가 allowed-tools입니다. 이것은 실행 가능한 도구를 제한하는 것이 아니라, 목록에 있는 도구들을 확인 프롬프트 없이 실행할 수 있도록 미리 승인하는 것입니다. 목록에 없는 도구도 사용자의 일반적인 권한 설정에 따라 여전히 호출될 수 있습니다. 따라서 진정으로 차단하고 싶은 기능이 있다면 이 목록에서 제외하는 것만으로는 막을 수 없습니다. 또 다른 것은 disable-model-invocation: true인데, 저는 릴리스와 같이 부수 효과(side-effect)가 발생하는 작업을 할 때 이 설정을 사용합니다. Claude가 친절하게 /release-build를 시작하게 두기보다는, 제가 직접 호출하는 것을 선호하기 때문입니다.

핵심 요점: Skill (스킬)은 Claude Code가 실행할 수 있는 로컬 파일과 명령에 접근합니다. 웹사이트의 현재 수치나 실시간 데이터 등을 가져오는 것은 단계를 어떻게 작성하더라도 불가능합니다. 제가 여기서 실수했습니다. Skill은 단계를 암기할 뿐, 외부로 나갈 수 있는 다리가 없습니다.

MCP: 실시간 데이터와 실제 시스템

MCP (Model Context Protocol)는 Claude를 외부 도구 및 데이터와 연결합니다. 예를 들어 .mcp.json과 같은 설정 파일에 서버를 선언합니다:

{
  "mcpServers": {
    "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] }
...

WordPress.org 통계, 스테이징 데이터베이스, GitHub 이슈 등이 이에 해당합니다. 외부로부터 현재 시점의 값을 가져오고 싶을 때가 바로 MCP를 사용할 때입니다. 활성 설치 수(Active install counts)는 매일 변하므로, Skill에 박제된 어제의 수치는 내일이면 틀린 정보가 됩니다. 기록할 수 있는 고정된 것들은 Skill에 넣고, 매번 변하는 것들은 MCP가 필요합니다. /mcp 명령어를 통해 연결된 서버 목록을 확인하고 연결을 해제할 수 있습니다.

하지만 MCP는 무겁습니다, 그것도 꽤 많이 무겁습니다. 아래에서 구체적인 수치를 다루겠지만, "유용해 보이는 건 일단 다 연결하자"라는 방식은 기본값으로 삼기에 너무 무거운 선택입니다.

Skill에서 CLI 호출하기: MCP를 쓰기 전에 먼저 생각할 것

외부 데이터가 필요할 때, 저는 곧바로 MCP로 뛰어들지 않습니다. 먼저 CLI (Command Line Interface)가 이미 그 기능을 수행할 수 있는지 확인합니다. GitHub에는 gh가 있고, WordPress에는 wp-cli가 있습니다. 만약 CLI가 존재한다면, Skill (스킬)의 단계(steps)에서 Bash를 통해 이를 호출하는 것이 대개 더 가볍습니다.

wp post list --post_type=post --post_status=publish --format=count
wp option get tmfs_settings --format=json

그 이유는 컨텍스트 (context)가 로드되는 방식 때문입니다. MCP 서버는 연결하는 순간 전체 도구 스키마 (tool schema)를 로드하며, 매 턴마다 이를 유지합니다. 반면 Bash를 통해 호출되는 CLI는 시작 시 아무것도 로드하지 않습니다. 명령어가 실행될 때만 비용을 지불합니다. 가끔씩 사용하는 기능의 경우, 이 차이는 매우 큽니다. 한 보고된 벤치마크에 따르면, GitHub CLI는 작업당 비용이 GitHub MCP보다 4배에서 32배까지 저렴했습니다. 매일 사용하는 깊은 통합(deep integration)이라면 MCP의 구조화된 결과가 정당화될 수 있겠지만, 한 달에 두 번 정도 사용하는 도구를 위해 전체 스키마를 컨텍스트에 유지하는 것은 나쁜 거래입니다.

Plugin (플러그인): 번들링, 재사용, 공유

Plugin (플러그인)은 Skill (스킬), MCP 설정, 명령어, 서브에이전트 (subagents), 그리고 훅 (hooks)을 plugin.json이 포함된 하나의 배포 가능한 단위로 패키징합니다.

my-plugin/
├── .claude-plugin/plugin.json
├── skills/
...

마켓플레이스에서 /install로 설치하고, /plugins로 관리합니다. 만약 여러 플러그인에 걸쳐 공통적인 릴리스 절차가 있다면, 파일을 여기저기 복사해서 붙여넣는 대신 릴리스 빌드용 Skill (스킬)과 빌드 스크립트를 하나의 Plugin (플러그인)으로 묶어 새 리포지토리(repo)로 한 번에 가져오세요. Plugin (플러그인)은 콘텐츠를 해결하는 것이 아닙니다. 콘텐츠는 Skill (스킬)과 MCP입니다. Plugin (플러그인)은 오직 배포(distribution) 문제만을 해결합니다. 콘텐츠를 먼저 결정하고, 이를 배포하고 싶을 때 Plugin (플러그인)으로 감싸세요. 처음부터 "플러그인을 만들자"라고 시작하면 대개 진행이 막히게 됩니다.

다른 사람의 Plugin (플러그인)을 설치할 때 제가 주의 깊게 보는 한 가지는, Plugin (플러그인)이 MCP 설정과 훅을 포함할 수 있으며, 이것들이 제 컴퓨터에서 코드를 실행할 수 있다는 점입니다. 공식 마켓플레이스는 큐레이션(curated)되어 있지만, 커뮤니티 버전은 제각각입니다. 저는 설치하기 전에 내부에 어떤 MCP와 훅이 들어있는지 확인합니다.

실제 수치로 보는 컨텍스트 비용

"가장 가벼운 것부터(Lightest first)"라는 원칙은 실제 무게 차이에 근거합니다. 수치는 버전과 설정에 따라 다르므로 직접 측정해 보시기 바랍니다. 하지만 보고된 수치들은 매우 극명합니다.

세션은 아무것도 입력하기 전부터 이미 무거운 상태로 시작됩니다. 시스템 프롬프트 (System prompt), CLAUDE.md, 메모리 (Memory), 연결된 MCP 서버들의 도구 스키마 (Tool schemas), 그리고 Skill들의 이름과 설명이 모두 시작 시점에 로드됩니다. 보고된 바에 따르면, 아무것도 입력하지 않은 상태에서 세션은 약 20k에서 30k 토큰으로 시작됩니다.

MCP가 가장 많은 비중을 차지합니다. 연결된 서버는 사용 여부와 관계없이 전체 스키마를 로드하며, 해당 서버를 전혀 사용하지 않는 세션이라 할지라도 매 턴 (Turn)마다 함께 따라다닙니다. 공개적으로 공유된 /context 분석 결과, 200k 컨텍스트 윈도우 (Window)에서 다음과 같은 양상을 보였습니다:

System prompt    3.2k   (1.6%)
System tools    16.1k   (8.0%)
MCP tools       98.7k   (49.3%)   <- 연결된 서버의 도구 정의 (Tool definitions)
...

컨텍스트 윈도우의 거의 절반이 MCP 도구 정의에 할당됩니다. 또 다른 보고에 따르면, 7개의 서버가 대화가 시작되기도 전에 67,300 토큰(약 34%)을 점유했습니다. 서버별로 살펴보면, 공식 GitHub MCP는 GitHub를 전혀 사용하지 않을 때도 27개의 도구에 대해 약 18k를 소모하며, 더 기능이 많은 빌드는 93개의 도구에 걸쳐 약 55k에 달합니다. 한 /doctor 덤프 (Dump) 결과에서는 20개 도구의 서버가 약 14.1k, Playwright(21개 도구)가 약 13.6k, SQLite 서버(19개 도구)가 약 13.4k를 차지하여, 도구당 대략 700 토큰 정도가 소모되었습니다. 그리고 이는 매 턴마다 다시 로드됩니다. 20턴의 세션 동안 15k의 오버헤드 (Overhead)가 발생한다면, 도구를 사용했는지 여부와 관계없이 도구 정의에만 300k 토큰이 소비되는 셈입니다.

Skill은 이와 정반대입니다. 시작 시에는 이름과 설명만 로드되며 각각 수십 토큰 정도만 사용하고, 본문 (Body)은 필요할 때만 호출됩니다. 따라서 많은 Skill을 유지하더라도 시작 비용은 거의 변하지 않습니다. 동일하게 "기능을 추가한다"는 점은 같지만, 무게는 완전히 다릅니다. 이것이 바로 "가장 가벼운 것부터"라는 원칙이 유효한 이유입니다.

측정하고 절감하려면: /context를 실행하여 MCP Tools 섹션을 읽은 다음, /mcp를 사용하여 사용하지 않는 것을 연결 해제하세요. Claude Code의 도구 검색은 도구가 필요할 때까지 스키마 로딩을 지연합니다. 한 번의 측정 결과, 메인 스레드(main-thread) 사용량이 51k에서 8.5k로 감소하여 약 47%의 절감 효과를 보였습니다. 사용하는 도구만 허용 목록(Allow-listing)에 추가하면 50개의 도구가 있는 서버를 5개로 줄여 비용을 약 10분의 1로 낮출 수 있습니다.

한 가지 주의할 점: /context는 과거에 도구당 공유되는 오버헤드를 계산하여 MCP 사용량을 실제보다 과장하여 표시해 왔으며, 실제 수치의 거의 3배에 달했습니다. 이는 2026년 1월 말경에 수정되었습니다. 오래된 수치와 이전 게시물은 무시하고, 본인의 버전에서 직접 측정하세요.

흔한 실수들

• 고정된 절차나 템플릿을 MCP 서버로 만드는 것. 그것은 Skill입니다. 불필요한 무게를 감당하게 되며 기능은 나아지지 않고, 아무런 이득 없이 시작 토큰(startup tokens)만 소모하게 됩니다.
• gh나 wp-cli가 이미 수행하고 있는 작업을 위해 MCP를 구축하는 것. 시작 로드(startup load)는 늘어나지만 기능은 늘어나지 않습니다.
• 긴 작업 절차를 CLAUDE.md에 쑤셔 넣어 파일을 비대하게 만드는 것. CLAUDE.md는 항상 로드됩니다. 작업별 단계는 필요할 때 열리는 Skill에 포함되어야 합니다.
• 슬래시 명령어(slash commands)를 별개의 것으로 취급하는 것. 이제 그것들은 Skill로 통합되었습니다.
• 일회성 작업을 위해 Plugin이나 MCP를 구축하는 것. 그 순간의 프롬프트(prompt)만으로도 충분합니다. 반복할 것이 확실한 것에 대해서만 메커니즘을 구축하세요.

Skill은 리포지토리에 존재하고, MCP는 머신에 존재한다

공유 방식도 다르며, 이는 선택에 영향을 미칩니다. .claude/skills/에 있는 Skill은 git에 포함되는 파일입니다. 커밋되고, 리뷰되며, 코드와 함께 이동합니다. MCP 연결 설정은 API 키와 같은 비밀 정보(secrets)를 포함하는 경향이 있으므로 git에 들어가지 않으며, 머신이나 환경에 종속되어 사람마다 달라집니다. 키를 .mcp.json에 직접 작성하기보다 환경 변수(environment variables)에 보관하세요. Plugin은 머신에 종속된 부분까지도 패키징하여 배포할 수 있는 명시적인 방법입니다. 무엇을 누구와 공유하고 싶은가 하는 점 또한 선택의 또 다른 기준입니다.

다음의 나에게 남기는 메모

확신이 서지 않을 때는: 절차(procedure), 데이터(data), 또는 배포(distribution)를 생각하세요. 절차는 스킬(Skill)입니다. 외부 데이터는 우선 CLI로 처리한 뒤, 그 다음 MCP를 고려하세요. 공유를 위해 묶는 것은 플러그인(Plugin)입니다. 가장 가벼운 것부터 적용하고, 스킬(Skill)만으로 충분하다면 거기서 멈추세요. 무거운 도구부터 시작하지 마세요. 그것만으로도 절차 파일(procedure file)로 실시간 수치를 가져오려 했던 시도를 포함하여, 제가 겪었던 대부분의 혼란을 방지할 수 있었습니다.

에이전트(agent)에게 어느 정도의 실행 권한을 허용할 것인지, 그리고 되돌릴 수 없는 명령(irreversible commands)을 어떻게 중단할 것인지는 별도로 작성해 둔 다른 주제입니다. 저의 릴리스 설정(release setup)을 플러그인(Plugin)으로 묶는 작업은 여전히 제 할 일 목록에 있습니다. 그 작업을 완료하면 그것도 글로 남기겠습니다. 미래의 제가 이 세 가지 앞에서 다시 망설이지 않도록 이 지도(map)를 여기에 남겨둡니다.

참고 문헌 (References)

위의 토큰(Token) 수치는 다른 설정들로부터 얻은 공개 측정값입니다. /context를 사용하여 본인의 환경을 직접 측정해 보세요.