스킬 기반 Agent 패턴

프로그레시브 디스클로저를 활용한 Agent 성능 최적화

LangChain이 공개한 AI 코딩 에이전트용 스킬 세트를 분석하고, 프로그레시브 디스클로저 패턴이 Agent 아키텍처 설계에 주는 시사점을 정리한다.

Agent
Architecture
LangChain
저자

Kwangmin Kim

공개

2026년 03월 12일

1 배경

  • LangChain이 Claude Code 같은 AI 코딩 에이전트의 성능을 향상시키기 위한 스킬(Skill) 세트를 공개했다 (11개의 LangChain 스킬 + 3개의 LangSmith 스킬)

  • 공개된 스킬을 활용한 실험에서, 기존 방식 대비 4~5배 이상의 성능 향상이 관찰되었다.

  • LangChain 관련 작업 통과율: 25% → 95%

  • LangSmith 관련 작업 통과율: 17% → 92%

모델 자체를 변경하지 않고, 올바른 컨텍스트를 올바른 시점에 제공하는 것만으로 성능이 4~5배 향상된 사례이다.

2 스킬(Skill)이란

“필요할 때만 꺼내 쓰는 전문 매뉴얼”로, 마크다운 파일과 스크립트로 구성된다.

  • LangChain 스킬 (11종): 에이전트 루프, Human-in-the-Loop, Deep Agents 활용법
  • LangSmith 스킬 (3종): 트레이싱, 데이터셋 관리, 에이전트 평가

2.1 스킬의 구성 요소

skill/
├── README.md          # 스킬 설명 (마크다운)
├── instructions.md    # Agent가 참조할 매뉴얼
└── scripts/           # 실행 가능한 스크립트

3 프로그레시브 디스클로저 (Progressive Disclosure)

핵심 원리는 모든 정보를 한꺼번에 주지 않고, 필요한 시점에 필요한 정보만 동적으로 로드하는 것이다.

3.1 기존 방식의 문제

[모든 문서를 프롬프트에 포함] → 컨텍스트 과부하 → 성능 저하

3.2 스킬 기반 방식

[태스크 분석] → [관련 스킬만 선택] → [해당 스킬 문서 로드] → 높은 정확도

3.3 스킬 수 관리

스킬 수 결과
너무 적음 (< 5) 커버리지 부족
적정 (~12개) 최적 성능
너무 많음 (20+) 선택 오류 증가, 성능 저하
중요

스킬이 많다고 좋은 것이 아니다. 유사한 스킬이 많으면 Agent가 잘못된 스킬을 선택할 확률이 높아진다.

4 Agent 아키텍처 설계에 주는 시사점

4.1 1. 컨텍스트 관리가 Agent 성능의 핵심이다

모델 성능에만 의존하지 말고, 도메인별 스킬(문서 + 도구)을 잘 설계해서 필요할 때만 주입하는 구조가 중요하다.

4.2 2. 스킬 패턴은 Agent 아키텍처의 표준이 되고 있다

  • Claude Code: /commit, /simplify 등의 스킬 시스템 사용
  • LangChain: 마크다운 + 스크립트 기반 스킬
  • 가볍고 확장 가능한 형태로 Agent에 도메인 전문성을 부여하는 실용적 방법

4.3 3. RAG와의 차이점

구분 RAG 스킬 기반
정보 형태 비정형 문서 청크 구조화된 매뉴얼 + 스크립트
검색 방식 유사도 기반 검색 태스크 기반 선택
적합한 상황 대규모 비정형 지식베이스 명확한 도메인 작업 절차
정확도 검색 품질에 의존 사전 설계된 정확한 컨텍스트

5 배포된 것과 설치 방법

5.1 배포 형태

GitHub 오픈소스 레포지토리로 공개되었다:

실체는 마크다운 파일 + 스크립트 모음이다. Claude Code의 스킬 시스템에 등록되면, Agent가 관련 작업 시 자동으로 해당 문서를 참조한다.

5.2 설치

# LangChain 스킬 전체 설치 (글로벌)
npx skills add langchain-ai/langchain-skills --agent claude-code --skill '*' --yes --global

# LangSmith 스킬 추가
npx skills add langchain-ai/langsmith-skills --agent claude-code --skill '*' --yes --global

또는 레포를 클론해서 설치할 수도 있다:

git clone https://github.com/langchain-ai/langchain-skills.git
cd langchain-skills
./install.sh --global

5.3 사용법

설치 후 별도 조작이 필요 없다. Claude Code에게 LangChain/LangGraph 관련 코드를 작성해달라고 하면, Agent가 자동으로 관련 스킬을 감지하여 해당 매뉴얼을 로드한다.

  • “LangGraph로 에이전트 만들어줘” → LangGraph 스킬 자동 로드
  • “LangSmith로 트레이싱 설정해줘” → LangSmith 스킬 자동 로드

5.4 지원 Agent

Claude Code 외에도 Cursor, Windsurf 등 Agent Skills 규격을 지원하는 코딩 에이전트에서 사용 가능하다.

항목 내용
배포 형태 GitHub 레포 (마크다운 + 스크립트)
설치 npx skills add 한 줄
사용 자동 (Agent가 알아서 로드)
대상 Agent Claude Code, Cursor, Windsurf 등
비용 무료 (오픈소스)

6 스킬 레포지토리 상세 분석

실제 langchain-skills 레포지토리를 분석한 결과를 정리한다.

6.1 레포지토리 구조

langchain-skills/
├── README.md              # 설치 가이드
├── install.sh             # Claude Code / Deep Agents CLI용 설치 스크립트
├── pyproject.toml
└── config/
    ├── AGENTS.md           # 전체 스킬 목록 & 사용 가이드 (시스템 프롬프트)
    └── skills/             # 11개 SKILL.md 파일
        ├── framework-selection/
        ├── langchain-dependencies/
        ├── langchain-fundamentals/
        ├── langchain-middleware/
        ├── langchain-rag/
        ├── langgraph-fundamentals/
        ├── langgraph-human-in-the-loop/
        ├── langgraph-persistence/
        ├── deep-agents-core/
        ├── deep-agents-memory/
        └── deep-agents-orchestration/

각 스킬 폴더에는 SKILL.md 파일 하나가 들어있다. 이 파일이 Agent에게 주입되는 시스템 프롬프트 역할을 한다.

6.2 3개 프레임워크의 계층 구조

스킬 분석 결과, LangChain/LangGraph/Deep Agents는 경쟁 관계가 아니라 계층 구조임을 알 수 있다.

┌─────────────────────────────────────────┐
│              Deep Agents                │  ← 최상위: 배터리 포함
│   (계획, 메모리, 스킬, 파일관리)          │
├─────────────────────────────────────────┤
│               LangGraph                 │  ← 오케스트레이션: 그래프, 루프, 상태
│    (노드, 엣지, 상태, 퍼시스턴스)         │
├─────────────────────────────────────────┤
│               LangChain                 │  ← 기초: 모델, 도구, 체인
│      (모델, 도구, 프롬프트, RAG)          │
└─────────────────────────────────────────┘

상위 계층을 선택해도 하위 계층을 자유롭게 사용할 수 있다.

6.3 프레임워크 선택 가이드

질문 Yes No
서브태스크 분해, 파일 관리, 영구 메모리, 온디맨드 스킬이 필요한가? Deep Agents 다음 질문
루프, 동적 분기, 병렬 처리, HITL, 커스텀 상태가 필요한가? LangGraph 다음 질문
입력 → 도구 실행 → 결과 반환의 단순 Agent인가? LangChain (create_agent) 다음 질문
순수 모델 호출, 체인, 검색 파이프라인인가? LangChain (LCEL / chain) -

6.4 11개 스킬 상세 요약

6.4.1 Getting Started (2개)

framework-selection — 프레임워크 비교 레퍼런스

  • LangChain vs LangGraph vs Deep Agents 선택 기준 제공
  • 의사결정 테이블, 각 프레임워크 프로파일, 혼합 사용 패턴 포함

langchain-dependencies — 패키지 버전 관리 레퍼런스

  • LangChain 1.0이 현재 LTS (0.3은 레거시, 신규 프로젝트 금지)
  • Python 3.10+, Node.js 20+ 필수
  • langchain-community는 semver를 따르지 않음 → 전용 패키지 사용 권장
  • Python/TypeScript 양쪽 최소 의존성 템플릿 제공

6.4.2 LangChain (3개)

langchain-fundamentals — Agent 생성 기초

  • create_agent()가 유일한 공식 Agent 생성 방법 (다른 방식은 deprecated)
  • @tool 데코레이터, middleware 패턴, structured output
  • 모델 문자열 ("anthropic:claude-sonnet-4-5") 또는 인스턴스 전달

langchain-middleware — HITL 승인 및 커스텀 미들웨어

  • HumanInTheLoopMiddleware: 위험한 도구 호출 전 인간 승인
  • Command(resume=...): 승인/편집/거부 후 실행 재개
  • 도구별 다른 HITL 정책 설정 가능
  • checkpointer + thread_id 필수

langchain-rag — RAG 파이프라인

  • Load → Split → Embed → Store → Retrieve → Generate
  • Vector Store 선택: InMemory(테스트), FAISS(로컬), Chroma(개발), Pinecone(프로덕션)
  • 청크 크기 500~1500, 오버랩 10~20% 권장
  • 인덱싱과 검색에 동일한 임베딩 모델 사용 필수

6.4.3 LangGraph (3개)

langgraph-fundamentals — StateGraph 기초

  • StateGraph, 노드, 엣지, Command, Send API
  • State 설계: reducer 없으면 마지막 값으로 덮어씀 (Annotated[list, operator.add] 사용)
  • 노드는 partial update dict만 반환 (전체 state 반환 금지)
  • Send로 병렬 fan-out/fan-in 처리
  • 스트리밍 모드: values, updates, messages, custom

langgraph-human-in-the-loop — 인터럽트 & 재개

  • interrupt(value): 실행 일시정지, 값을 호출자에게 전달
  • Command(resume=value): 재개, interrupt()의 반환값이 됨
  • resume 시 노드가 처음부터 재실행됨 → interrupt 전 코드는 멱등성 필수
  • 검증 루프: while 문 안에서 interrupt → 유효하지 않으면 재요청
  • 병렬 인터럽트: interrupt ID → resume value 매핑으로 일괄 처리

langgraph-persistence — 체크포인터 & 메모리

  • 단기 메모리(checkpointer): 스레드 단위 대화 히스토리
  • 장기 메모리(Store): 크로스 스레드 사용자 선호도
  • 체크포인터 선택: InMemorySaver(개발) → PostgresSaver(프로덕션)
  • 타임 트래블: get_state_history()로 과거 체크포인트 탐색 및 포크
  • 서브그래프 체크포인터 스코핑: False(퍼시스턴스 없음) / None(인터럽트만) / True(멀티턴 메모리)

6.4.4 Deep Agents (3개)

deep-agents-core — Deep Agent 아키텍처

  • create_deep_agent(): 내장 미들웨어를 자동 제공하는 Agent 생성
  • 내장 미들웨어: TodoList, Filesystem, SubAgent (항상 활성)
  • 선택 미들웨어: Skills, Memory, HumanInTheLoop
  • SKILL.md 포맷: YAML frontmatter (name, description) 필수
  • 스킬은 서브에이전트에 상속되지 않음 → 명시적으로 전달해야 함

deep-agents-memory — 백엔드 & 퍼시스턴스

  • StateBackend: 임시 (스레드 종료 시 소멸)
  • StoreBackend: 영구 (크로스 스레드 접근 가능)
  • FilesystemBackend: 로컬 개발용 실제 디스크 접근
  • CompositeBackend: 경로별 다른 백엔드 라우팅 (/memories/ → StoreBackend, 나머지 → StateBackend)
  • 프로덕션에서 InMemoryStore 대신 PostgresStore 사용

deep-agents-orchestration — 서브에이전트 & 계획

  • task 도구: 메인 Agent가 서브에이전트에 작업 위임
  • 서브에이전트는 stateless → 한 번의 호출에 완전한 지시를 제공해야 함
  • write_todos: 멀티스텝 태스크 계획 및 추적
  • HITL: interrupt_on으로 도구별 승인 설정, approve/edit/reject 지원

6.5 스킬 문서의 공통 패턴

모든 SKILL.md는 동일한 구조를 따른다:

---
name: 스킬-이름
description: "언제 이 스킬을 호출해야 하는지 명시"
---

<overview>개요</overview>
<when-to-use>사용 시점 (비교 테이블)</when-to-use>
<ex-기능명>코드 예시 (Python + TypeScript)</ex-기능명>
<fix-흔한실수>잘못된 코드 → 올바른 코드</fix-흔한실수>
<boundaries>설정 가능한 것 / 불가능한 것</boundaries>
노트

이 구조 자체가 프로그레시브 디스클로저의 실제 구현이다. Agent는 description을 보고 스킬을 선택하고, 선택된 스킬의 overview → 예시 → fix 순서로 필요한 깊이만큼 읽는다.

6.6 주요 API 변경점

스킬에서 반복적으로 강조하는 변경 사항들:

변경 사항 상세
create_agent() 필수 다른 Agent 생성 방식은 모두 deprecated
LangChain 1.0 LTS 0.3은 레거시, 신규 프로젝트 금지
langchain-community 주의 semver 미준수, 전용 패키지 사용 권장
TavilySearchResults deprecated TavilySearch 사용
interrupt() 전 코드 재실행 resume 시 노드 처음부터 재실행됨
Command(resume=...) invoke 입력으로 사용하는 유일한 Command 패턴

7 자체 Agent 개발 시 적용 방법

7.1 직접적인 도구인가?

LangChain이 공개한 스킬은 Claude Code가 LangChain 코드를 더 잘 작성하도록 돕는 코딩 보조 도구이다. 자체 Agent의 런타임 성능과 직접적인 관계는 없다. 다만, LangChain 기반 Agent를 개발하는 과정에서 Claude Code의 코딩 정확도가 올라가는 효과가 있다.

7.2 가져갈 수 있는 것은 아키텍처 패턴이다

자체 RAG/Agent 개발 시 다음과 같은 하이브리드 구조를 설계할 수 있다:

[사용자 질의]
    ↓
[태스크 분류기] → 명확한 작업 → [스킬 기반 처리]
    ↓
  모호한 질의 → [RAG 기반 검색 + 응답]

7.3 실전 적용 가이드

  1. 도메인별 스킬 문서(마크다운)를 미리 작성한다
  2. 태스크 분류기를 통해 어떤 스킬을 로드할지 결정한다
  3. 스킬 수는 ~12개 이내로 관리한다
  4. 스킬로 커버되지 않는 질의는 RAG로 폴백한다
  5. Docker 기반 테스트 환경에서 스킬 유무에 따른 성능을 비교 평가한다
힌트

전체 문서를 RAG로 검색하는 대신, 태스크별 스킬 문서를 미리 구조화해서 선택적으로 주입하는 하이브리드 방식이 효과적이다.

8 참고

Subscribe

Enjoy this blog? Get notified of new posts by email: