Claude Code의 Command, Skills, Agents 그리고 Plugin 완벽 정리

Overview

Claude Code를 쓰다 보면 `/command`, Skill, Subagent, Plugin 이 네 가지 개념이 계속 등장한다. 이름도 비슷하고 하는 일도 겹쳐 보여서 처음엔 구분이 잘 안 된다. 특히 슬래시 커맨드와 스킬은 최근 통합되면서 더 헷갈린다.

 

이 글에서는 다음을 정리한다.

• Command, Skills, Agents가 각각 무엇이고 어떻게 다른가
• 같은 이름이 겹칠 때 어떤 게 우선되는가 (우선순위 규칙)
• Plugin으로 설치하면 기존 Skill과 어떻게 동작하는가

 

 

결론부터 말하면 이렇다. Command는 호출 단축키, Skill은 번들 가능한 프롬프트 능력, Agent는 격리된 컨텍스트를 가진 별도 인스턴스, Plugin은 이것들을 묶어서 배포하는 패키지다. 그리고 Plugin Skill은 네임스페이스로 격리되어 우선순위 경쟁 자체를 하지 않는다.

 

 

 

 

 

 

 

 

---

 

 

 

1. Slash Command (슬래시 커맨드)

슬래시 커맨드는 크게 두 종류로 나뉜다.

 

 

빌트인 커맨드

`/clear`, `/compact`, `/model`, `/cost`, `/help` 같은 명령어다. 이들은 Claude Code CLI에 하드코딩된 고정 로직이다. AI 추론이 들어가지 않고, 커스터마이징도 불가능하다. 그냥 /로 시작하는 CLI 단축키라고 보면 된다.

 

 

 

커스텀 커맨드

사용자가 직접 만드는 슬래시 커맨드다. 원래는 마크다운 파일 하나로 정의했다.

.claude/commands/review.md      # 프로젝트 전용
~/.claude/commands/review.md    # 모든 프로젝트에서 사용

호출은 `/review` 처럼 명시적으로 타이핑하는 방식이 핵심이다.

 

중요: 커스텀 슬래시 커맨드는 Skill로 통합되었다. `.claude/commands/` 디렉터리는 이제 레거시 포맷이고, 권장 포맷은 `.claude/skills/<name>/SKILL.md` 다. 기존 `.claude/commands/` 파일은 그대로 동작하지만, 신규 작성은 Skill로 하는 것이 맞다.

 

 

 

 

 

 

---

 

 

 

 

 

 

2. Skills

Skill은 프롬프트 기반 능력이다. 호출하면 정의된 지침(마크다운)이 컨텍스트에 로드되고 Claude가 그대로 실행한다. 슬래시 커맨드와 가장 큰 차이는 두 가지다.

 

 

 

차이 1 — 디렉터리 구조 (스크립트 번들 가능)

Skill은 파일 하나가 아니라 디렉터리로 정의한다. 이름은 디렉터리명으로 잡고, 실제 정의는 그 안의 SKILL.md에 둔다. 같은 디렉터리에 템플릿, 예제, 스크립트를 함께 번들할 수 있다.

.claude/skills/
└── helm-lint/
    ├── SKILL.md          # 스킬 정의 (필수)
    ├── templates/        # 함께 번들되는 리소스
    └── scripts/lint.sh   # 결정론적 코드도 포함 가능

 

 

SKILL.md의 프론트매터에서 동작을 제어한다.

---
name: helm-lint
description: Helm 차트 values와 템플릿을 검증한다. 차트 린트가 필요할 때 사용한다.
allowed-tools: Bash, Read       # 사용 가능 도구 제한 (선택)
model: claude-opus-4-8          # 사용할 모델 지정 (선택)
disable-model-invocation: true  # 자동 호출 끄기 (선택)
---

• name, description은 필수다. 특히 description은 Claude가 언제 이 스킬을 쓸지 판단하는 기준이라 가장 중요하다.

 

 

 

차이 2 — 자동 호출 + 컨텍스트 효율

Skill은 `/name` 으로 직접 호출할 수도 있고, description이 작업과 매칭되면 Claude가 알아서 invoke한다. 슬래시 커맨드가 주로 명시적 호출인 것과 대비된다.

 

또 progressive disclosure(점진적 공개) 방식으로 동작한다. 메타데이터 → SKILL.md 본문 → 리소스 순서로 필요할 때만 로드한다. 그래서 컨텍스트 효율이 매우 좋다. 5만 토큰짜리 참조 자료를 가진 스킬도 호출하지 않으면 100토큰, 본문만 쓰면 3천 토큰 수준만 소비한다. MCP 서버가 세션 시작 시 컨텍스트를 통째로 잡아먹는 것과 대조적이다.

 

한 가지 더 — Skill은 Claude Code뿐 아니라 Claude.ai 웹과 Claude Desktop에서도 동작한다. 한 번 정의하면 여러 환경에서 쓸 수 있다.

 

 

 

 

 

 

---

 

 

 

 

 

 

3. Subagent (Agents)

Subagent는 별도의 AI 인스턴스다. 가장 큰 특징은 독립된 컨텍스트 윈도우를 가진다는 점이다.

.claude/agents/
└── doc-researcher.md

 

 

메인 대화의 컨텍스트를 더럽히지 않고 작업을 위임할 수 있다. 문서 페칭, 대규모 코드베이스 탐색, 리서치처럼 토큰을 많이 먹지만 메인 흐름과 분리하고 싶은 작업에 적합하다. Claude가 자동으로 위임하거나 명시적으로 지정할 수 있다.

 

단, 제약이 하나 있다. Subagent는 다른 Subagent를 호출할 수 없다. 반면 Skill은 다른 Skill, MCP 서버, 그리고 Subagent까지 조합해서 쓸 수 있다.

 

 

 

 

 

 

4. 세 가지 비교 정리

구분	정의  형태	호출 방식	컨텍스트	대표 용도
Command	단일 md (.claude/commands/, 레거시)	주로 명시적 / 입력	메인 컨텍스트에서 실행	세션 제어, 단순 단축키
Skill	디렉터리 + SKILL.md (스크립트 번들)	명시적 / + 자동 호출	progressive disclosure, 효율적	반복 정형 작업, 도메인 지식 패키징
Subagent	.claude/agents/의 md	자동 위임 + 명시적	독립 컨텍스트로 격리	리서치, 탐색, 컨텍스트 보호

 

 

실무 관점 요약은 이렇다.

• 반복되는 정형 작업(매니페스트 검증, Helm 린트 워크플로우 등)은 스크립트 번들이 되는 Skill이 가장 유연하다.
• 토큰을 많이 먹는 조사·탐색 작업은 메인 컨텍스트를 지켜주는 Subagent가 낫다.
• 빌트인 슬래시 커맨드는 세션 제어용 단축키로만 쓴다.

 

 

 

 

 

 

 

 

 

---

 

 

 

 

 

5. 우선순위 (Precedence) 규칙

같은 이름이 여러 곳에 존재할 때 어떤 게 이기는지가 핵심이다.

 

 

 

Skill 레벨 간 우선순위

스킬이 여러 레벨에서 같은 이름을 가지면 다음 순서로 높은 쪽이 이긴다

Enterprise  >  Personal (~/.claude/skills/)  >  Project (.claude/skills/)
   (관리 설정)        (내 모든 프로젝트)              (이 저장소만)

• enterprise가 personal을 덮어쓰고, personal이 project를 덮어쓴다.

 

 

 

Skill vs Command

skill과 command가 같은 이름이면 skill이 우선한다. 예를 들어 `.claude/commands/review.md` 와 `.claude/skills/review/SKILL.md` 가 둘 다 있으면 skill 쪽이 쓰인다.

 

 

 

주의할 점 — 빌트인 충돌

Claude Code 업데이트로 같은 이름의 빌트인 스킬(`/review` 등)이 새로 추가되면, 빌트인이 우선권을 가져가서 기존 커스텀 스킬이 조용히 밀려나는 케이스가 보고된 적 있다. 커스텀 스킬 이름은 빌트인과 겹치지 않게 짓는 것이 안전하다.

 

 

 

 

 

 

---

 

 

 

 

 

6. Plugin — 충돌 없이 공존한다

Plugin은 Skill, Agent, Hook, MCP 서버를 하나로 묶어 배포하는 패키지다. 마켓플레이스를 추가하고 설치하는 방식으로 동작한다.

/plugin marketplace add <owner>/<repo>
/plugin install <plugin-name>@<marketplace>

 

 

여기서 가장 중요한 포인트가 있다.

Plugin Skill은 plugin-name:skill-name 네임스페이스를 쓰기 때문에 다른 레벨과 충돌할 수 없다.

 

 

즉 Plugin으로 설치한 스킬은 위의 Enterprise > Personal > Project 줄세우기 바깥에 따로 격리되어 들어온다. 내가 직접 만든 프로젝트/유저 스킬을 이름으로 덮어쓰지도 않고, 반대로 덮어쓰이지도 않는다. 우선순위 경쟁이 아니라 그냥 공존하는 구조다.

 

 

 

 

예시 — karpathy-guidelines 플러그인

 

# 마켓플레이스 추가 후 설치
/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

• 이 플러그인은 `karpathy-guidelines` 라는 스킬 하나를 담고 있다. 설치하면 `karpathy-skills:karpathy-guidelines` 형태로 격리되어 들어오므로, 기존에 쓰던 스킬·커맨드와 안 부딪힌다.

 

 

 

 

CLAUDE.md로 붙이는 경우는 메커니즘이 다르다

같은 내용을 Plugin이 아니라 `CLAUDE.md` 로 붙일 수도 있다. `CLAUDE.md` 는 lazy-load되는 스킬과 달리 항상 컨텍스트에 통째로 주입되는 지침이다. "어느 게 이긴다"보다 "여러 CLAUDE.md가 합쳐진다"에 가깝다.

 

다만 문제가 하나 있다. 마켓플레이스 플러그인 스킬이 직접 invoke될 때 플러그인의 SKILL.md가 우선권을 가져서, 프로젝트 `CLAUDE.md` 에 적어둔 패턴이 무시되는 경우가 보고된다. 이걸 깔끔하게 오버라이드하는 공식 문법(extends / overrides)은 아직 논의 단계다.

 

 

 

 

 

 

 

 

---

 

 

 

 

 

7. 정리 — 언제 무엇을 쓸까

상황	선택
세션 정리, 모델 변경 등 단순 제어	빌트인 Command
반복되는 정형 작업 + 스크립트 동반	Skill
자동 호출은 끄고 명시적으로만 쓰고 싶다	Skill + disable-model-invocation: true
토큰 많이 먹는 리서치/탐색, 컨텍스트 보호	Subagent
외부에서 만든 능력 묶음을 안전하게 가져오기	Plugin (네임스페이스 격리)
프로젝트 전반에 항상 적용할 코딩 원칙	CLAUDE.md 병합

 

핵심 한 줄: Skill은 내가 작성하는 것, Plugin은 설치하는 것이다. 그리고 Plugin Skill은 네임스페이스 덕분에 기존 설정과 충돌하지 않으니 안심하고 가져와도 된다.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

---

Reference

 

• Claude Code Overview: https://docs.claude.com/en/docs/claude-code/overview
• Extend Claude with skills: https://code.claude.com/docs/en/skills
• Slash Commands (SDK): https://code.claude.com/docs/en/agent-sdk/slash-commands
• Claude Code Docs Map: https://docs.anthropic.com/en/docs/claude-code/claude_code_docs_map.md
• andrej-karpathy-skills: https://github.com/multica-ai/andrej-karpathy-skills

 

 

 

 

 

 

Somaz | DevOps Engineer | Kubernetes & Cloud Infrastructure Specialist