클로드 코드(Claude Code) 내장 스킬 & 커맨드 완벽 총정리

실무 치트시트부터 SKILL.md, 직접 테스트 후기까지 한 번에 정리

브라우저에서 프롬프트를 복사해 붙여 넣는 방식만으로는 이제 한계가 분명합니다. 중요한 것은 AI에게 한 번 잘 물어보는 능력이 아니라, 내 작업 흐름 안에서 같은 방식으로 반복 실행되게 만드는 구조입니다. Claude Code가 주목받는 이유도 여기에 있습니다. 이 도구는 단순한 코드 추천기를 넘어, 파일을 읽고 수정하고, 작업을 나누고, 반복 흐름을 관리하는 쪽으로 설계돼 있습니다. 그래서 겉으로는 비슷해 보여도, 일반적인 채팅형 AI와는 결이 다릅니다.

이 지점에서 많은 분들이 바로 막힙니다. /clear, /compact 같은 것과 /batch, /simplify, /loop 같은 것이 모두 슬래시(/)로 시작하다 보니, 대체 무엇이 커맨드이고 무엇이 스킬인지 헷갈리기 때문입니다. 게다가 SKILL.md 파일 하나 만든다고 실제로 어떤 차이가 생기는지도 직관적으로 와닿지 않습니다. 이 글은 그 혼선을 정리하기 위해 썼습니다.

이 글의 핵심은 Claude Code를 “명령어 모음”으로 보는 데서 멈추지 않고, 반복 가능한 작업 규칙의 관점에서 이해하는 데 있습니다.

단순 소개가 아니라, 클로드 스킬과 클로드 커맨드의 차이, 실무에서 자주 쓰이는 패턴, SKILL.md의 구조, 그리고 직접 테스트해본 결과까지 하나의 흐름으로 정리했습니다. 끝까지 읽으시면 “무엇이 되는가”보다 “왜 이 구조가 실무에서 유의미한가”가 더 분명해지실 겁니다.

도입부: 터미널로 들어온 AI, 워크플로우의 판도가 바뀌다

Claude Code를 기존 AI 코딩 도구와 다르게 봐야 하는 이유는, 이 도구가 단순히 답을 생성하는 인터페이스가 아니라 작업을 수행하는 단위에 더 가깝기 때문입니다. 공식 문서만 보더라도 built-in commands, bundled skills, supporting files, invocation control, subagent execution, dynamic context injection 같은 개념이 함께 등장합니다. 다시 말해, “질문하면 답하는 AI”라기보다 “정해진 작업 방식을 따라 움직이는 에이전트”에 가까운 구조입니다.

이 변화는 단순한 기능 추가가 아닙니다. 이전에는 좋은 프롬프트를 한 번 잘 쓰는 사람이 유리했다면, 이제는 작업 방식을 잘 설계해 반복 가능하게 만드는 사람이 더 유리합니다. 결국 생산성 차이는 모델 자체의 성능보다, 그 모델을 어떤 구조 안에서 굴리느냐에서 더 크게 벌어집니다. Claude Code의 스킬 시스템은 바로 이 지점을 담당합니다.

그래서 Claude Code를 잘 쓴다는 말은 명령어를 많이 외운다는 뜻이 아니라, 작업을 어떻게 모듈화할지 이해하고 있다는 뜻에 더 가깝습니다.

이 관점이 잡히면 커맨드와 스킬의 구분도 훨씬 자연스럽게 정리됩니다.

1. 가장 헷갈리는 개념: 스킬(Skill) vs 커맨드(Command)

한눈에 보면 비슷하지만, 구조는 다릅니다

처음 보면 둘은 거의 같은 것처럼 보입니다. 둘 다 /로 시작하고, 둘 다 터미널 안에서 호출되며, 둘 다 Claude의 동작을 바꾸는 것처럼 느껴지기 때문입니다. 하지만 공식 문서 기준으로 보면 구조는 꽤 다릅니다. built-in commands는 고정 로직을 직접 실행하는 기능이고, bundled skills는 SKILL.md를 기반으로 Claude가 작업 절차를 읽고 실행하게 만드는 프롬프트형 플레이북입니다.

쉽게 비유하면 이렇습니다. 커맨드는 버튼에 가깝고, 스킬은 작업 매뉴얼에 가깝습니다. /clear를 누르면 대화가 정리되고, /compact를 실행하면 컨텍스트가 압축됩니다. 반면 /batch, /simplify, /loop는 단순히 하나의 동작을 실행하는 것이 아니라, Claude에게 “이 상황에서는 이런 절차로 움직여라”라고 지시하는 구조입니다.

즉, 커맨드는 기능이고 스킬은 방식입니다.

이 차이를 이해하면, 왜 Anthropic이 일부 기능은 하드코딩하고 일부는 SKILL.md로 열어뒀는지도 자연스럽게 보이기 시작합니다.

비교 요약

2. 먼저 개념부터: CLI, slash command, flag, MCP는 무엇인가

Claude Code를 처음 보면 명령어가 많은 것보다, 서로 다른 층위의 개념이 한꺼번에 나온다는 점이 더 어렵게 느껴집니다. 터미널에서 claude라고 입력해 실행하는 CLI가 있고, Claude Code 안에서 /clear, /init처럼 쓰는 slash command가 있으며, /batch, /simplify처럼 프롬프트 기반으로 움직이는 스킬도 따로 있습니다. 여기에 -p, --model, --output-format json 같은 플래그까지 붙기 시작하면 처음 접하는 사람 입장에서는 “무슨 명령이 어디서 실행되는지”부터 헷갈리기 쉽습니다.

그래서 이 글에서는 먼저 구조부터 정리하고 넘어가겠습니다. 아주 단순하게 말하면, CLI는 Claude Code를 여는 바깥 명령, slash command는 세션 안에서 쓰는 내부 명령, 스킬은 반복 업무를 실행 절차로 묶어둔 작업 플레이북, MCP는 Claude를 외부 도구와 연결하는 표준 인터페이스입니다. 이 네 가지를 구분할 수 있으면, 이후에 나오는 전체 명령어 목록도 훨씬 덜 복잡하게 읽힙니다.

CLI는 무엇인가

CLI는 Command Line Interface의 줄임말입니다. 쉽게 말하면 마우스로 버튼을 누르는 대신, 터미널에 텍스트 명령어를 입력해 프로그램을 실행하고 제어하는 방식입니다. Claude Code도 기본적으로는 이 방식으로 시작합니다. claude라고 입력하면 인터랙티브 세션이 열리고, claude -p "query"처럼 입력하면 결과만 출력한 뒤 종료할 수 있습니다. 즉, CLI는 Claude Code의 바깥쪽 실행 인터페이스라고 이해하시면 됩니다.

커맨드는 무엇인가

커맨드는 말 그대로 명령입니다. 다만 Claude Code에서는 이 말이 두 층위로 쓰입니다. 하나는 터미널에서 실행하는 CLI 명령이고, 다른 하나는 Claude Code 세션 안에서 쓰는 slash command입니다. 예를 들어 claude update는 CLI 명령이고, /clear는 세션 내부 명령입니다. 즉, 같은 “명령”이지만 밖에서 여는 명령과 안에서 조작하는 명령이 나뉘어 있다고 보시면 됩니다.

플래그는 무엇인가

플래그는 명령어에 붙는 옵션입니다. 커맨드가 “무엇을 할지”를 정한다면, 플래그는 “어떤 방식으로 할지”를 조정합니다. 예를 들어 claude는 기본 실행이고, claude -p는 결과만 출력하는 print 모드이며, claude -c는 최근 세션을 이어받는 옵션입니다. 즉, 플래그는 명령의 세부 실행 방식을 바꾸는 설정값입니다.

slash command는 무엇인가

slash command는 /로 시작하는 명령어입니다. Claude Code 세션 안에서 입력하며, 현재 작업 흐름을 빠르게 조정하는 데 씁니다. /help, /status, /init, /clear, /compact 같은 것들이 여기에 해당합니다. 다시 말해, slash command는 Claude Code의 내부 조작용 명령어입니다.

스킬은 무엇인가

스킬은 단순 기능이라기보다 작업 플레이북에 가깝습니다. built-in command가 버튼처럼 정해진 기능을 바로 실행한다면, 스킬은 Claude에게 “이 상황에서는 이런 절차로 일하라”는 규칙을 읽히는 구조입니다. 그래서 /simplify, /batch 같은 스킬은 단순 명령이 아니라, 반복 업무를 재사용 가능한 방식으로 실행하게 만드는 프롬프트 기반 작업 규칙에 가깝습니다.

MCP는 무엇인가

MCP는 Model Context Protocol의 줄임말입니다. 쉽게 말하면 Claude가 외부 도구나 시스템과 연결될 때 쓰는 표준 인터페이스입니다. GitHub, 외부 API, 브라우저, 사내 도구 등을 Claude와 연결하는 층위라고 보면 됩니다. 즉, 스킬이 “어떻게 일할지”를 정하는 구조라면, MCP는 “무엇과 연결할지”를 정하는 구조입니다.

3. Claude Code built-in 커맨드·CLI·플래그 총정리

이제 구조를 잡았으니, 실제로 Claude Code에서 어떤 명령을 어디에 쓰는지 전체 그림을 보겠습니다. 이 섹션은 “처음 시작하는 사람도 한 번에 구조를 잡을 수 있는 레퍼런스” 역할을 합니다. 아래 목록은 단순히 이름만 나열하는 것이 아니라, 어떤 상황에서 왜 쓰는지까지 함께 설명하는 방식으로 정리했습니다.

3-1. built-in slash commands: Claude Code 안에서 쓰는 명령

/add-dir <path>

현재 세션에 추가 작업 디렉터리를 붙입니다. 여러 폴더를 동시에 다뤄야 할 때 유용하지만, 추가 디렉터리의 .claude/ 설정까지 자동으로 다 불러오는 개념은 아닙니다. 즉, 작업 범위를 넓히는 명령으로 이해하는 편이 정확합니다.

/clear

현재 대화 히스토리를 비우고 새 흐름으로 넘어갑니다. 작업 주제가 완전히 바뀌었을 때 가장 안전한 초기화 방법입니다. 이전 맥락이 남아 있으면 Claude가 엉뚱한 컨텍스트를 계속 끌고 갈 수 있기 때문에, 생각보다 자주 쓰게 됩니다.

/compact [instructions]

세션을 압축해 컨텍스트를 줄입니다. 긴 대화를 계속 끌고 가면 토큰 낭비도 생기고, 답변이 산만해질 수 있는데 이때 가장 실무적으로 많이 쓰는 명령입니다. 필요하면 “테스트 관련 내용 위주로 남겨줘”처럼 압축 방향도 함께 줄 수 있습니다.

/context

현재 컨텍스트 사용량을 보여줍니다. Claude가 왜 갑자기 무거워지는지, memory나 tool output이 얼마나 쌓였는지 감을 잡게 해주는 진단용 명령입니다.

/copy [N]

최근 응답을 클립보드로 복사합니다. 긴 코드 블록이나 설명을 따로 옮겨 적어야 할 때 편합니다.

/diff

현재 git diff와 Claude가 각 턴에서 만든 변경을 비교해 보여줍니다. 즉, “Claude가 실제로 무슨 변경을 했는지”를 검수하기 좋은 명령입니다.

/exit

세션을 종료합니다. /quit와 같은 역할입니다.

/export [filename]

현재 대화를 텍스트로 내보냅니다. 세션 기록을 남기거나 팀과 공유할 때 유용합니다.

/branch [name]

현재 대화 시점에서 흐름을 분기합니다. 코드 브랜치라기보다, 작업 방향을 갈라서 다른 시도를 해보는 세션 분기에 가깝습니다.

/rename [name]

현재 세션 이름을 바꿉니다. 세션이 많아질수록 /resume과 함께 중요해집니다.

/resume [session]

이전 세션을 다시 엽니다. 세션 ID나 이름으로 재개할 수 있어서, 기능별로 세션을 나눠두면 꽤 강력합니다.

/rewind

이전 체크포인트나 메시지 시점으로 되돌립니다. “방금 시도 자체를 없던 것으로 돌리고 싶다”는 상황에서 가장 강력한 복구 수단입니다.

/tasks

백그라운드 작업을 관리합니다. Claude가 뒤에서 어떤 작업을 돌리고 있는지 보는 창구로 이해하시면 됩니다.

/help

사용 가능한 명령과 도움말을 보여줍니다. 처음 시작하는 사람이 가장 먼저 쳐봐야 하는 명령입니다.

/powerup

Claude Code 기능을 빠르게 익힐 수 있는 레슨이나 데모 형태의 안내를 제공합니다. 온보딩 성격의 명령입니다.

/init

프로젝트를 CLAUDE.md와 함께 초기화합니다. Claude Code를 프로젝트 단위로 제대로 쓰려면 가장 먼저 익혀야 할 명령 중 하나입니다.

/insights

세션 사용 기록과 상호작용 패턴을 분석해 보여줍니다. 단순 통계라기보다, “내가 Claude Code를 어떻게 쓰고 있는지”를 메타적으로 보여주는 리포트에 가깝습니다.

/config

설정 인터페이스를 엽니다. 테마, 모델, output style 등 다양한 환경설정을 조정하는 기본 진입점입니다.

/status

현재 버전, 계정, 모델, 연결 상태 등을 보여줍니다. 무언가 이상하게 느껴질 때 가장 먼저 확인하는 명령 중 하나입니다.

/model [model]

현재 모델을 확인하거나 변경합니다. 품질·속도·비용 균형을 조정하는 데 중요합니다.

/effort [low|medium|high|max|auto]

모델의 effort level을 조정합니다. 단순한 품질 버튼이 아니라, Claude가 얼마나 깊게 생각할지를 정하는 제어 장치입니다.

/fast [on|off]

fast mode를 켜거나 끕니다. 품질보다 응답 속도가 중요한 상황에서 의미가 있습니다.

/theme

테마를 바꿉니다. 라이트/다크 같은 UI 개인화 기능입니다.

/color [color|default]

프롬프트 바 색상을 바꿉니다. 세션을 여러 개 돌릴 때 시각적으로 구분하는 데 도움됩니다.

/statusline

상태 표시줄을 설정합니다. 자주 보는 정보를 자신에게 맞게 튜닝할 수 있습니다.

/keybindings

키바인딩 설정 파일을 열거나 생성합니다. 터미널 입력 방식에 익숙한 사용자에게 유용합니다.

/terminal-setup

특정 터미널 환경에서 줄바꿈이나 키 입력 세팅을 도와줍니다. 입력 UX를 다듬는 보조 기능으로 보시면 됩니다.

/login, /logout

Anthropic 계정 로그인/로그아웃입니다.

/usage

플랜 사용량과 rate limit 상태를 보여줍니다. “왜 갑자기 제한이 걸리지?”를 확인할 때 먼저 봐야 합니다.

/cost

토큰 사용량 통계를 보여줍니다. 세션 비용 감각을 잡는 데 직접적입니다.

/extra-usage

기본 한도를 넘겼을 때 extra usage를 설정하는 기능입니다. 과금과 직결되므로 의미를 이해하고 써야 합니다.

/passes, /upgrade, /privacy-settings

공유 패스, 플랜 업그레이드, 개인정보 설정 관련 명령입니다. 실무 코딩 흐름보다는 계정 관리에 가깝습니다.

/stats

일일 사용량, 세션 기록, 선호 모델 같은 통계를 시각화합니다.

/memory

CLAUDE.md와 auto-memory를 관리합니다. Claude Code 품질은 결국 memory 설계에 크게 좌우되기 때문에 중요도가 높습니다.

/permissions

allow/ask/deny 규칙을 관리합니다. Claude에게 어디까지 자동 권한을 줄지 정하는 핵심 명령입니다.

/hooks

도구 이벤트에 연결된 hook 구성을 봅니다. 자동화 흐름을 설계할 때 중요합니다.

/sandbox

sandbox mode를 켜거나 끕니다. 보안 민감도가 높은 환경에서 의미가 큽니다.

/doctor

설치 및 설정 상태를 진단합니다. 뭔가 이상할 때 가장 먼저 써봐야 하는 명령입니다.

/feedback [report]

피드백이나 버그 리포트를 보냅니다.

/agents

agent 구성을 관리합니다. Claude를 역할별 subagent로 나눠 쓰는 구조의 입구입니다.

/mcp

MCP 서버 연결과 OAuth 인증을 관리합니다. 외부 도구와의 연결 제어판에 가깝습니다.

/plugin, /reload-plugins

플러그인 관리와 재로드입니다. 플러그인 변경을 재시작 없이 반영할 수 있다는 점이 중요합니다.

/ide

IDE 연동 상태를 관리합니다.

/chrome, /desktop, /mobile, /remote-control, /remote-env, /voice

브라우저, 데스크톱 앱, 모바일 앱, 원격 제어, 원격 환경, 음성 입력과 관련된 명령입니다. Claude Code를 다른 인터페이스와 연결하는 계층이라고 보면 됩니다.

/install-github-app, /install-slack-app

GitHub나 Slack 연동 앱 설치를 돕는 온보딩 명령입니다.

/plan [description]

바로 plan mode로 들어갑니다. Claude를 곧바로 수정 도구로 쓰기보다, 먼저 설계와 계획을 세우는 모드로 전환할 때 중요합니다.

/security-review

현재 브랜치의 변경사항을 보안 관점에서 리뷰합니다. 일반 코드 리뷰가 아니라, 인증·권한·노출·주입 같은 위험에 초점을 둔 리뷰입니다.

/schedule [description]

스케줄 작업을 생성·수정·조회·실행합니다. 일정 기반 자동화를 관리하는 명령입니다.

/ultraplan <prompt>

브라우저에서 검토할 수 있는 깊은 계획 세션을 따로 만듭니다. 일반 plan보다 더 무거운 설계 흐름으로 이해하면 됩니다.

3-2. 번들 스킬: 버튼이 아니라 플레이북으로 움직이는 명령

클로드 코드 스킬 소개 공식문서 바로가기

/batch <instruction>

큰 변경 작업을 병렬화하는 스킬입니다. Claude가 먼저 코드베이스를 살펴보고, 작업을 독립 단위로 쪼개고, 승인 후 각 단위를 별도 worktree에서 background agent가 수행하도록 움직입니다. 즉, 단순 일괄 수정이 아니라 분해 → 계획 → 병렬 실행 → 테스트/검증 흐름으로 작동합니다.

/claude-api

프로젝트 언어에 맞는 Claude API 레퍼런스를 로드하는 스킬입니다. 직접 뭔가를 실행한다기보다, 현재 코드베이스에 필요한 API 문맥을 먼저 붙여주는 reference skill에 가깝습니다.

/debug [description]

세션 중간부터 디버그 로그 수집을 켜고, 그 로그를 바탕으로 문제를 분석합니다. description을 주면 Claude가 어떤 문제에 초점을 맞출지 방향을 잡을 수 있습니다.

/loop [interval] <prompt>

정해진 간격으로 같은 프롬프트를 반복 실행합니다. 배포 모니터링, PR 상태 확인, 주기적 체크 같은 반복성 작업에 맞습니다.

/simplify [focus]

최근 변경 파일을 검토해 코드 재사용성, 품질, 효율성 문제를 찾고 수정합니다. Claude가 여러 리뷰 관점을 병렬로 돌리고 결과를 합쳐 후처리하는 구조라서, 초안 작성보다는 마지막 품질 정리 패스에 더 잘 맞습니다.

3-3. Claude Code CLI commands: 터미널에서 Claude Code를 실행·재개·관리하는 명령

claude

인터랙티브 세션을 시작합니다. 가장 기본적인 진입점입니다.

claude "query"

첫 질문을 포함해 세션을 시작합니다. 시작과 동시에 작업 방향을 던지고 싶을 때 편합니다.

claude -p "query"

print 모드로 결과만 출력하고 종료합니다. 자동화, 셸 스크립트, CI 연결에 핵심입니다.

cat file | claude -p "query"

파이프로 입력을 넘겨 파일이나 로그를 직접 처리할 수 있습니다.

claude -c

현재 디렉터리의 최근 세션을 이어갑니다. 어제 하던 작업을 그대로 다시 여는 가장 쉬운 방법입니다.

claude -c -p "query"

최근 세션의 맥락은 재사용하되, 비대화형으로 한 번만 실행하고 싶을 때 씁니다.

claude -r "<session>" "query"

세션 ID나 이름으로 특정 세션을 재개합니다.

claude update

최신 버전으로 업데이트합니다.

claude auth login

Anthropic 계정에 로그인합니다.

claude auth logout

로그아웃합니다.

claude auth status

인증 상태를 확인합니다. JSON 또는 텍스트 출력이 가능해 자동화 스크립트에도 유용합니다.

claude agents

subagent 구성을 보여줍니다.

claude auto-mode defaults

auto mode classifier 규칙을 JSON으로 출력합니다.

claude mcp

MCP 서버를 설정합니다.

claude plugin / claude plugins

플러그인을 관리합니다.

claude remote-control

Remote Control 서버를 시작해 다른 인터페이스에서 로컬 Claude Code 세션을 제어할 수 있게 합니다.

3-4. CLI flags: 명령의 실행 방식을 바꾸는 옵션

이 부분은 너무 길게 늘어놓기보다, 역할별로 묶어 설명하는 편이 초보자에게 더 친절합니다.

세션/작업 범위 관련 플래그

• -add-dir, -continue(-c), -resume(-r), -fork-session, -session-id, -name(-n), -from-pr, -worktree(-w), -tmux, -teammate-mode

이 그룹은 “어디서 어떤 세션을, 얼마나 분리해서 이어갈 것인가”를 정합니다.

출력/비대화형 실행 관련 플래그

• -print(-p), -input-format, -output-format, -json-schema, -include-hook-events, -include-partial-messages, -replay-user-messages, -max-turns, -max-budget-usd, -no-session-persistence

이 그룹은 Claude Code를 자동화 파이프라인에 넣을 때 중요합니다.

모델/품질/시스템 프롬프트 관련 플래그

• -model, -fallback-model, -effort, -append-system-prompt, -append-system-prompt-file, -system-prompt, -system-prompt-file

이 그룹은 어떤 모델로 얼마나 깊게 생각하게 할지, 어떤 운영 규칙을 깔고 시작할지를 정합니다.

권한/도구 관련 플래그

• -allowedTools, -disallowedTools, -tools, -permission-mode, -permission-prompt-tool, -allow-dangerously-skip-permissions, -dangerously-skip-permissions

이 그룹은 Claude에게 어느 도구를 어디까지 자동 허용할지 정하는 보안 관련 옵션입니다.

확장/외부 연결 관련 플래그

• -mcp-config, -strict-mcp-config, -plugin-dir, -chrome, -no-chrome, -channels, -dangerously-load-development-channels, -ide, -remote, -remote-control, -rc, -remote-control-session-name-prefix, -teleport

이 그룹은 MCP, 플러그인, 브라우저, 원격 제어 같은 확장 기능과 연결됩니다.

디버그/운영 관련 플래그

• -debug, -debug-file, -verbose, -version(-v), -init, -init-only, -maintenance, -settings, -setting-sources, -bare, -disable-slash-commands

문제가 생겼을 때 상태를 진단하고, 최소 모드로 줄여서 원인을 분리하는 데 유용합니다.

4. [인사이트] 앤스로픽은 왜 핵심 스킬을 ‘코드’가 아닌 ‘프롬프트’로 만들었을까?

이 지점이 가장 흥미롭습니다. 왜 Anthropic은 /clear 같은 것은 하드코딩하고, /simplify 같은 것은 SKILL.md 기반으로 열어뒀을까요. 단순히 구현 편의의 문제가 아니라, 기능의 성격이 다르기 때문입니다. 공식 문서의 표현을 따라가면 built-in commands는 fixed logic directly, bundled skills는 prompt-based입니다.

즉, 어떤 것은 버튼처럼 확정된 동작이어야 하고, 어떤 것은 상황에 따라 적응하는 플레이북이어야 합니다. 하드코딩된 기능은 빠르고 예측 가능하지만 닫혀 있습니다. 반대로 프롬프트 기반 기능은 모델 추론을 타지만, 훨씬 유연하고 수정 가능하며 재사용 구조를 만들기 쉽습니다. 실무에서는 오히려 후자가 더 큰 가치를 갖는 경우가 많습니다.

스킬의 강점은 Claude에게 없던 기능을 만들어내는 데 있지 않고, 사람이 가진 작업 노하우를 파일 형태로 남길 수 있다는 데 있습니다.

이게 중요한 이유는 명확합니다. 배포 전 체크 방식, 코드 설명 방식, 문서화 포맷, 리뷰 기준처럼 팀마다 자주 반복되지만 사람마다 조금씩 다르게 처리하는 업무가 있기 때문입니다. 이런 작업을 코드로 박아넣기엔 무겁고, 매번 프롬프트로 쓰기엔 불안정합니다. 스킬은 그 중간을 차지합니다.

또 하나 중요한 점은 supporting files를 붙일 수 있다는 것입니다. SKILL.md만 덩그러니 있는 구조가 아니라, 같은 디렉터리 안에 예시 파일이나 참고 문서, 스크립트를 함께 둘 수 있습니다. 이 말은 곧 스킬이 단순 프롬프트가 아니라, 가벼운 작업 시스템으로 확장될 수 있다는 뜻입니다. 그래서 Anthropic이 스킬을 프롬프트 기반으로 설계한 것은 임시방편이 아니라, 오히려 더 높은 수준의 추상화라고 보는 편이 맞습니다.

5. 나만의 커스텀 스킬 만들기 (심화)

커스텀 스킬의 시작은 생각보다 단순합니다. 디렉터리 하나를 만들고, 그 안에 SKILL.md 파일을 두면 됩니다. 이 파일 안에는 YAML frontmatter와 markdown instructions가 들어갑니다. 구조만 놓고 보면 복잡하지 않지만, 실제로 중요한 것은 파일을 만드는 것보다 무엇을 어떻게 적느냐입니다.

공식 예시에서는 name이 슬래시 커맨드 이름이 되고, description이 Claude가 언제 이 스킬을 자동으로 사용할지 판단하는 기준이 됩니다. 즉, description은 소개 문구가 아니라 트리거 역할을 합니다. 여기에 instructions가 결합되면, Claude는 “어떤 상황에서 이 스킬을 꺼내고, 어떤 방식으로 결과를 만들어야 하는지”를 함께 이해하게 됩니다.

예를 들어 코드 설명용 스킬이라면, name: explain-code처럼 이름을 정하고, description에는 “코드 작동 방식을 설명하거나, 코드베이스를 가르치거나, 사용자가 ‘이게 어떻게 동작하나요?’라고 묻는 상황” 같은 트리거를 적을 수 있습니다. 그 아래에는 비유를 넣고, 다이어그램을 그리고, 단계별로 설명하고, 주의할 함정을 짚으라는 식의 지시문이 이어집니다. 결국 스킬은 기능이 아니라 반복 가능한 설명 방식 자체를 정의하는 문서라고 보는 편이 정확합니다.

공식 문서 기준으로 알아둘 구성 포인트

아래 요소들은 실제로 스킬을 쓸 때 꽤 중요합니다.

• 스킬 저장 위치
  personal, project, enterprise, plugin 범위로 둘 수 있습니다. 팀이 함께 쓸 규칙이라면 프로젝트 단위가 더 적합합니다.
• supporting files 사용 가능
  SKILL.md 외에 예시 파일, 참고 문서, 스크립트 등을 함께 둘 수 있습니다. 본문은 짧게 유지하고, 상세 자료는 분리하는 편이 좋습니다.
• invocation control 제공
  자동 호출만 허용하거나, 반대로 사용자의 직접 호출만 허용하는 식으로 제어할 수 있습니다. 배포나 외부 전송처럼 부작용이 있는 작업에서는 특히 중요합니다.
• allowed-tools 설정 가능
  읽기 전용, 특정 도구만 사용 가능하도록 제한할 수 있습니다. 안전장치 역할을 합니다.
• arguments와 string substitution 지원
  인자를 받아 파라미터화된 스킬로 만들 수 있습니다. 이 기능이 들어가면 단순 템플릿을 넘어 작은 작업 단위처럼 쓸 수 있습니다.

결국 잘 만든 스킬은 길고 복잡한 스킬이 아니라, 언제 쓰는지와 어떻게 움직이는지가 분명한 스킬입니다.

이 원칙이 뒤의 직접 테스트 결과와도 연결됩니다.

6. 직접 테스트해보니: 스킬은 “새 기능”이라기보다 “잘하는 방식을 고정하는 장치”였습니다

문서만 읽으면 스킬은 꽤 그럴듯해 보입니다. 하지만 실제로는 누구나 같은 의문을 가집니다. 정말 발동하는지, 그냥 프롬프트를 잘 쓰는 것과 무엇이 다른지, 그리고 작동한다고 해서 실무적으로 무슨 이점이 있는지 궁금해집니다. 저도 그 부분이 가장 궁금해서, 공식 문서 예제를 거의 그대로 따라 explain-code 스킬을 직접 만들어 테스트해봤습니다.

공식 문서의 흐름대로 ~/.claude/skills/explain-code 디렉터리를 만들고, 그 안에 SKILL.md를 작성했습니다. name: explain-code, 그리고 “비유와 ASCII 다이어그램을 활용해 코드를 설명하라”는 취지의 description과 instructions를 넣는 방식입니다. 실제 터미널에서도 해당 디렉터리와 파일이 정상적으로 생성된 것을 확인할 수 있었습니다. 즉, 최소한 문서에서 설명한 기본 구조는 그대로 재현됐습니다.

그 다음에는 공식 문서의 Test the skill 섹션을 따라 테스트를 진행했습니다. 문서에 따르면 테스트 방법은 두 가지입니다. 하나는 “How does this code work?”처럼 설명과 맞는 자연어 요청을 던져 자동 발동을 유도하는 방식이고, 다른 하나는 /explain-code src/auth/login.ts처럼 스킬 이름으로 직접 호출하는 방식입니다. 여기서 더 중요한 기준이 하나 있습니다. 공식 문서는 어느 방식이든 결과에 비유(analogy)와 ASCII 다이어그램이 포함되어야 한다고 안내합니다.

(출처 : Anthropic, 2026)

직접 테스트해본 결과를 이 기준에 맞춰 보면, 스킬은 정상적으로 작동한 것으로 판단하는 것이 맞습니다. 실제 출력에는 코드 설명에 들어가기 전 비유가 제시됐고, 구조를 풀어주는 ASCII 다이어그램도 함께 포함됐습니다. 이후에는 단계별로 흐름을 설명하는 방식까지 이어졌습니다. 즉, 문서가 제시한 두 가지 핵심 요소가 모두 나타났기 때문에, 작동 여부만 놓고 보면 충분히 통과라고 볼 수 있습니다.

그런데 여기서 정말 중요한 건 “작동했다”는 사실 자체가 아닙니다. 솔직히 그 결과만 놓고 보면, “원래 Claude가 코드 설명은 잘하는데?”라는 반응이 나오는 것도 자연스럽습니다. 맞습니다. 이번 테스트의 진짜 의미는 Claude가 코드를 설명할 수 있다는 점이 아니라, Claude가 원래 할 수 있는 일을 내가 원하는 형식으로 반복 가능하게 고정했다는 점에 있습니다.

이 차이는 생각보다 큽니다. 그냥 프롬프트로 “비유도 넣고, ASCII 다이어그램도 그리고, 단계별 설명도 해주세요”라고 매번 써도 한 번은 잘 됩니다. 하지만 두 번째, 세 번째부터는 사람마다 요구가 달라지고 결과 형식도 흔들리기 시작합니다. 누군가는 비유를 빼먹고, 누군가는 다이어그램을 생략하고, 누군가는 설명 깊이가 들쭉날쭉해집니다. 스킬로 묶어두면 이 즉흥성이 줄어들고, 결과 형식이 하나의 프로토콜처럼 고정됩니다.

스킬의 실질적 가치는 Claude에게 새로운 능력을 주는 데 있지 않고, 이미 가능한 일을 같은 방식으로 다시 쓰게 만드는 데 있습니다.

이게 실무에서 중요한 이유도 분명합니다. 설명 방식, PR 리뷰 방식, 장애 분석 방식, 배포 체크 방식처럼 반복되는 업무를 사람의 기억과 감각에 맡기지 않고, 재사용 가능한 파일로 남길 수 있기 때문입니다.

다만 기대치는 정확히 잡아둘 필요가 있습니다. 스킬을 만든다고 모델 자체가 더 똑똑해지는 것은 아닙니다. 복잡한 추론 품질은 여전히 기본 모델 성능과 컨텍스트 품질에 크게 영향을 받습니다. 단발성 요청이라면 오히려 프롬프트 한 줄이 더 빠를 수도 있습니다. 그래서 스킬은 “능력 추가”라기보다 행동 패키징이라고 보는 편이 가장 정확합니다.

7. 커뮤니티 반응으로 본 스킬의 진짜 장점

직접 테스트를 해보면 스킬이 작동한다는 사실 자체는 금방 확인됩니다. 하지만 실무적으로 더 중요한 질문은 그다음입니다. “그래서 이게 왜 좋은가”, “그냥 프롬프트를 길게 쓰는 것과 무엇이 다른가”라는 질문이 남습니다. 이 지점은 실제 사용자 후기를 함께 볼 때 훨씬 선명해집니다.

후기들을 묶어보면, 사람들이 스킬을 높게 평가하는 이유는 의외로 단순합니다. 새로운 기능이 생겼기 때문이 아니라, AI와 일하는 방식을 더 안정적으로 반복할 수 있게 됐기 때문입니다. 특히 /simplify, /batch, 커스텀 스킬에 대한 반응은 서로 다른 이야기처럼 보여도 결국 같은 결론으로 모입니다. 스킬의 핵심 가치는 Claude가 더 많은 걸 하게 만드는 데 있지 않고, Claude가 어떻게 일할지를 고정할 수 있게 해준다는 데 있습니다.

1) 이미 작동하는 코드를 마지막 패스로 정리해준다는 후기

Reddit에서 /simplify를 거의 모든 작업의 마지막 패스로 돌린다는 후기 바로가기

/simplify에 대한 좋은 평가는 단순히 “코드를 짧게 줄여준다”는 의미가 아닙니다. 실제 후기에서 더 자주 강조되는 포인트는, 이미 돌아가는 코드를 한 번 더 정리하고, 불필요한 구조를 덜어내고, 유지보수하기 쉬운 방향으로 다듬어준다는 점입니다. 그래서 많은 사용자가 이 스킬을 기능 하나로 보기보다, AI가 만든 초안을 그대로 믿지 않도록 해주는 후처리 안전장치처럼 받아들입니다.

이 반응이 중요한 이유는 분명합니다. Claude가 처음 생성한 결과물은 대체로 “일단 돌아가게 만드는 초안”에 가깝고, 실제 품질은 그 이후 리팩토링과 정리 단계에서 갈립니다. /simplify는 바로 이 후반 작업을 루틴으로 고정해줍니다. 결국 이 스킬이 좋은 이유는 더 화려한 코드를 만들기 때문이 아니라, AI 코드에 사람이 다시 개입할 수 있는 품질 관리 레일을 하나 추가해주기 때문입니다.

2) 여러 Claude 세션을 돌리고 본인은 스펙과 칸반 관리에 집중했다는 후기

여러 Claude 세션을 동시에 운영하면서 스펙 작성과 관리에 집중했다는 후기 바로가기

/batch와 병렬 실행에 대한 좋은 평가는 “속도가 빨라진다”는 말로는 충분히 설명되지 않습니다. 실제 사용자 반응에서 더 인상적인 지점은, 작업 단위를 여러 개로 쪼개 동시에 돌리면서 본인의 역할이 직접 구현자에서 오케스트레이터로 바뀌었다는 점입니다. 다시 말해, 손으로 하나씩 구현하는 사람에서, 무엇을 먼저 할지 정하고 스펙을 정리하고 결과를 리뷰하는 사람으로 무게중심이 이동했다는 뜻입니다.

이건 단순한 생산성 향상보다 더 큰 변화입니다. AI가 여러 작업을 병렬로 처리하고 있으면, 사람은 자연스럽게 “다음 기능을 어떻게 자를지”, “무엇을 검토하고 승인할지”에 더 집중하게 됩니다. 그래서 /batch의 강점은 빠름 자체보다, 사람을 실행자보다 관리자·설계자 역할에 더 가깝게 옮겨 놓는 데 있다고 보는 편이 더 정확합니다. 이런 반응은 글에서 말한 “사용자가 오케스트레이터가 된다”는 포인트를 가장 설득력 있게 뒷받침해 줍니다.

3) 반복 지시를 커스텀 스킬로 묶으니 세션마다 시간이 절약됐다는 후기

배포 체크·테스트·PR 리뷰 등 반복 지시를 커스텀 스킬로 묶은 후기 바로가기

커스텀 스킬에 대한 평가에서 가장 자주 반복되는 문장은 “매번 처음부터 설명하지 않아도 된다”는 감각입니다. 배포 체크, 테스트 플로우, PR 리뷰처럼 반복되는 지시를 파일로 저장해두면, 긴 프롬프트를 계속 다시 타이핑할 필요가 없습니다. 이건 편의성의 문제가 아니라, 개인의 프롬프트 습관이 팀 차원의 재사용 가능한 플레이북으로 바뀌는 순간이라는 점에서 더 중요합니다.

실무에서는 좋은 프롬프트를 한 번 잘 쓰는 것보다, 그 프롬프트를 다음 세션에서도 같은 방식으로 다시 쓸 수 있느냐가 훨씬 중요합니다. 커스텀 스킬은 바로 그 반복 가능성을 만들어줍니다. 그래서 사용자들이 높게 평가하는 지점도 “Claude가 더 똑똑해졌다”가 아니라, 반복 지시를 운영 자산처럼 저장해둘 수 있게 됐다는 데 있습니다. 이게 스킬의 본질을 가장 잘 보여주는 후기라고 볼 수 있습니다.

정리

이 세 가지 후기를 묶어보면 결론은 비교적 분명합니다. /simplify는 AI가 만든 결과물을 그대로 믿지 않아도 되는 후처리 안전장치로 받아들여지고, /batch는 사용자를 구현자에서 오케스트레이터로 이동시키며, 커스텀 스킬은 반복되는 지시를 재사용 가능한 작업 플레이북으로 바꿔줍니다. 즉, 사람들이 스킬을 좋게 보는 이유는 새로운 기능이 많아서가 아니라, 일하는 방식을 더 안정적으로 반복할 수 있게 만들어주기 때문입니다.

결국 실제 후기들이 공통으로 말하는 핵심은 하나입니다. 스킬은 Claude가 무엇을 할 수 있느냐보다, Claude가 어떻게 일하게 만들 것이냐를 정리하는 도구에 가깝습니다.

8. 공식 문서 기준으로 꼭 알아야 하는 스킬 설계 팁

직접 테스트까지 해보면, 이제 관심사는 “어떻게 하면 더 잘 작동하게 만들 수 있나”로 넘어갑니다. 이때 중요한 건 스킬을 길게 쓰는 것이 아니라, Claude가 적절한 순간에 적절한 방식으로 불러오게 만드는 것입니다. 공식 문서 기준으로도 실제 문제의 상당수는 기능 부족이 아니라, 설명과 구조 설계가 모호해서 생깁니다.

description은 소개 문구가 아니라 트리거 문장입니다

description이 추상적이면 자동 호출이 잘 일어나지 않습니다. “문서를 도와줍니다” 같은 표현은 너무 넓어서 효과가 떨어집니다. 반대로 “PDF에서 텍스트와 표를 추출해야 할 때 사용”처럼 구체적으로 적으면 자동 발견 가능성이 높아집니다. 결국 description은 예쁜 소개 문구가 아니라, Claude가 언제 이 스킬을 꺼내야 하는지 판단하는 기준 문장입니다.

YAML이 깨지면 스킬은 생각보다 쉽게 무너집니다

앞뒤 ---가 닫히지 않았거나, 들여쓰기나 문법이 잘못됐거나, 파일 경로가 틀린 경우만으로도 스킬이 로드되지 않을 수 있습니다. 구조가 단순한 대신, 기본 문법에 더 민감하다고 보는 편이 좋습니다. 잘 안 될 때는 큰 이유를 찾기 전에 frontmatter부터 점검하는 것이 훨씬 빠릅니다.

SKILL.md는 짧고 분명할수록 좋습니다

공식 문서도 SKILL.md는 개요와 방향만 담고, 상세 자료는 supporting files로 분리하는 방식을 권장합니다. 본문 하나에 모든 정보를 몰아넣으면 오히려 읽기 어렵고 유지보수도 힘들어집니다. 특히 팀 단위로 쓰기 시작하면, 설명이 길어지는 것보다 구조가 분리되어 있는 편이 훨씬 안정적입니다.

nested directories도 실무적으로 유용합니다

모노레포처럼 구조가 큰 프로젝트에서는 패키지별로 .claude/skills/를 둘 수 있다는 점이 꽤 실용적입니다. 프론트엔드 설명용 스킬과 백엔드 배포용 스킬을 같은 루트에 섞어두지 않고 나눌 수 있기 때문입니다. 결국 스킬도 코드처럼, 어디에 어떤 책임으로 둘지가 중요해집니다.

9. 실무자가 알아둘 주의사항 및 에러 해결 포인트

Claude Code를 실제로 써보면, 막히는 지점은 대개 화려한 기능보다 기본 운영에서 나옵니다. 권한 요청이 반복되거나, 스킬이 발동하지 않거나, 검색이 어색하거나, 세션이 지나치게 무거워지는 식입니다. 이런 문제는 대부분 “더 좋은 모델”로 해결되지 않고, 사용 방식과 설정을 정리하는 쪽에서 풀립니다.

자주 부딪히는 포인트를 정리하면 아래와 같습니다.

권한 요청이 너무 많을 때

매번 승인만 누르고 있다면 /permissions를 먼저 확인하는 편이 낫습니다. 반복 승인 자체가 생산성을 깎습니다.

스킬이 안 발동할 때

description이 구체적인지, 파일 경로가 맞는지, YAML frontmatter가 유효한지부터 봐야 합니다. 대개는 이 세 군데에서 원인이 나옵니다.

검색 결과가 이상할 때

search 환경이나 ripgrep 관련 설정이 영향을 줄 수 있습니다. 환경 문제일 수도 있다는 점을 염두에 두는 것이 좋습니다.

세션이 너무 무거울 때

/compact를 적절히 사용하고, 큰 작업 단위 사이에서는 세션을 정리하는 편이 좋습니다. 거대한 빌드 디렉터리 같은 불필요한 맥락도 줄일수록 유리합니다.

Claude Code는 “좋은 답변”보다 “좋은 운영 방식”이 더 큰 차이를 만드는 도구입니다.

그래서 설치 직후보다, 며칠 써본 뒤의 사용 습관이 훨씬 중요해집니다.

결론: 프롬프트를 지배하는 자가 시스템을 지배합니다

Claude Code를 잘 쓴다는 것은 슬래시 커맨드를 많이 외운다는 뜻이 아닙니다. 진짜 중요한 것은 고정 기능은 커맨드로 처리하고, 반복되는 복잡한 업무는 스킬로 올리고, 필요한 경우 supporting files와 tool control까지 묶어 작업 방식을 시스템처럼 다루는 것입니다. Anthropic이 스킬을 코드가 아니라 SKILL.md로 만든 이유도 여기에 있습니다. 행동을 코드에 박아두는 대신, 설명 가능하고 수정 가능한 작업 규칙으로 끌어올린 것입니다.

직접 테스트해본 뒤 더 분명해진 점도 같습니다. 스킬은 Claude를 더 똑똑하게 만드는 기능이 아니라, Claude가 잘하는 방식을 다시 쓸 수 있게 만드는 장치입니다. 그리고 실무에서는 한 번 잘 되는 것보다, 다음에도 같은 방식으로 다시 되는 것이 훨씬 더 중요합니다. 이 차이를 이해하는 순간 Claude Code는 단순한 AI 코딩 도구가 아니라, 팀의 작업 규칙을 설계하는 인터페이스로 보이기 시작합니다.

결국 다음 단계에서 중요한 것은 툴을 더 많이 아는 것이 아니라, 우리 팀의 업무를 어떤 단위로 스킬화할 수 있는지 판단하는 것입니다.

이 관점이 잡히면 Claude Code는 “좋아 보이는 기능 모음”이 아니라, 실제 운영 가능한 워크플로우의 재료로 바뀝니다.

마무리: 다음 단계로 넘어가려면 ‘툴’이 아니라 ‘운영 기준’이 필요합니다

리트머스는 AI·바이브코딩 기반 개발을 단순히 “빠르게 만들어주는 외주”로 접근하지 않습니다. 실제 프로젝트에서는 속도만큼이나 작업 분리, 검수 기준, 권한 설계, 테스트 흐름, 문서화 방식이 중요하기 때문입니다. 특히 Claude Code 같은 도구는 한 번 잘 쓰는 것보다, 팀 단위로 재사용 가능한 프로세스로 정리했을 때 비로소 가치가 커집니다. 리트머스는 바로 이 지점, 즉 기능 구현을 넘어 운영 가능한 구조까지 함께 설계하는 외주개발 팀이라는 점에서 차별점이 있습니다.

그런데 여기서 한 가지가 더 남습니다. 스킬과 커맨드의 구조를 이해했다면, 다음에는 자연스럽게 이런 질문이 생깁니다. “AI 코딩을 도입하면 어디까지 자동화해도 안전한가?”, “반복되는 작업을 스킬로 묶을 수는 있겠지만, 그 결과물을 어떤 기준으로 검수해야 하는가?” 실제로 많은 팀이 이 다음 단계에서 막힙니다.

함께 읽으면 좋은 글!

바이브코딩 주의할 점? AI 코딩 현실과 프롬프트 예시까지 한 번에 정리

이 글은 AI 코딩이 생산성을 높이는 동시에 어떤 리스크를 키울 수 있는지, 그리고 자동화와 사람이 직접 잡아야 하는 구간을 어떤 기준으로 나눠야 하는지를 더 구체적으로 다룹니다. 지금 글에서 스킬과 커맨드의 구조를 이해하셨다면, 다음 단계에서는 “그래서 실제 운영 기준은 어떻게 세워야 하나”가 더 중요해지는데, 그 질문에 가장 자연스럽게 이어지는 글입니다.

결국 마지막에 남는 질문은 비슷합니다. 우리 팀은 어떤 수준까지 AI 코딩을 도입할 수 있는지, 그리고 그걸 MVP부터 운영까지 어떤 구조로 굴려야 하는지입니다. 바이브코딩 외주가 맞는지부터 함께 검토해드릴 테니, 무료 견적 상담을 통해 우리 프로젝트가 어디까지 가능한지 확인해 보셔도 좋습니다.