Vol. 05 - Claude Skill & Agent

안녕하세요. 제로백데브 프론트엔더 재균입니다.
두번째 Lab 포스팅으로 인사드립니다.

저희 제로백데브는 개발할때 AI를 적극적으로 활용하는데 그중에 claude를 주로 사용하여 개발을 하고 있습니다.
Claude Code를 쓰다 보면 자연스럽게 마주치는 질문이 있습니다.
"Skill을 만들라는데, 이건 Agent랑 뭐가 다른 거지?" 둘 다 Claude의 능력을 확장하는 도구지만, 작동 방식이 근본적으로 다릅니다. 이 차이를 이해하면 "언제 무엇을 써야 하는지"가 명확해집니다.

본격적으로 들어가기 전에 용어 하나만 짚고 가겠습니다. 이 글에서 계속 나올 컨텍스트는 Claude가 한 번에 보고 기억하는 대화의 범위를 뜻합니다. 지금 주고받는 대화, 읽은 파일, 실행한 명령이 모두 이 안에 쌓입니다. Skill과 Agent의 차이도 결국 "이 컨텍스트를 공유하느냐, 따로 두느냐"로 갈립니다.

한 줄로 먼저 정리하면 이렇습니다.

▎ Skill은 "어떻게 하는지"를 알려주는 매뉴얼이고, Agent는 "대신 해주는" 별도의 일꾼입니다.

1. Skill — 지금 이 대화 안에서 펼쳐지는 매뉴얼

Skill은 마크다운으로 패키징한 지침 묶음입니다. 반복되는 작업 절차, 팀 컨벤션, 체크리스트 같은 걸 파일로 만들어두면, Claude가 필요할 때 꺼내서 따라 합니다.

구조는 단순합니다.

.claude/skills/<skill-name>/
├── SKILL.md # 필수: frontmatter + 지침 본문
├── reference.md # 선택: 참고 자료
└── scripts/
└── helper.sh # 선택: 실행 스크립트

SKILL.md는 YAML frontmatter와 본문으로 이루어집니다.

---
name: pr-review
description: PR 코드 리뷰 시 우리 팀 규칙대로 검토할 때 사용
---
# PR 리뷰 체크리스트
1. 네이밍 컨벤션 확인 (camelCase)
2. 에러 핸들링 누락 여부
3. 테스트 커버리지
...

Skill의 핵심: 같은 컨텍스트, 그리고 점진적 로딩

Skill에서 가장 중요한 두 가지 특성이 있습니다.

• 지금 이 대화와 같은 컨텍스트에서 실행됩니다.
  Skill을 호출하면 그 내용이 현재 대화에 메시지로 들어와 그대로 남습니다.
  별도의 대화 공간을 새로 열지 않고, 진행 중인 대화 안에서 처리됩니다.

• Progressive disclosure(점진적 공개)가 적용됩니다. description만 항상 컨텍스트에 떠 있어서 Claude가 "이런 Skill이 있구나"만 알고, 실제 본문은 호출될 때만 로드됩니다.
  그래서 긴 참고 문서를 Skill로 쌓아둬도 평소엔 토큰을 거의 먹지 않습니다.

호출 방식도 두 가지입니다.

• 모델이 알아서 호출 — description을 보고 상황에 맞으면 자동 실행됩니다

• 사용자가 직접 호출 — 슬래시 커맨드처럼 /pr-review로 부릅니다

disable-model-invocation: true를 주면 자동 호출을 끄고 사용자 전용으로, user-invocable: false면 반대로 Claude 전용으로 만들 수 있습니다.

2. Agent(Subagent) — 자기만의 작업 공간을 가진 별도 일꾼

Agent(서브에이전트)는 자기만의 독립된 컨텍스트에서 도는 별도의 Claude입니다. 자기만의 시스템 프롬프트, 자기만의 도구 권한을 갖고, 작업이 끝나면 결과 요약만 메인 대화로 돌려줍니다.

.claude/agents/
├── code-reviewer.md
└── debugger.md
---
name: code-reviewer
description: 코드 변경분을 리뷰할 때 사용
tools: Read, Grep, Bash
model: opus
---
당신은 꼼꼼한 코드 리뷰어입니다. 다음 기준으로 검토하세요...
(이 본문이 서브에이전트의 시스템 프롬프트가 됩니다)

서브에이전트는 /agents 명령으로 여는 관리 UI에서 손쉽게 만들 수 있습니다. 평범한 한국어로 "이런 일을 하는 에이전트를 만들어줘"라고 설명하면 Claude가 정의 파일 초안을 잡아주고, 거기서 모델·허용 도구·저장 범위(프로젝트 전용 .claude/agents/ vs 개인 전용 ~/.claude/agents/)를 고르면 됩니다.

Agent의 핵심: 컨텍스트 격리

Agent를 쓰는 진짜 이유는 격리입니다.

• 별도의 독립된 컨텍스트 — 메인 대화 내용을 보지 않는 깨끗한 상태에서 시작합니다.

• 작업 과정이 메인 대화를 더럽히지 않습니다 — 서브에이전트가 수십 개 파일을 grep하고 로그를 뒤져도, 그 노이즈는 메인 대화에 들어오지 않습니다. 오직 최종 요약만 돌아옵니다.

• 도구·권한을 따로 제한할 수 있습니다 — tools로 허용 도구를 좁히거나, 모델을 따로 지정할 수 있습니다.

빌트인 에이전트도 있습니다. Explore(빠른 읽기 전용 탐색, Haiku 사용), Plan(구현 전 설계), general-purpose(범용 다단계 작업) 등입니다.

호출은 자동 위임, @agent-code-reviewer 멘션, 또는 claude --agent code-reviewer 플래그로 합니다.

3. 결정적 차이 한눈에 보기

Skill의 내용은 지금 내 대화에 남고, Agent의 작업 과정은 내 대화에 끼어들지 않고 결과만 받습니다.
이 격리가 바로 테스트 실행·문서 조회 같은 노이즈가 큰 작업에 Agent가 강한 이유입니다.

4. 여러 에이전트를 한 번에 다루기

에이전트 하나를 부리는 데 익숙해지면, 다음 욕심이 생깁니다. "여러 개를 동시에 굴릴 순 없나?" Claude Code는 이걸 위한 방법을 단계별로 제공합니다.
크게 세 가지인데, 용도가 다릅니다.

한 세션 안에서 병렬로 — 서브에이전트 오케스트레이션

가장 가벼운 방법입니다. 메인 대화가 오케스트레이터(지휘자) 역할을 하면서, 큰 작업을 쪼개 여러 서브에이전트에 동시에 분배하고 결과를 모아 종합합니다.
예를 들어 인증/DB/API 모듈을 각각 다른 서브에이전트로 동시에 조사시키고 결과만 합치는 식입니다. 각자 별도 컨텍스트에서 돌기 때문에 메인 대화는 깨끗하게 유지됩니다.
Fan-out 탐색, 보안·성능·테스트로 나눈 다차원 리뷰, 모듈별 병렬 리팩터링에 잘 맞습니다.

여러 독립 세션을 한 화면에서 — Agent View (claude agents)

여기가 "여러 에이전트를 한 번에 관리한다"의 진짜 주인공입니다.
터미널에서 claude agents를 실행하면 Agent View라는 대시보드가 열립니다.

claude agents

• 진행 상태별로 정리해서 보여줍니다 — 입력 대기 / 작업 중 / 완료

• - 대시보드에서 바로 새 작업을 디스패치합니다

• 어떤 세션이든 골라 들어가 대화 내용을 읽고 답을 줄 수 있습니다

• 디스패치된 세션은 자동으로 워크트리(격리된 git 체크아웃)에서 돌아 서로 충돌하지 않습니다

• 터미널을 닫아도 백그라운드에서 계속 일하고, 나중에 다시 들어가 확인할 수 있습니다

독립적인 작업 5개를 각각 세션에 던져두고, 나중에 어떤 게 끝났고 어떤 게 내 입력을 기다리는지 대시보드에서 확인하는 식의 워크플로우에 딱입니다.

[이미지 7] claude agents로 연 Agent View 대시보드 — 입력 대기/작업 중/완료로 나뉜 세션 목록 캡처

에이전트끼리 협업하게 — Agent Teams

서브에이전트는 결과를 지휘자에게 보고만 하지만, 더 정교한 협업이 필요할 때가 있습니다.
Agent Teams는 여러 독립 세션(팀원)이 공유 작업 목록을 두고 스스로 일을 가져가며, 서로 직접 메시지를 주고받는 방식입니다.
리드가 작업을 배분하고 팀원들이 토론하듯 검증합니다.

// ~/.claude/settings.json
{
  "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }
}

기본적으로 꺼져 있는 실험 기능이고, 팀원 하나하나가 완전한 Claude 인스턴스라 토큰 비용이 큽니다. 보통 3~5명으로 시작하길 권합니다. 경쟁 가설을 두고 디버깅하거나, 교차 레이어 변경, 여러 관점의 코드 리뷰처럼 "서로 의견을 부딪쳐야 하는" 무거운 작업에 적합합니다.

세 가지, 언제 무엇을?

알아둘 점

• 서브에이전트는 메인 대화 내용을 보지 못합니다 (깨끗하게 시작하는 게 장점이자 제약입니다)

• Agent View·Agent Teams는 세션마다 완전한 Claude 대화라 토큰이 세션 수에 비례해 늘어납니다.

5. 그래서 언제 무엇을 쓸까

• 반복되는 절차·규칙을 표준화하고 싶다 → Skill

• 출력이 지저분한 작업을 메인 대화에서 격리하고 싶다 → Agent(서브에이전트)

• 서로 무관한 여러 작업을 동시에 굴리고 관리하고 싶다 → Agent View (claude agents)

• 에이전트들이 서로 협업·검증하게 하고 싶다 → Agent Teams

Skill로 "규칙"을 정의하고,
서브에이전트를 부리고 ,
Agent View로 "여러 작업을 한 보드에서 지휘"하고
Agent Teams로 "팀 협업"까지.

이 도구들을 조합하면 Claude Code를 단순한 코딩 보조에서 작업 오케스트레이션 도구로 끌어올릴 수 있습니다.

앞으로도 제로백데브 Lab은 변화되는 개발 시대에 맞춰서 다양한 내용을 준비할 예정입니다!

다음 Lab도 기대해주세요!