Claude Code Skills & Agents: 전문가 팀을 내 손안에

Claude Code의 Skills와 **Agents(서브에이전트)**는 꼭 알아야 하는 기능이에요.

Skills는 Claude에게 추가 능력을 부여하는 거예요. Agents는 특화된 전문가를 호출하는 거고요. Planner Agent는 프로젝트 전체 구조를 설계하고, Architect는 기술 스택을 추천하고, Code Reviewer는 코드 리뷰를, Security Reviewer는 보안 취약점을 찾아줘요.

마치 시니어 개발자 팀을 고용한 것처럼 일할 수 있어요.

---

TL;DR

• Skills: Claude에게 새로운 능력을 부여하는 지식 패키지
• Agents: 특화된 작업을 수행하는 전문가 서브에이전트
• 빌트인 Agents: Explore (탐색), Plan (계획)
• 커스텀 Agents 생성 가능: /agents 명령으로 쉽게 생성
• 추천 리소스: affaan-m/everything-claude-code — 실전 검증된 configs

---

Skills란?

"Skills extend Claude's capabilities by packaging your expertise into composable resources for Claude, transforming general-purpose agents into specialized assistants." — Anthropic Engineering

Skills는 Claude에게 도메인 전문 지식을 주입하는 방법이에요. 폴더 + SKILL.md 파일 구조로 되어있고, Claude가 필요할 때 자동으로 로드합니다.

기본 구조

my-skill/
├── SKILL.md          ← 필수: 메타데이터 + 지침
├── templates/        ← 선택: 템플릿 파일들
├── scripts/          ← 선택: 실행 가능한 스크립트
└── examples/         ← 선택: 예시 파일들

SKILL.md 예시

---
name: tdd-workflow
description: Test-driven development methodology for writing robust code
---

# TDD Workflow

1. **RED**: Write failing tests first
2. **GREEN**: Implement minimal code to pass
3. **REFACTOR**: Improve code quality
4. Always aim for 80%+ test coverage
5. Never modify tests to make them pass

Progressive Disclosure

Skills의 핵심 원리는 **점진적 공개(Progressive Disclosure)**예요:

"Skills let Claude load information only as needed. The amount of context that can be bundled into a skill is effectively unbounded." — Anthropic Engineering

• 시작: 이름과 설명만 로드
• 필요 시: 전체 SKILL.md 로드
• 상세 필요 시: 추가 파일들 로드

컨텍스트 윈도우를 효율적으로 사용하면서도 무제한에 가까운 지식을 활용할 수 있어요.

빌트인 Skills

Anthropic이 제공하는 기본 Skills:

Skill 용도

PowerPoint	프레젠테이션 생성/편집
Excel	스프레드시트 + 수식
Word	문서 작성/편집
PDF	PDF 폼 채우기/생성

"Use Anthropic-created skills to have Claude read and generate professional Excel spreadsheets with formulas, PowerPoint presentations, Word documents, and fillable PDFs." — Anthropic News

---

Agents(서브에이전트)란?

"Subagents are separate agent instances that your main agent can spawn to handle focused subtasks." — Claude Agent SDK Docs

Agents는 특화된 작업을 수행하는 전문가예요. 메인 Claude가 복잡한 작업을 만나면 적절한 Agent에게 위임합니다.

왜 필요한가?

1. 컨텍스트 격리: 서브에이전트는 별도 컨텍스트 사용 → 메인 컨텍스트 깔끔 유지
2. 병렬 처리: 여러 에이전트 동시 실행 가능
3. 전문화: 각 에이전트에 맞춤 프롬프트와 도구 제한

"Subagents use their own isolated context windows, and only send relevant information back to the orchestrator, rather than their full context." — Anthropic Engineering

빌트인 Agents

Claude Code에 기본 내장된 에이전트들:

Agent 용도 특징

Explore	코드베이스 탐색/검색	Read-only, 빠른 탐색
Plan	계획 수립을 위한 리서치	Plan Mode에서 자동 사용

"Claude delegates to Explore when it needs to search or understand a codebase without making changes. This keeps exploration results out of your main conversation context." — Claude Code Docs

커스텀 Agent 만들기

/agents 명령으로 쉽게 만들 수 있어요:

# Claude Code에서
> /agents
# → Create new agent 선택
# → User-level 또는 Project-level 선택
# → Generate with Claude로 자동 생성

Agent 파일 구조

---
name: code-reviewer
description: Reviews code for quality, security, and maintainability
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer. Analyze code for:
- Security vulnerabilities
- Performance issues
- Code style consistency
- Best practices violations

Provide specific, actionable feedback with code examples.

Agent 저장 위치

위치 범위

~/.claude/agents/	사용자 전역 (모든 프로젝트)
.claude/agents/	프로젝트 전용

---

실전 활용: everything-claude-code

실전에서 검증된 configs를 원한다면 affaan-m/everything-claude-code 레포를 추천해요.

"Won the Anthropic x Forum Ventures hackathon in Sep 2025... These configs are battle-tested across multiple production applications." — affaan-m

포함된 Agents

Agent 역할

planner.md	기능 구현 계획 수립
architect.md	시스템 설계, 기술 스택 결정
tdd-guide.md	테스트 주도 개발 가이드
code-reviewer.md	코드 품질/보안 리뷰
security-reviewer.md	보안 취약점 분석
build-error-resolver.md	빌드 에러 해결
e2e-runner.md	Playwright E2E 테스트
refactor-cleaner.md	데드 코드 정리
doc-updater.md	문서 동기화

포함된 Skills

Skill 내용

coding-standards.md	언어별 베스트 프랙티스
backend-patterns.md	API, DB, 캐싱 패턴
frontend-patterns.md	React, Next.js 패턴
tdd-workflow/	TDD 방법론
security-review/	보안 체크리스트

설치 방법

# 레포 클론
git clone https://github.com/affaan-m/everything-claude-code.git

# agents 복사 (사용자 전역)
cp -r everything-claude-code/agents/* ~/.claude/agents/

# skills 복사 (사용자 전역)
cp -r everything-claude-code/skills/* ~/.claude/skills/

# 또는 프로젝트별로 복사
cp -r everything-claude-code/agents/* .claude/agents/
cp -r everything-claude-code/skills/* .claude/skills/

사용 예시

# Planner Agent에게 기능 설계 요청
> "Use the planner agent to design the user authentication feature"

# Code Reviewer로 리뷰 요청
> "Have the code-reviewer agent review src/auth/"

# Security Reviewer로 보안 검토
> "Ask security-reviewer to analyze our API endpoints"

---

또 다른 추천: wshobson/agents

더 방대한 컬렉션을 원한다면 **wshobson/agents**도 있어요:

• 108개 전문 Agents
• 129개 Skills
• 72개 플러그인
• 15개 워크플로우 오케스트레이터

"A comprehensive production-ready system combining 108 specialized AI agents, 15 multi-agent workflow orchestrators, 129 agent skills." — wshobson/agents

---

Skills vs Agents 비교

구분 Skills Agents

역할	지식/방법론 제공	작업 실행
비유	매뉴얼, 가이드북	전문가, 팀원
로드 시점	필요할 때 자동	명시적 호출 또는 자동 위임
컨텍스트	메인과 공유	별도 격리
예시	TDD 방법론, 코딩 표준	Code Reviewer, Security Auditor

함께 사용하면 더 강력

[사용자 요청]
     ↓
[메인 Claude]
     ↓
[Skills 로드: tdd-workflow]  ←  방법론 참조
     ↓
[Agent 위임: tdd-guide]      ←  실제 작업 수행
     ↓
[결과 반환]

---

Agent 작성 팁

1. 명확한 description

---
name: security-reviewer
description: Analyzes code for security vulnerabilities including XSS, SQL injection, auth issues, and sensitive data exposure
---

Claude가 언제 이 에이전트를 사용할지 결정하는 핵심이에요.

2. 도구 제한

---
tools: Read, Grep, Glob  # Bash 제외 → 읽기 전용
---

"A doc-reviewer subagent might only have access to Read and Grep tools, ensuring it can analyze but never accidentally modify your documentation files." — Claude Agent SDK Docs

3. 적절한 모델 선택

---
model: sonnet  # 빠른 분석 작업
# model: opus  # 복잡한 추론 필요 시
---

4. 구체적인 지침

You are a senior code reviewer at a Fortune 500 company.

## Review Checklist
- [ ] No hardcoded secrets
- [ ] Input validation on all endpoints
- [ ] Error handling with proper logging
- [ ] SQL injection prevention
- [ ] XSS protection

## Output Format
For each issue:
1. File and line number
2. Severity (Critical/High/Medium/Low)
3. Description
4. Suggested fix with code

---

주의사항

컨텍스트 관리

"Critical: Don't enable all MCPs at once. Your 200k context window can shrink to 70k with too many tools enabled." — affaan-m

• 필요한 것만 활성화
• 프로젝트별로 다른 설정 사용

보안

"Skills provide Claude with new capabilities through instructions and code... a malicious Skill can direct Claude to invoke tools or execute code in ways that don't match the Skill's stated purpose." — Claude Docs

• 신뢰할 수 있는 소스만 사용
• 설치 전 내용 검토

서브에이전트 제한

"Subagents cannot spawn other subagents." — Claude Code Docs

복잡한 체이닝이 필요하면 메인 Claude가 조율해야 해요.

---

체크리스트

시작하기

• [ ] everything-claude-code 클론
• [ ] 필요한 agents를 ~/.claude/agents/에 복사
• [ ] 필요한 skills를 ~/.claude/skills/에 복사

활용하기

• [ ] Planner Agent로 기능 설계
• [ ] Architect Agent로 기술 스택 결정
• [ ] Code Reviewer로 품질 검토
• [ ] Security Reviewer로 보안 검토

고급

• [ ] 프로젝트 맞춤 커스텀 Agent 생성
• [ ] 팀 공유용 Skills 작성
• [ ] 워크플로우 자동화 구성

---

마무리

Skills와 Agents는 Claude Code를 단순한 코딩 도우미에서 전문가 팀으로 업그레이드해줘요.

기억하세요:

• Skills = 지식 주입 (어떻게 해야 하는지)
• Agents = 작업 위임 (대신 해줘)
• **everything-claude-code**에서 시작하세요
• 필요한 것만 설치해서 컨텍스트 절약
• 신뢰할 수 있는 소스만 사용

"Skills extend Claude Code with your team's expertise and workflows... Claude loads them automatically when relevant." — Anthropic

처음엔 기본 Agents로 시작하고, 점점 팀 워크플로우에 맞는 커스텀 Agents를 만들어가세요. 생산성이 완전히 달라집니다.

---

참고 자료

Anthropic 공식

• Introducing Agent Skills — Anthropic News
• Equipping Agents with Skills — Anthropic Engineering
• Create Custom Subagents — Claude Code Docs
• Agent Skills Overview — Claude Docs

커뮤니티

• everything-claude-code — Anthropic 해커톤 우승자의 실전 configs
• wshobson/agents — 108 Agents, 129 Skills 컬렉션
• subagents.cc — 커뮤니티 Agent 디렉토리

---