플러그인을 처음 만들어보려는데 어디서 시작해야 할지 막막했다면 이 글이 그 출발점이다. plugin.json 하나로 Claude Code가 어떻게 내 도구를 인식하는지, 세 개의 핵심 폴더가 각각 무슨 역할을 하는지 실제 구조를 뜯어보며 정리했다.
플러그인이 뭔가 — 구조부터 이해하기
Claude Code 플러그인은 결국 디렉토리 하나다. 복잡한 빌드 도구도, 패키지 레지스트리 등록도 필요 없다. ~/.claude/plugins/{플러그인 이름}/ 경로에 파일 몇 개만 놓으면 Claude Code가 시작할 때 자동으로 불러온다.
핵심은 딱 두 가지다:
plugin.json— Claude Code에게 "이 플러그인이 존재한다"고 알리는 선언 파일skills/,commands/,hooks/— 실제 동작을 담는 세 폴더
처음 만들 때는 plugin.json + skills/main.md 두 파일만으로도 동작한다. 여기서 시작해서 점점 확장하면 된다.
plugin.json 해부
{
"name": "my-plugin",
"description": "내가 만든 첫 플러그인",
"author": "seunghyeon",
"version": "0.1.0",
"entrypoint": "skills/main.md"
}
필드별 역할을 정리하면 이렇다.
| 필드 | 역할 | 필수 여부 |
|---|---|---|
name |
플러그인 식별자, 디렉토리 이름과 일치시킬 것 | 필수 |
description |
Claude Code UI에 표시되는 설명 | 필수 |
author |
제작자 정보 | 선택 |
version |
버전 관리용 | 선택 |
entrypoint |
기본 진입점 파일 경로 | 필수 |
entrypoint에 지정한 파일이 Claude Code가 가장 먼저 읽는 파일이다. 여기에 이 플러그인이 무엇을 하는지 설명하고, 나머지 skills로 연결하는 구조가 일반적이다.
세 폴더의 역할 차이
skills/ — 자동 invoke되는 행동 정의
skills/ 폴더 안에 마크다운 파일(.md)을 넣으면, Claude Code가 대화 중 해당 skill이 필요하다고 판단할 때 자동으로 불러온다. 직접 호출하지 않아도 된다는 게 핵심이다.
skills/
├── main.md # 기본 진입점
├── summarize.md # 요약 관련 행동
└── review.md # 코드 리뷰 관련 행동
각 .md 파일 안에는 이 skill이 언제 사용되어야 하는지, 어떻게 동작해야 하는지를 자연어로 기술한다. Claude Code가 이 내용을 읽고 컨텍스트에 맞게 적용한다.
commands/ — /슬래시 명령어 매핑
commands/ 폴더는 사용자가 /명령어 형태로 직접 호출하는 기능을 담는다.
commands/
├── deploy.md # /deploy 명령어
└── test.md # /test 명령어
파일 이름이 곧 명령어 이름이 된다. deploy.md를 만들면 /deploy가 활성화된다. skills와 달리 명시적으로 호출해야 실행된다.
hooks/ — 이벤트 트리거
hooks/ 폴더는 Claude Code의 특정 이벤트에 반응하는 코드를 담는다. 예를 들어 Claude가 응답을 완료했을 때, 파일을 편집했을 때 등의 시점에 자동으로 실행된다.
hooks/
├── post-response.md # 응답 완료 후
└── pre-edit.md # 파일 편집 전
최소 구조로 첫 플러그인 만들기
이론보다 실제로 만들어보는 게 빠르다. 터미널 다섯 줄이면 된다.
# 플러그인 디렉토리 생성
mkdir -p ~/.claude/plugins/my-first-plugin/skills
# plugin.json 작성
cat > ~/.claude/plugins/my-first-plugin/plugin.json << 'EOF'
{
"name": "my-first-plugin",
"description": "첫 번째 Claude Code 플러그인",
"author": "seunghyeon",
"version": "0.1.0",
"entrypoint": "skills/main.md"
}
EOF
# 기본 skill 파일 작성
cat > ~/.claude/plugins/my-first-plugin/skills/main.md << 'EOF'
# 기본 Skill
이 플러그인은 개발 작업에서 코드 품질 점검을 도와준다.
사용자가 코드 리뷰나 품질 확인을 요청하면 이 skill을 적용한다.
EOF
Claude Code를 재시작하면 플러그인이 자동으로 로드된다. 별도의 설치 명령어가 없다.
# 로드 확인 — Claude Code 실행 후 확인
ls ~/.claude/plugins/my-first-plugin/
# 출력: plugin.json skills/
확장할 때 주의할 함정
파일 이름과 명령어 이름이 일치해야 한다. commands/ 폴더에서 파일 이름을 잘못 지으면 해당 명령어가 아예 노출되지 않는다. my-deploy.md로 만들면 /my-deploy가 된다.
entrypoint 경로는 plugin.json 기준 상대경로다. ~/.claude/plugins/my-plugin/skills/main.md에 파일이 있으면 entrypoint는 "skills/main.md"이지 절대경로가 아니다.
hooks는 무거운 작업에 쓰지 말 것. 응답마다 실행되는 hook에 무거운 처리를 넣으면 응답 속도가 눈에 띄게 느려진다. 로깅이나 간단한 알림 수준으로만 쓰는 게 안전하다.
마무리
plugin.json 선언 + skills/ 자동 invoke + commands/ 명시 호출 + hooks/ 이벤트 반응 — 이 네 가지가 Claude Code 플러그인의 전부다. 최소 구조는 파일 두 개면 충분하고, 필요할 때 폴더를 추가하며 확장하면 된다.
다음 글에서는 skills/ 파일 안에 실제로 무엇을 어떻게 쓰는지, 잘 동작하는 skill 파일과 그렇지 않은 것의 차이를 다룰 예정이다.
🐦 X에서 더 빠르게: @baegseungh7061
📚 이 시리즈 더 보기: Code 빌드
💌 새 글 알림: X 팔로우 또는 블로그 RSS 구독