Claude Code의 Agent와 Skill 개념 정리

저 같은 비개발자 바이브코더들을 위해 "개념"부터 탑재하기 위해 정리해봤습니다!!!

1. Agent란?

핵심 개념

Agent = 프롬프트 기반의 역할 정의

코드가 아니라 자연어 지시문(프롬프트)
Claude한테 "너는 이런 역할이고, 이렇게 행동해"라고 상세하게 알려주는 것
재사용 가능한 프롬프트 패키지라고 이해하면 됨

Agent ≈ 세밀하게 작성된 시스템 프롬프트 + 도구 제한

Agent의 구성 요소

┌─────────────────────────────────────┐
│  Agent = 재사용 가능한 프롬프트 패키지  │
│                                     │
│  ├─ 역할 정의 (자연어)               │
│  ├─ 사용 가능 도구 제한              │
│  ├─ 작업 방식 가이드                 │
│  └─ 자동 호출 조건 (description)     │
└─────────────────────────────────────┘

Agent vs 직접 프롬프팅

직접 프롬프팅	Agent
매번 입력해야 함	한번 만들면 재사용
도구 제한 없음	도구 제한 가능
내 대화에서만	팀과 공유 가능
즉흥적	검증된 패턴

Agent의 한계

프롬프트 기반이므로 100% 역할 보장은 안 됨
대부분 지시대로 행동하지만, 가끔 벗어날 수 있음
더 세밀한 프롬프트일수록 일관성 높아짐

2. Skill이란?

핵심 개념

Skill = Claude에게 가르쳐주는 지식/능력 모음

비유:

Agent = 전문가 (사람)
Skill = 전문가가 읽는 매뉴얼/교과서

Skill의 특징

자동 활성화: Claude가 필요할 때 알아서 찾아 씀
폴더 구조: .claude/skills/스킬이름/SKILL.md

3. Agent vs Skill 비교

구분	Agent	Skill
비유	전문가 (사람)	매뉴얼 (지식)
파일 위치	`.claude/agents/이름.md`	`.claude/skills/이름/SKILL.md`
동작	독립적으로 작업	Claude가 참고
호출	자동 + 명시적	자동만
컨텍스트	별도 작업 공간	현재 대화에 포함
용도	복잡한 역할 기반 작업	단순한 기능 추가

언제 뭘 만들까?

Agent로 만들어야 할 때:

"코드 검토자", "배포 담당자" 같은 역할이 필요할 때
여러 단계의 복잡한 작업
명시적으로 "이 전문가한테 맡겨줘"라고 하고 싶을 때

Skill로 만들어야 할 때:

"PDF 변환", "커밋 메시지 생성" 같은 기능이 필요할 때
단순하고 반복적인 작업
Claude가 알아서 필요할 때 쓰면 되는 것

4. Agent 만드는 방법

방법 1: 명령어 사용

bash
claude /agents

대화형 메뉴가 나와서 가이드에 따라 만들 수 있음.

방법 2: 직접 파일 생성

파일 위치:

# 이 프로젝트에서만 사용
.claude/agents/에이전트이름.md

# 모든 프로젝트에서 사용
~/.claude/agents/에이전트이름.md

파일 형식:

markdown
---
name: code-reviewer
description: 코드 품질 검토. 코드 수정 후 자동 사용.
tools: Read, Grep, Glob
model: sonnet
---

# 코드 검토 전문가

당신은 10년 경력의 시니어 개발자입니다.

## 검토 기준
1. 가독성 - 변수명이 명확한가?
2. 에러 처리 - 예외 상황 처리하는가?
3. 보안 - 민감 정보 노출 없는가?

## 작업 절차
1. git diff로 변경사항 확인
2. 수정된 파일 읽기
3. 문제점과 해결책 제시

주요 설정 옵션

필드	설명	예시
`name`	에이전트 이름 (소문자, 하이픈)	`bug-fixer`
`description`	언제 사용할지 (중요!)	`"버그 수정. 에러 발생 시 사용"`
`tools`	사용 가능 도구	`Read, Edit, Bash`
`model`	AI 모델 선택	`haiku`, `sonnet`, `opus`

5. 도구(Tools)

기본 제공 도구들 (Claude Code 내장)

Read, Write, Edit     - 파일 조작
Grep, Glob           - 검색
Bash                 - 터미널 명령
WebFetch, WebSearch  - 웹 접근
Task                 - 다른 Agent 호출

도구 확장: MCP

MCP 서버를 설치하면 새로운 도구가 추가됨:

mcp__slack__*           - Slack 도구들
mcp__mcp-atlassian__*   - Jira/Confluence 도구들
mcp__playwright__*      - 브라우저 자동화 도구들

Agent에서 MCP 도구 사용 예시:

markdown
---
name: jira-manager
description: Jira 이슈 관리. 이슈 생성, 상태 변경 시 사용.
tools: Read, mcp__mcp-atlassian__jira_create_issue, mcp__mcp-atlassian__jira_search
---

6. 기본 제공 Agent 유형

Agent	역할	언제 사용?
Explore	코드베이스 빠른 탐색	"이 기능 어디있어?"
Plan	작업 계획 수립	복잡한 리팩토링 전
General Purpose	복합 작업 수행	파일 수정이 필요한 작업

7. 실제 Agent 예시

배포 전문가

markdown
---
name: deployer
description: AWS 배포 전문가. 배포, 서버, EC2 관련 작업 시 사용.
tools: Bash, Read
model: sonnet
---

# 배포 전문가

AWS 배포를 안전하게 진행합니다.

## 배포 전 체크리스트
1. 테스트 통과 확인
2. 환경변수 확인
3. 현재 서버 상태 확인

## 배포 절차
1. 빌드 실행
2. S3 업로드 또는 서버 전송
3. 서비스 재시작
4. 헬스체크 확인

에러 해결사

markdown
---
name: error-fixer
description: 에러와 버그 수정. 테스트 실패나 에러 발생 시 자동 사용.
tools: Read, Edit, Bash, Grep
model: sonnet
---

# 에러 해결 전문가

에러를 빠르게 찾아 수정합니다.

## 해결 프로세스
1. 에러 메시지 분석
2. 관련 코드 찾기
3. 원인 파악
4. 최소한의 수정으로 해결
5. 테스트로 확인

8. 팀과 공유하기

bash
# Agent 파일을 git에 추가
git add .claude/agents/
git commit -m "배포 Agent 추가"
git push

팀원이 git pull 하면 바로 사용 가능!

9. 핵심 요약

Agent는 코드가 아니라 프롬프트 - 세밀한 역할 정의 문서
역할 100% 보장은 안 됨 - 프롬프트 엔지니어링의 한계 적용
도구 확장은 MCP로 - 이미 사용 중인 MCP가 도구 확장
Agent의 가치:
- 재사용성 (매번 같은 말 안 해도 됨)
- 일관성 (검증된 프롬프트)
- 공유 (팀원들과 같은 Agent 사용)
- 도구 제한 (실수 방지)
- 자동 호출 (상황에 맞게 선택)

결론: Agent는 "프로그래밍"이 아니라 "프롬프트 관리"에 가깝다!

10. Description의 중요성

Description = 자동 선택의 핵심

Claude가 Agent, Skill, MCP Tool 중 뭘 쓸지 결정하는 건 전부 description 매칭이다.

사용자: "리들에 글 올려줘"
        ↓
Claude: 모든 description 스캔
        ↓
"리들 발행... 글 올리기, 포스팅" ← 매칭!
        ↓
해당 Skill/Agent/Tool 선택

Description 잘 쓰는 법

markdown
description: [핵심 동작]. [구체적 설명]. [동의어/유사 표현들].

좋은 예시:

markdown
# 리들 발행
description: 리들 발행. 마크다운을 bkamp.ai에 게시. 글 올리기, 포스팅, 발행, 퍼블리시.

# 배포
description: AWS 배포. EC2 서버에 코드 배포. 디플로이, 릴리즈, 서버 업데이트.

# 코드 리뷰
description: 코드 리뷰. 품질과 보안 검토. PR 체크, 코드 검사, 리뷰.

핵심: 동의어를 넣어라! 사용자가 어떤 말로 요청할지 모르니까.

MCP도 같은 원리

MCP 서버의 각 도구(tool)에도 description이 있고, Claude는 이걸 보고 어떤 도구를 쓸지 결정한다.

typescript
// MCP 서버 코드 예시
server.tool({
  name: "slack_post_message",
  description: "Post a new message to a Slack channel. 슬랙 메시지 보내기.",
});

종류	description 위치	역할
Skill	`SKILL.md` 프론트매터	자동 로드 기준
Agent	`.md` 프론트매터	자동 선택 기준
MCP Tool	서버 코드에 정의	도구 선택 기준

11. 프로젝트 Skill vs 전역 Skill

저장 위치

bash
# 프로젝트 Skill (이 프로젝트에서만)
/프로젝트경로/.claude/skills/스킬이름/SKILL.md

# 전역 Skill (모든 프로젝트에서)
~/.claude/skills/스킬이름/SKILL.md

전역 Skill 주의사항

전역 Skill은 모든 프로젝트에서 description 매칭되므로 주의 필요:

전역 Skill: "리들 발행. 글 올리기, 포스팅..."
        ↓
다른 프로젝트에서: "이 글 포스팅해줘"
        ↓
Claude: description 매칭됨! → Skill 로드
        ↓
엉뚱한 프로젝트에서 riddle-publish.ts 실행 시도 💥

전역 vs 프로젝트 선택 기준

전역 Skill로 적합:

모든 프로젝트에서 동일하게 쓰는 것
프로젝트 경로에 의존하지 않는 것
예: 커밋 메시지 스타일, 코드 리뷰 체크리스트, 공통 코딩 컨벤션

프로젝트 Skill로 적합:

특정 스크립트 실행 (riddle-publish.ts)
특정 서버 배포
특정 DB 접근
특정 API 호출

12. Agent + Skills 조합

Agent가 여러 Skill을 가질 수 있다

Agent 정의할 때 skills 필드로 연결:

markdown
---
name: riddle-writer
description: 리들 콘텐츠 작성 및 발행 전문가
skills: riddle-publish, markdown-style
---

# 리들 작성 전문가

당신은 리들 콘텐츠를 작성하고 발행하는 전문가입니다.

이 Agent가 활성화되면 관련 Skill들도 함께 로드됨.

구조

┌─────────────────────────────────┐
│  Agent: riddle-writer           │
│  ├─ 역할 정의 (프롬프트)         │
│  ├─ Skill: riddle-publish       │ ← 발행 방법
│  ├─ Skill: markdown-style       │ ← 스타일 가이드
│  └─ Tools: Read, Write, Bash    │ ← 실행 도구
└─────────────────────────────────┘

13. AI 서비스의 본질

Genspark, GPTs 같은 서비스들

결국 이런 서비스들이 하는 것:

"여행 플래너" Agent
├─ Skill: 항공권 검색
├─ Skill: 호텔 예약
├─ Skill: 일정 최적화
├─ Skill: 현지 맛집 추천
└─ Tools: 웹 검색, API 호출

**잘 정의된 역할(Agent) + 기능 모음(Skills) + 도구(Tools)**를 패키징한 것.

공식

AI 서비스 = 잘 조합된 Agent
         = 역할 정의 + Skills + Tools

개념	역할	비유
Agent	전문가 정체성	"나는 여행 플래너야"
Skill	특정 능력/지식	"항공권 검색할 줄 알아"
Tool	실행 수단	"검색 API 호출할 수 있어"

Claude Code의 Agent와 Skill 개념 정리

저 같은 비개발자 바이브코더들을 위해 "개념"부터 탑재하기 위해 정리해봤습니다!!!

1. Agent란?

핵심 개념

Agent = 프롬프트 기반의 역할 정의

코드가 아니라 자연어 지시문(프롬프트)
Claude한테 "너는 이런 역할이고, 이렇게 행동해"라고 상세하게 알려주는 것
재사용 가능한 프롬프트 패키지라고 이해하면 됨

Agent ≈ 세밀하게 작성된 시스템 프롬프트 + 도구 제한

Agent의 구성 요소

┌─────────────────────────────────────┐
│  Agent = 재사용 가능한 프롬프트 패키지  │
│                                     │
│  ├─ 역할 정의 (자연어)               │
│  ├─ 사용 가능 도구 제한              │
│  ├─ 작업 방식 가이드                 │
│  └─ 자동 호출 조건 (description)     │
└─────────────────────────────────────┘

Agent vs 직접 프롬프팅

직접 프롬프팅	Agent
매번 입력해야 함	한번 만들면 재사용
도구 제한 없음	도구 제한 가능
내 대화에서만	팀과 공유 가능
즉흥적	검증된 패턴

Agent의 한계

프롬프트 기반이므로 100% 역할 보장은 안 됨
대부분 지시대로 행동하지만, 가끔 벗어날 수 있음
더 세밀한 프롬프트일수록 일관성 높아짐

2. Skill이란?

핵심 개념

Skill = Claude에게 가르쳐주는 지식/능력 모음

비유:

Agent = 전문가 (사람)
Skill = 전문가가 읽는 매뉴얼/교과서

Skill의 특징

자동 활성화: Claude가 필요할 때 알아서 찾아 씀
폴더 구조: .claude/skills/스킬이름/SKILL.md

3. Agent vs Skill 비교

구분	Agent	Skill
비유	전문가 (사람)	매뉴얼 (지식)
파일 위치	`.claude/agents/이름.md`	`.claude/skills/이름/SKILL.md`
동작	독립적으로 작업	Claude가 참고
호출	자동 + 명시적	자동만
컨텍스트	별도 작업 공간	현재 대화에 포함
용도	복잡한 역할 기반 작업	단순한 기능 추가

언제 뭘 만들까?

Agent로 만들어야 할 때:

"코드 검토자", "배포 담당자" 같은 역할이 필요할 때
여러 단계의 복잡한 작업
명시적으로 "이 전문가한테 맡겨줘"라고 하고 싶을 때

Skill로 만들어야 할 때:

"PDF 변환", "커밋 메시지 생성" 같은 기능이 필요할 때
단순하고 반복적인 작업
Claude가 알아서 필요할 때 쓰면 되는 것

4. Agent 만드는 방법

방법 1: 명령어 사용

bash
claude /agents

대화형 메뉴가 나와서 가이드에 따라 만들 수 있음.

방법 2: 직접 파일 생성

파일 위치:

# 이 프로젝트에서만 사용
.claude/agents/에이전트이름.md

# 모든 프로젝트에서 사용
~/.claude/agents/에이전트이름.md

파일 형식:

markdown
---
name: code-reviewer
description: 코드 품질 검토. 코드 수정 후 자동 사용.
tools: Read, Grep, Glob
model: sonnet
---

# 코드 검토 전문가

당신은 10년 경력의 시니어 개발자입니다.

## 검토 기준
1. 가독성 - 변수명이 명확한가?
2. 에러 처리 - 예외 상황 처리하는가?
3. 보안 - 민감 정보 노출 없는가?

## 작업 절차
1. git diff로 변경사항 확인
2. 수정된 파일 읽기
3. 문제점과 해결책 제시

주요 설정 옵션

필드	설명	예시
`name`	에이전트 이름 (소문자, 하이픈)	`bug-fixer`
`description`	언제 사용할지 (중요!)	`"버그 수정. 에러 발생 시 사용"`
`tools`	사용 가능 도구	`Read, Edit, Bash`
`model`	AI 모델 선택	`haiku`, `sonnet`, `opus`

5. 도구(Tools)

기본 제공 도구들 (Claude Code 내장)

Read, Write, Edit     - 파일 조작
Grep, Glob           - 검색
Bash                 - 터미널 명령
WebFetch, WebSearch  - 웹 접근
Task                 - 다른 Agent 호출

도구 확장: MCP

MCP 서버를 설치하면 새로운 도구가 추가됨:

mcp__slack__*           - Slack 도구들
mcp__mcp-atlassian__*   - Jira/Confluence 도구들
mcp__playwright__*      - 브라우저 자동화 도구들

Agent에서 MCP 도구 사용 예시:

markdown
---
name: jira-manager
description: Jira 이슈 관리. 이슈 생성, 상태 변경 시 사용.
tools: Read, mcp__mcp-atlassian__jira_create_issue, mcp__mcp-atlassian__jira_search
---

6. 기본 제공 Agent 유형

Agent	역할	언제 사용?
Explore	코드베이스 빠른 탐색	"이 기능 어디있어?"
Plan	작업 계획 수립	복잡한 리팩토링 전
General Purpose	복합 작업 수행	파일 수정이 필요한 작업

7. 실제 Agent 예시

배포 전문가

markdown
---
name: deployer
description: AWS 배포 전문가. 배포, 서버, EC2 관련 작업 시 사용.
tools: Bash, Read
model: sonnet
---

# 배포 전문가

AWS 배포를 안전하게 진행합니다.

## 배포 전 체크리스트
1. 테스트 통과 확인
2. 환경변수 확인
3. 현재 서버 상태 확인

## 배포 절차
1. 빌드 실행
2. S3 업로드 또는 서버 전송
3. 서비스 재시작
4. 헬스체크 확인

에러 해결사

markdown
---
name: error-fixer
description: 에러와 버그 수정. 테스트 실패나 에러 발생 시 자동 사용.
tools: Read, Edit, Bash, Grep
model: sonnet
---

# 에러 해결 전문가

에러를 빠르게 찾아 수정합니다.

## 해결 프로세스
1. 에러 메시지 분석
2. 관련 코드 찾기
3. 원인 파악
4. 최소한의 수정으로 해결
5. 테스트로 확인

8. 팀과 공유하기

bash
# Agent 파일을 git에 추가
git add .claude/agents/
git commit -m "배포 Agent 추가"
git push

팀원이 git pull 하면 바로 사용 가능!

9. 핵심 요약

Agent는 코드가 아니라 프롬프트 - 세밀한 역할 정의 문서
역할 100% 보장은 안 됨 - 프롬프트 엔지니어링의 한계 적용
도구 확장은 MCP로 - 이미 사용 중인 MCP가 도구 확장
Agent의 가치:
- 재사용성 (매번 같은 말 안 해도 됨)
- 일관성 (검증된 프롬프트)
- 공유 (팀원들과 같은 Agent 사용)
- 도구 제한 (실수 방지)
- 자동 호출 (상황에 맞게 선택)

결론: Agent는 "프로그래밍"이 아니라 "프롬프트 관리"에 가깝다!

10. Description의 중요성

Description = 자동 선택의 핵심

Claude가 Agent, Skill, MCP Tool 중 뭘 쓸지 결정하는 건 전부 description 매칭이다.

사용자: "리들에 글 올려줘"
        ↓
Claude: 모든 description 스캔
        ↓
"리들 발행... 글 올리기, 포스팅" ← 매칭!
        ↓
해당 Skill/Agent/Tool 선택

Description 잘 쓰는 법

markdown
description: [핵심 동작]. [구체적 설명]. [동의어/유사 표현들].

좋은 예시:

markdown
# 리들 발행
description: 리들 발행. 마크다운을 bkamp.ai에 게시. 글 올리기, 포스팅, 발행, 퍼블리시.

# 배포
description: AWS 배포. EC2 서버에 코드 배포. 디플로이, 릴리즈, 서버 업데이트.

# 코드 리뷰
description: 코드 리뷰. 품질과 보안 검토. PR 체크, 코드 검사, 리뷰.

핵심: 동의어를 넣어라! 사용자가 어떤 말로 요청할지 모르니까.

MCP도 같은 원리

MCP 서버의 각 도구(tool)에도 description이 있고, Claude는 이걸 보고 어떤 도구를 쓸지 결정한다.

typescript
// MCP 서버 코드 예시
server.tool({
  name: "slack_post_message",
  description: "Post a new message to a Slack channel. 슬랙 메시지 보내기.",
});

종류	description 위치	역할
Skill	`SKILL.md` 프론트매터	자동 로드 기준
Agent	`.md` 프론트매터	자동 선택 기준
MCP Tool	서버 코드에 정의	도구 선택 기준

11. 프로젝트 Skill vs 전역 Skill

저장 위치

bash
# 프로젝트 Skill (이 프로젝트에서만)
/프로젝트경로/.claude/skills/스킬이름/SKILL.md

# 전역 Skill (모든 프로젝트에서)
~/.claude/skills/스킬이름/SKILL.md

전역 Skill 주의사항

전역 Skill은 모든 프로젝트에서 description 매칭되므로 주의 필요:

전역 Skill: "리들 발행. 글 올리기, 포스팅..."
        ↓
다른 프로젝트에서: "이 글 포스팅해줘"
        ↓
Claude: description 매칭됨! → Skill 로드
        ↓
엉뚱한 프로젝트에서 riddle-publish.ts 실행 시도 💥

전역 vs 프로젝트 선택 기준

전역 Skill로 적합:

모든 프로젝트에서 동일하게 쓰는 것
프로젝트 경로에 의존하지 않는 것
예: 커밋 메시지 스타일, 코드 리뷰 체크리스트, 공통 코딩 컨벤션

프로젝트 Skill로 적합:

특정 스크립트 실행 (riddle-publish.ts)
특정 서버 배포
특정 DB 접근
특정 API 호출

12. Agent + Skills 조합

Agent가 여러 Skill을 가질 수 있다

Agent 정의할 때 skills 필드로 연결:

markdown
---
name: riddle-writer
description: 리들 콘텐츠 작성 및 발행 전문가
skills: riddle-publish, markdown-style
---

# 리들 작성 전문가

당신은 리들 콘텐츠를 작성하고 발행하는 전문가입니다.

이 Agent가 활성화되면 관련 Skill들도 함께 로드됨.

구조

┌─────────────────────────────────┐
│  Agent: riddle-writer           │
│  ├─ 역할 정의 (프롬프트)         │
│  ├─ Skill: riddle-publish       │ ← 발행 방법
│  ├─ Skill: markdown-style       │ ← 스타일 가이드
│  └─ Tools: Read, Write, Bash    │ ← 실행 도구
└─────────────────────────────────┘

13. AI 서비스의 본질

Genspark, GPTs 같은 서비스들

결국 이런 서비스들이 하는 것:

"여행 플래너" Agent
├─ Skill: 항공권 검색
├─ Skill: 호텔 예약
├─ Skill: 일정 최적화
├─ Skill: 현지 맛집 추천
└─ Tools: 웹 검색, API 호출

**잘 정의된 역할(Agent) + 기능 모음(Skills) + 도구(Tools)**를 패키징한 것.

공식

AI 서비스 = 잘 조합된 Agent
         = 역할 정의 + Skills + Tools

개념	역할	비유
Agent	전문가 정체성	"나는 여행 플래너야"
Skill	특정 능력/지식	"항공권 검색할 줄 알아"
Tool	실행 수단	"검색 API 호출할 수 있어"

Claude Code의 Agent와 Skill 개념 정리

저 같은 비개발자 바이브코더들을 위해 "개념"부터 탑재하기 위해 정리해봤습니다!!!

1. Agent란?

핵심 개념

Agent = 프롬프트 기반의 역할 정의

코드가 아니라 자연어 지시문(프롬프트)
Claude한테 "너는 이런 역할이고, 이렇게 행동해"라고 상세하게 알려주는 것
재사용 가능한 프롬프트 패키지라고 이해하면 됨

Agent ≈ 세밀하게 작성된 시스템 프롬프트 + 도구 제한

Agent의 구성 요소

┌─────────────────────────────────────┐
│  Agent = 재사용 가능한 프롬프트 패키지  │
│                                     │
│  ├─ 역할 정의 (자연어)               │
│  ├─ 사용 가능 도구 제한              │
│  ├─ 작업 방식 가이드                 │
│  └─ 자동 호출 조건 (description)     │
└─────────────────────────────────────┘

Agent vs 직접 프롬프팅

직접 프롬프팅	Agent
매번 입력해야 함	한번 만들면 재사용
도구 제한 없음	도구 제한 가능
내 대화에서만	팀과 공유 가능
즉흥적	검증된 패턴

Agent의 한계

프롬프트 기반이므로 100% 역할 보장은 안 됨
대부분 지시대로 행동하지만, 가끔 벗어날 수 있음
더 세밀한 프롬프트일수록 일관성 높아짐

2. Skill이란?

핵심 개념

Skill = Claude에게 가르쳐주는 지식/능력 모음

비유:

Agent = 전문가 (사람)
Skill = 전문가가 읽는 매뉴얼/교과서

Skill의 특징

자동 활성화: Claude가 필요할 때 알아서 찾아 씀
폴더 구조: .claude/skills/스킬이름/SKILL.md

3. Agent vs Skill 비교

구분	Agent	Skill
비유	전문가 (사람)	매뉴얼 (지식)
파일 위치	`.claude/agents/이름.md`	`.claude/skills/이름/SKILL.md`
동작	독립적으로 작업	Claude가 참고
호출	자동 + 명시적	자동만
컨텍스트	별도 작업 공간	현재 대화에 포함
용도	복잡한 역할 기반 작업	단순한 기능 추가

언제 뭘 만들까?

Agent로 만들어야 할 때:

"코드 검토자", "배포 담당자" 같은 역할이 필요할 때
여러 단계의 복잡한 작업
명시적으로 "이 전문가한테 맡겨줘"라고 하고 싶을 때

Skill로 만들어야 할 때:

"PDF 변환", "커밋 메시지 생성" 같은 기능이 필요할 때
단순하고 반복적인 작업
Claude가 알아서 필요할 때 쓰면 되는 것

4. Agent 만드는 방법

방법 1: 명령어 사용

bash
claude /agents

대화형 메뉴가 나와서 가이드에 따라 만들 수 있음.

방법 2: 직접 파일 생성

파일 위치:

# 이 프로젝트에서만 사용
.claude/agents/에이전트이름.md

# 모든 프로젝트에서 사용
~/.claude/agents/에이전트이름.md

파일 형식:

markdown
---
name: code-reviewer
description: 코드 품질 검토. 코드 수정 후 자동 사용.
tools: Read, Grep, Glob
model: sonnet
---

# 코드 검토 전문가

당신은 10년 경력의 시니어 개발자입니다.

## 검토 기준
1. 가독성 - 변수명이 명확한가?
2. 에러 처리 - 예외 상황 처리하는가?
3. 보안 - 민감 정보 노출 없는가?

## 작업 절차
1. git diff로 변경사항 확인
2. 수정된 파일 읽기
3. 문제점과 해결책 제시

주요 설정 옵션

필드	설명	예시
`name`	에이전트 이름 (소문자, 하이픈)	`bug-fixer`
`description`	언제 사용할지 (중요!)	`"버그 수정. 에러 발생 시 사용"`
`tools`	사용 가능 도구	`Read, Edit, Bash`
`model`	AI 모델 선택	`haiku`, `sonnet`, `opus`

5. 도구(Tools)

기본 제공 도구들 (Claude Code 내장)

Read, Write, Edit     - 파일 조작
Grep, Glob           - 검색
Bash                 - 터미널 명령
WebFetch, WebSearch  - 웹 접근
Task                 - 다른 Agent 호출

도구 확장: MCP

MCP 서버를 설치하면 새로운 도구가 추가됨:

mcp__slack__*           - Slack 도구들
mcp__mcp-atlassian__*   - Jira/Confluence 도구들
mcp__playwright__*      - 브라우저 자동화 도구들

Agent에서 MCP 도구 사용 예시:

markdown
---
name: jira-manager
description: Jira 이슈 관리. 이슈 생성, 상태 변경 시 사용.
tools: Read, mcp__mcp-atlassian__jira_create_issue, mcp__mcp-atlassian__jira_search
---

6. 기본 제공 Agent 유형

Agent	역할	언제 사용?
Explore	코드베이스 빠른 탐색	"이 기능 어디있어?"
Plan	작업 계획 수립	복잡한 리팩토링 전
General Purpose	복합 작업 수행	파일 수정이 필요한 작업

7. 실제 Agent 예시

배포 전문가

markdown
---
name: deployer
description: AWS 배포 전문가. 배포, 서버, EC2 관련 작업 시 사용.
tools: Bash, Read
model: sonnet
---

# 배포 전문가

AWS 배포를 안전하게 진행합니다.

## 배포 전 체크리스트
1. 테스트 통과 확인
2. 환경변수 확인
3. 현재 서버 상태 확인

## 배포 절차
1. 빌드 실행
2. S3 업로드 또는 서버 전송
3. 서비스 재시작
4. 헬스체크 확인

에러 해결사

markdown
---
name: error-fixer
description: 에러와 버그 수정. 테스트 실패나 에러 발생 시 자동 사용.
tools: Read, Edit, Bash, Grep
model: sonnet
---

# 에러 해결 전문가

에러를 빠르게 찾아 수정합니다.

## 해결 프로세스
1. 에러 메시지 분석
2. 관련 코드 찾기
3. 원인 파악
4. 최소한의 수정으로 해결
5. 테스트로 확인

8. 팀과 공유하기

bash
# Agent 파일을 git에 추가
git add .claude/agents/
git commit -m "배포 Agent 추가"
git push

팀원이 git pull 하면 바로 사용 가능!

9. 핵심 요약

Agent는 코드가 아니라 프롬프트 - 세밀한 역할 정의 문서
역할 100% 보장은 안 됨 - 프롬프트 엔지니어링의 한계 적용
도구 확장은 MCP로 - 이미 사용 중인 MCP가 도구 확장
Agent의 가치:
- 재사용성 (매번 같은 말 안 해도 됨)
- 일관성 (검증된 프롬프트)
- 공유 (팀원들과 같은 Agent 사용)
- 도구 제한 (실수 방지)
- 자동 호출 (상황에 맞게 선택)

결론: Agent는 "프로그래밍"이 아니라 "프롬프트 관리"에 가깝다!

10. Description의 중요성

Description = 자동 선택의 핵심

Claude가 Agent, Skill, MCP Tool 중 뭘 쓸지 결정하는 건 전부 description 매칭이다.

사용자: "리들에 글 올려줘"
        ↓
Claude: 모든 description 스캔
        ↓
"리들 발행... 글 올리기, 포스팅" ← 매칭!
        ↓
해당 Skill/Agent/Tool 선택

Description 잘 쓰는 법

markdown
description: [핵심 동작]. [구체적 설명]. [동의어/유사 표현들].

좋은 예시:

markdown
# 리들 발행
description: 리들 발행. 마크다운을 bkamp.ai에 게시. 글 올리기, 포스팅, 발행, 퍼블리시.

# 배포
description: AWS 배포. EC2 서버에 코드 배포. 디플로이, 릴리즈, 서버 업데이트.

# 코드 리뷰
description: 코드 리뷰. 품질과 보안 검토. PR 체크, 코드 검사, 리뷰.

핵심: 동의어를 넣어라! 사용자가 어떤 말로 요청할지 모르니까.

MCP도 같은 원리

MCP 서버의 각 도구(tool)에도 description이 있고, Claude는 이걸 보고 어떤 도구를 쓸지 결정한다.

typescript
// MCP 서버 코드 예시
server.tool({
  name: "slack_post_message",
  description: "Post a new message to a Slack channel. 슬랙 메시지 보내기.",
});

종류	description 위치	역할
Skill	`SKILL.md` 프론트매터	자동 로드 기준
Agent	`.md` 프론트매터	자동 선택 기준
MCP Tool	서버 코드에 정의	도구 선택 기준

11. 프로젝트 Skill vs 전역 Skill

저장 위치

bash
# 프로젝트 Skill (이 프로젝트에서만)
/프로젝트경로/.claude/skills/스킬이름/SKILL.md

# 전역 Skill (모든 프로젝트에서)
~/.claude/skills/스킬이름/SKILL.md

전역 Skill 주의사항

전역 Skill은 모든 프로젝트에서 description 매칭되므로 주의 필요:

전역 Skill: "리들 발행. 글 올리기, 포스팅..."
        ↓
다른 프로젝트에서: "이 글 포스팅해줘"
        ↓
Claude: description 매칭됨! → Skill 로드
        ↓
엉뚱한 프로젝트에서 riddle-publish.ts 실행 시도 💥

전역 vs 프로젝트 선택 기준

전역 Skill로 적합:

모든 프로젝트에서 동일하게 쓰는 것
프로젝트 경로에 의존하지 않는 것
예: 커밋 메시지 스타일, 코드 리뷰 체크리스트, 공통 코딩 컨벤션

프로젝트 Skill로 적합:

특정 스크립트 실행 (riddle-publish.ts)
특정 서버 배포
특정 DB 접근
특정 API 호출

12. Agent + Skills 조합

Agent가 여러 Skill을 가질 수 있다

Agent 정의할 때 skills 필드로 연결:

markdown
---
name: riddle-writer
description: 리들 콘텐츠 작성 및 발행 전문가
skills: riddle-publish, markdown-style
---

# 리들 작성 전문가

당신은 리들 콘텐츠를 작성하고 발행하는 전문가입니다.

이 Agent가 활성화되면 관련 Skill들도 함께 로드됨.

구조

┌─────────────────────────────────┐
│  Agent: riddle-writer           │
│  ├─ 역할 정의 (프롬프트)         │
│  ├─ Skill: riddle-publish       │ ← 발행 방법
│  ├─ Skill: markdown-style       │ ← 스타일 가이드
│  └─ Tools: Read, Write, Bash    │ ← 실행 도구
└─────────────────────────────────┘

13. AI 서비스의 본질

Genspark, GPTs 같은 서비스들

결국 이런 서비스들이 하는 것:

"여행 플래너" Agent
├─ Skill: 항공권 검색
├─ Skill: 호텔 예약
├─ Skill: 일정 최적화
├─ Skill: 현지 맛집 추천
└─ Tools: 웹 검색, API 호출

**잘 정의된 역할(Agent) + 기능 모음(Skills) + 도구(Tools)**를 패키징한 것.

공식

AI 서비스 = 잘 조합된 Agent
         = 역할 정의 + Skills + Tools

개념	역할	비유
Agent	전문가 정체성	"나는 여행 플래너야"
Skill	특정 능력/지식	"항공권 검색할 줄 알아"
Tool	실행 수단	"검색 API 호출할 수 있어"

Claude Code의 Agent와 Skill 개념 정리

저 같은 비개발자 바이브코더들을 위해 "개념"부터 탑재하기 위해 정리해봤습니다!!!

1. Agent란?

핵심 개념

Agent = 프롬프트 기반의 역할 정의

코드가 아니라 자연어 지시문(프롬프트)
Claude한테 "너는 이런 역할이고, 이렇게 행동해"라고 상세하게 알려주는 것
재사용 가능한 프롬프트 패키지라고 이해하면 됨

Agent ≈ 세밀하게 작성된 시스템 프롬프트 + 도구 제한

Agent의 구성 요소

┌─────────────────────────────────────┐
│  Agent = 재사용 가능한 프롬프트 패키지  │
│                                     │
│  ├─ 역할 정의 (자연어)               │
│  ├─ 사용 가능 도구 제한              │
│  ├─ 작업 방식 가이드                 │
│  └─ 자동 호출 조건 (description)     │
└─────────────────────────────────────┘

Agent vs 직접 프롬프팅

직접 프롬프팅	Agent
매번 입력해야 함	한번 만들면 재사용
도구 제한 없음	도구 제한 가능
내 대화에서만	팀과 공유 가능
즉흥적	검증된 패턴

Agent의 한계

프롬프트 기반이므로 100% 역할 보장은 안 됨
대부분 지시대로 행동하지만, 가끔 벗어날 수 있음
더 세밀한 프롬프트일수록 일관성 높아짐

2. Skill이란?

핵심 개념

Skill = Claude에게 가르쳐주는 지식/능력 모음

비유:

Agent = 전문가 (사람)
Skill = 전문가가 읽는 매뉴얼/교과서

Skill의 특징

자동 활성화: Claude가 필요할 때 알아서 찾아 씀
폴더 구조: .claude/skills/스킬이름/SKILL.md

3. Agent vs Skill 비교

구분	Agent	Skill
비유	전문가 (사람)	매뉴얼 (지식)
파일 위치	`.claude/agents/이름.md`	`.claude/skills/이름/SKILL.md`
동작	독립적으로 작업	Claude가 참고
호출	자동 + 명시적	자동만
컨텍스트	별도 작업 공간	현재 대화에 포함
용도	복잡한 역할 기반 작업	단순한 기능 추가

언제 뭘 만들까?

Agent로 만들어야 할 때:

"코드 검토자", "배포 담당자" 같은 역할이 필요할 때
여러 단계의 복잡한 작업
명시적으로 "이 전문가한테 맡겨줘"라고 하고 싶을 때

Skill로 만들어야 할 때:

"PDF 변환", "커밋 메시지 생성" 같은 기능이 필요할 때
단순하고 반복적인 작업
Claude가 알아서 필요할 때 쓰면 되는 것

4. Agent 만드는 방법

방법 1: 명령어 사용

bash
claude /agents

대화형 메뉴가 나와서 가이드에 따라 만들 수 있음.

방법 2: 직접 파일 생성

파일 위치:

# 이 프로젝트에서만 사용
.claude/agents/에이전트이름.md

# 모든 프로젝트에서 사용
~/.claude/agents/에이전트이름.md

파일 형식:

markdown
---
name: code-reviewer
description: 코드 품질 검토. 코드 수정 후 자동 사용.
tools: Read, Grep, Glob
model: sonnet
---

# 코드 검토 전문가

당신은 10년 경력의 시니어 개발자입니다.

## 검토 기준
1. 가독성 - 변수명이 명확한가?
2. 에러 처리 - 예외 상황 처리하는가?
3. 보안 - 민감 정보 노출 없는가?

## 작업 절차
1. git diff로 변경사항 확인
2. 수정된 파일 읽기
3. 문제점과 해결책 제시

주요 설정 옵션

필드	설명	예시
`name`	에이전트 이름 (소문자, 하이픈)	`bug-fixer`
`description`	언제 사용할지 (중요!)	`"버그 수정. 에러 발생 시 사용"`
`tools`	사용 가능 도구	`Read, Edit, Bash`
`model`	AI 모델 선택	`haiku`, `sonnet`, `opus`

5. 도구(Tools)

기본 제공 도구들 (Claude Code 내장)

Read, Write, Edit     - 파일 조작
Grep, Glob           - 검색
Bash                 - 터미널 명령
WebFetch, WebSearch  - 웹 접근
Task                 - 다른 Agent 호출

도구 확장: MCP

MCP 서버를 설치하면 새로운 도구가 추가됨:

mcp__slack__*           - Slack 도구들
mcp__mcp-atlassian__*   - Jira/Confluence 도구들
mcp__playwright__*      - 브라우저 자동화 도구들

Agent에서 MCP 도구 사용 예시:

markdown
---
name: jira-manager
description: Jira 이슈 관리. 이슈 생성, 상태 변경 시 사용.
tools: Read, mcp__mcp-atlassian__jira_create_issue, mcp__mcp-atlassian__jira_search
---

6. 기본 제공 Agent 유형

Agent	역할	언제 사용?
Explore	코드베이스 빠른 탐색	"이 기능 어디있어?"
Plan	작업 계획 수립	복잡한 리팩토링 전
General Purpose	복합 작업 수행	파일 수정이 필요한 작업

7. 실제 Agent 예시

배포 전문가

markdown
---
name: deployer
description: AWS 배포 전문가. 배포, 서버, EC2 관련 작업 시 사용.
tools: Bash, Read
model: sonnet
---

# 배포 전문가

AWS 배포를 안전하게 진행합니다.

## 배포 전 체크리스트
1. 테스트 통과 확인
2. 환경변수 확인
3. 현재 서버 상태 확인

## 배포 절차
1. 빌드 실행
2. S3 업로드 또는 서버 전송
3. 서비스 재시작
4. 헬스체크 확인

에러 해결사

markdown
---
name: error-fixer
description: 에러와 버그 수정. 테스트 실패나 에러 발생 시 자동 사용.
tools: Read, Edit, Bash, Grep
model: sonnet
---

# 에러 해결 전문가

에러를 빠르게 찾아 수정합니다.

## 해결 프로세스
1. 에러 메시지 분석
2. 관련 코드 찾기
3. 원인 파악
4. 최소한의 수정으로 해결
5. 테스트로 확인

8. 팀과 공유하기

bash
# Agent 파일을 git에 추가
git add .claude/agents/
git commit -m "배포 Agent 추가"
git push

팀원이 git pull 하면 바로 사용 가능!

9. 핵심 요약

Agent는 코드가 아니라 프롬프트 - 세밀한 역할 정의 문서
역할 100% 보장은 안 됨 - 프롬프트 엔지니어링의 한계 적용
도구 확장은 MCP로 - 이미 사용 중인 MCP가 도구 확장
Agent의 가치:
- 재사용성 (매번 같은 말 안 해도 됨)
- 일관성 (검증된 프롬프트)
- 공유 (팀원들과 같은 Agent 사용)
- 도구 제한 (실수 방지)
- 자동 호출 (상황에 맞게 선택)

결론: Agent는 "프로그래밍"이 아니라 "프롬프트 관리"에 가깝다!

10. Description의 중요성

Description = 자동 선택의 핵심

Claude가 Agent, Skill, MCP Tool 중 뭘 쓸지 결정하는 건 전부 description 매칭이다.

사용자: "리들에 글 올려줘"
        ↓
Claude: 모든 description 스캔
        ↓
"리들 발행... 글 올리기, 포스팅" ← 매칭!
        ↓
해당 Skill/Agent/Tool 선택

Description 잘 쓰는 법

markdown
description: [핵심 동작]. [구체적 설명]. [동의어/유사 표현들].

좋은 예시:

markdown
# 리들 발행
description: 리들 발행. 마크다운을 bkamp.ai에 게시. 글 올리기, 포스팅, 발행, 퍼블리시.

# 배포
description: AWS 배포. EC2 서버에 코드 배포. 디플로이, 릴리즈, 서버 업데이트.

# 코드 리뷰
description: 코드 리뷰. 품질과 보안 검토. PR 체크, 코드 검사, 리뷰.

핵심: 동의어를 넣어라! 사용자가 어떤 말로 요청할지 모르니까.

MCP도 같은 원리

MCP 서버의 각 도구(tool)에도 description이 있고, Claude는 이걸 보고 어떤 도구를 쓸지 결정한다.

typescript
// MCP 서버 코드 예시
server.tool({
  name: "slack_post_message",
  description: "Post a new message to a Slack channel. 슬랙 메시지 보내기.",
});

종류	description 위치	역할
Skill	`SKILL.md` 프론트매터	자동 로드 기준
Agent	`.md` 프론트매터	자동 선택 기준
MCP Tool	서버 코드에 정의	도구 선택 기준

11. 프로젝트 Skill vs 전역 Skill

저장 위치

bash
# 프로젝트 Skill (이 프로젝트에서만)
/프로젝트경로/.claude/skills/스킬이름/SKILL.md

# 전역 Skill (모든 프로젝트에서)
~/.claude/skills/스킬이름/SKILL.md

전역 Skill 주의사항

전역 Skill은 모든 프로젝트에서 description 매칭되므로 주의 필요:

전역 Skill: "리들 발행. 글 올리기, 포스팅..."
        ↓
다른 프로젝트에서: "이 글 포스팅해줘"
        ↓
Claude: description 매칭됨! → Skill 로드
        ↓
엉뚱한 프로젝트에서 riddle-publish.ts 실행 시도 💥

전역 vs 프로젝트 선택 기준

전역 Skill로 적합:

모든 프로젝트에서 동일하게 쓰는 것
프로젝트 경로에 의존하지 않는 것
예: 커밋 메시지 스타일, 코드 리뷰 체크리스트, 공통 코딩 컨벤션

프로젝트 Skill로 적합:

특정 스크립트 실행 (riddle-publish.ts)
특정 서버 배포
특정 DB 접근
특정 API 호출

12. Agent + Skills 조합

Agent가 여러 Skill을 가질 수 있다

Agent 정의할 때 skills 필드로 연결:

markdown
---
name: riddle-writer
description: 리들 콘텐츠 작성 및 발행 전문가
skills: riddle-publish, markdown-style
---

# 리들 작성 전문가

당신은 리들 콘텐츠를 작성하고 발행하는 전문가입니다.

이 Agent가 활성화되면 관련 Skill들도 함께 로드됨.

구조

┌─────────────────────────────────┐
│  Agent: riddle-writer           │
│  ├─ 역할 정의 (프롬프트)         │
│  ├─ Skill: riddle-publish       │ ← 발행 방법
│  ├─ Skill: markdown-style       │ ← 스타일 가이드
│  └─ Tools: Read, Write, Bash    │ ← 실행 도구
└─────────────────────────────────┘

13. AI 서비스의 본질

Genspark, GPTs 같은 서비스들

결국 이런 서비스들이 하는 것:

"여행 플래너" Agent
├─ Skill: 항공권 검색
├─ Skill: 호텔 예약
├─ Skill: 일정 최적화
├─ Skill: 현지 맛집 추천
└─ Tools: 웹 검색, API 호출

**잘 정의된 역할(Agent) + 기능 모음(Skills) + 도구(Tools)**를 패키징한 것.

공식

AI 서비스 = 잘 조합된 Agent
         = 역할 정의 + Skills + Tools

개념	역할	비유
Agent	전문가 정체성	"나는 여행 플래너야"
Skill	특정 능력/지식	"항공권 검색할 줄 알아"
Tool	실행 수단	"검색 API 호출할 수 있어"

(초보) 대체 agent, agent 하는데 그놈의 agent가 모에요? skill 은?

Claude Code의 Agent와 Skill 개념 정리

1. Agent란?

핵심 개념

Agent의 구성 요소

Agent vs 직접 프롬프팅

Agent의 한계

2. Skill이란?

핵심 개념

Skill의 특징

3. Agent vs Skill 비교

언제 뭘 만들까?

4. Agent 만드는 방법

방법 1: 명령어 사용

방법 2: 직접 파일 생성

주요 설정 옵션

5. 도구(Tools)

기본 제공 도구들 (Claude Code 내장)

도구 확장: MCP

6. 기본 제공 Agent 유형

7. 실제 Agent 예시

배포 전문가

에러 해결사

8. 팀과 공유하기

9. 핵심 요약

10. Description의 중요성

Description = 자동 선택의 핵심

Description 잘 쓰는 법

MCP도 같은 원리

11. 프로젝트 Skill vs 전역 Skill

저장 위치

전역 Skill 주의사항

전역 vs 프로젝트 선택 기준

12. Agent + Skills 조합

Agent가 여러 Skill을 가질 수 있다

구조

13. AI 서비스의 본질

Genspark, GPTs 같은 서비스들

공식

답변 1개

(초보) 대체 agent, agent 하는데 그놈의 agent가 모에요? skill 은?

Claude Code의 Agent와 Skill 개념 정리

1. Agent란?

핵심 개념

Agent의 구성 요소

Agent vs 직접 프롬프팅

Agent의 한계

2. Skill이란?

핵심 개념

Skill의 특징

3. Agent vs Skill 비교

언제 뭘 만들까?

4. Agent 만드는 방법

방법 1: 명령어 사용

방법 2: 직접 파일 생성

주요 설정 옵션

5. 도구(Tools)

기본 제공 도구들 (Claude Code 내장)

도구 확장: MCP

6. 기본 제공 Agent 유형

7. 실제 Agent 예시

배포 전문가

에러 해결사

8. 팀과 공유하기

9. 핵심 요약

10. Description의 중요성

Description = 자동 선택의 핵심

Description 잘 쓰는 법

MCP도 같은 원리

11. 프로젝트 Skill vs 전역 Skill

저장 위치

전역 Skill 주의사항

전역 vs 프로젝트 선택 기준

12. Agent + Skills 조합

Agent가 여러 Skill을 가질 수 있다

구조

13. AI 서비스의 본질

Genspark, GPTs 같은 서비스들

공식

답변 1개