diff --git a/docs/troubleshooting/250721_happybell80_이메일스킬HTTP분리및아키텍처전환.md b/docs/troubleshooting/250721_happybell80_이메일스킬HTTP분리및아키텍처전환.md
new file mode 100644
index 0000000..9282e2a
--- /dev/null
+++ b/docs/troubleshooting/250721_happybell80_이메일스킬HTTP분리및아키텍처전환.md
@@ -0,0 +1,113 @@
+# 이메일 스킬 HTTP 분리 및 아키텍처 전환
+
+**날짜**: 2025-07-21  
+**작업자**: happybell80 & Claude
+
+## 오후 3시 30분
+
+### 이메일 스킬 통합 문제 재발
+
+**배경**:
+- 7/18 작업 후 여전히 인증 문제 발생
+- `'AuthCredentialsProvider' object has no attribute 'get_credentials'` 에러
+
+**문제 분석**:
+1. skill_email: `FileCredentialsProvider` 사용 (파일 기반)
+2. rb10508_test: 새로 만든 `AuthCredentialsProvider` (API 기반)
+3. 인터페이스 불일치로 에러 발생
+
+**초기 해결 시도**:
+- FileCredentialsProvider로 전환
+- auth-server 토큰 폴더 마운트
+- 결과: 동기/비동기 문제 발생 (`object Err can't be used in 'await' expression`)
+
+## 오후 4시 00분
+
+### 근본적 아키텍처 문제 인식
+
+**문제점**:
+- "빠른 개발"이라며 direct import 방식 채택
+- 결과적으로 더 많은 시간 소요 (경로 문제, 동기/비동기 문제 등)
+- 로빙의 핵심 철학(독립성, 모듈성) 위배
+
+**결정**:
+- HTTP API 방식으로 전환
+- 스킬은 독립 서비스로 분리
+
+## 오후 5시 00분
+
+### skill-email HTTP 서비스 구축
+
+**구현 내용**:
+1. 포트 변경: 8100 → 8501
+2. Dockerfile 및 docker-compose.yml 생성
+3. nginx 프록시 설정 추가 (`/skill-email/`)
+
+**rb10508_test 단순화**:
+```python
+# Before: 111줄의 복잡한 코드
+# After: 57줄의 단순한 HTTP 클라이언트
+class EmailSkill:
+    async def send_email(...):
+        response = await client.post(f"{self.base_url}/send", ...)
+        return response.json()
+```
+
+## 오후 6시 30분
+
+### API 엔드포인트 문제 해결
+
+**문제**:
+- skill_email에 `/messages` 엔드포인트 없음
+- rb10508_test가 404 에러 받지만 "안읽은 이메일이 없습니다"로 표시
+
+**해결**:
+1. skill_email에 `/messages` 엔드포인트 추가
+2. 에러 처리 개선
+
+## 오후 7시 00분
+
+### 토큰 파일 및 메타데이터 문제 해결
+
+**문제 1 - 토큰 파일**:
+- 서버: `test_gmail.json`만 존재
+- 코드: `happybell80_gmail.json` 찾음
+- 해결: user_id를 "test"로 변경
+
+**문제 2 - 메타데이터 누락**:
+- 모든 이메일이 "No subject", "Unknown"으로 표시
+- 원인: `get_recent_messages`가 ID만 반환
+- 해결: 각 메시지의 상세 정보 조회 추가
+
+## 오후 7시 30분
+
+### 최종 완성 및 테스트 성공
+
+**결과**:
+- 실제 이메일 제목, 보낸이, 날짜 표시
+- 완전한 HTTP API 기반 통신
+- 로빙과 스킬 독립성 확보
+
+**아키텍처 개선**:
+```
+기존: rb10508_test → (direct import) → skill_email
+개선: rb10508_test → (HTTP API) → skill-email:8501
+```
+
+## 교훈 및 성과
+
+### 교훈
+1. "빠른 개발"이 항상 빠르지 않음
+2. 아키텍처 원칙을 지키는 것이 장기적으로 이득
+3. 마이크로서비스는 처음부터 제대로 분리해야 함
+
+### 성과
+- 코드 48% 감소 (111줄 → 57줄)
+- 의존성 완전 제거
+- 독립적 배포 가능
+- 확장 가능한 구조 확립
+
+### CLAUDE.md 업데이트
+- 스킬 포트 범위: 8501-8599
+- HTTP API 통신 원칙 명시
+- 직접 import 금지 규칙 추가
\ No newline at end of file