AI 코딩 어시스턴트의 Skill 시스템: RAG 없이 지식을 주입하는 법

RAG 파이프라인 없이 AI에 지식을 주입한다?

RAG(Retrieval-Augmented Generation)는 LLM에 외부 지식을 제공하는 표준 방식이었다. 문서를 청킹하고, 임베딩하고, 벡터 DB에 저장한 뒤, 질문이 들어오면 유사한 청크를 검색해서 컨텍스트에 넣는다. 효과적이지만 인프라 구축과 유지 비용이 만만치 않다.

그런데 AI 코딩 어시스턴트 영역에서는 다른 흐름이 생겼다. Claude Code, Cursor, GitHub Copilot 같은 도구들이 마크다운 파일 기반의 Skill/Rules 시스템으로 RAG 없이 도메인 지식을 주입하고 있다. 벡터 DB도, 임베딩 파이프라인도, 리랭킹 모델도 없다. 그냥 잘 정리된 텍스트 파일이다.

이 시리즈에서는 이 Skill 시스템이 어떻게 동작하는지, RAG 대비 어떤 장단점이 있는지, 그리고 효과적으로 구성하려면 어떻게 해야 하는지를 정리한다.

Skill 시스템이란

Skill은 AI 코딩 어시스턴트에게 지속적인 지침과 도메인 지식을 제공하는 마크다운 파일이다. 매번 프롬프트에 "우리 프로젝트는 TypeScript를 쓰고, 에러 핸들링은 이렇게 하고..."라고 반복하는 대신, 한 번 파일로 작성해두면 도구가 자동으로 컨텍스트에 주입한다.

도구별 구현

공통점은 모두 버전 관리 가능한 마크다운 파일이라는 것이다. Git으로 추적되고, PR로 리뷰되고, 팀 전체가 공유한다.

AGENTS.md: 벤더 중립 표준

2025년 말, Linux Foundation 산하에서 AGENTS.md 표준이 등장했다. 60,000개 이상의 오픈소스 프로젝트가 채택했고, Claude Code, OpenAI Codex, Google Jules, Cursor 등 25개 이상의 플랫폼에서 동작한다.

핵심 원칙:

• 필수 필드 없음 — 에이전트가 텍스트를 유연하게 파싱
• 근접성 기반 우선순위 — 편집 중인 코드에 가장 가까운 파일이 우선
• README.md는 사람용, AGENTS.md는 AI용으로 역할 분리

Claude Code의 Skill 아키텍처

Claude Code의 Skill 시스템이 가장 정교하다. 세 가지 레벨의 Progressive Disclosure로 동작한다.

3단계 컨텍스트 로딩

Level 1: 메타데이터 (~100토큰)

모든 Skill의 이름과 설명이 시스템 프롬프트에 항상 포함된다. Claude가 사용자 요청을 받으면 이 목록을 보고 어떤 Skill이 관련 있는지 LLM 추론으로 판단한다. 임베딩이나 분류기가 아니라 순수 언어 이해다.

Level 2: SKILL.md 로딩 (약 5,000토큰)

관련 Skill이 결정되면 해당 SKILL.md 파일 전체가 컨텍스트에 주입된다. 여기에 핵심 지침, 워크플로우, 규칙이 들어있다.

Level 3: 참조 파일 로딩 (필요할 때만)

SKILL.md가 참조하는 상세 문서(reference.md, examples.md, 스크립트 등)는 해당 서브태스크가 실행될 때만 로딩된다.

Skill 폴더 구조:
my-skill/
  SKILL.md           ← Level 2에서 로딩
  reference.md       ← Level 3에서 필요 시 로딩
  examples.md        ← Level 3에서 필요 시 로딩
  scripts/
    helper.py        ← Claude가 실행 가능

이 구조의 핵심은 Skill의 크기에 제한이 사실상 없다는 것이다. 참조 파일을 아무리 많이 달아도 실제로 필요한 것만 컨텍스트에 들어간다.

두 가지 Skill 유형

Reference Skill (참조형)

코딩 컨벤션, API 패턴, 아키텍처 결정 등 지식을 제공한다. 대화 컨텍스트에 함께 주입되어 Claude의 응답에 영향을 준다.

---
name: api-conventions
description: API 설계 패턴과 규칙
---
API 엔드포인트 작성 시:
- RESTful 명명 규칙 사용
- 일관된 에러 포맷 반환
- 요청 유효성 검증 포함

Task Skill (작업형)

배포, 커밋, 코드 리뷰 등 워크플로우를 정의한다. /skill-name으로 직접 호출한다.

---
name: deploy
description: 프로덕션 배포
context: fork
---
1. 테스트 실행
2. 빌드
3. 배포 대상에 푸시

Skill 저장 위치와 범위

RAG를 대체할 수 있는 이유

컨텍스트 윈도우의 확장

2023년 GPT-4의 컨텍스트는 ~8K 토큰이었다. 2025년 현재 Claude Sonnet은 200K 토큰, 일부 모델은 2M 토큰까지 지원한다. 200K 토큰이면 대략 15만 단어, 일반 기술 서적 1권 분량이다.

코딩 프로젝트의 핵심 지식(컨벤션, 아키텍처, API 문서)은 대부분 이 범위 안에 들어간다. 굳이 청킹하고 임베딩할 필요가 없다.

파일시스템 탐색이 벡터 검색을 대체

Claude Code는 RAG를 전혀 사용하지 않는다. 대신 ripgrep, glob 패턴, 파일 읽기 같은 파일시스템 도구로 코드베이스를 직접 탐색한다. 정확한 키워드 매칭이 필요할 때는 임베딩 기반 유사도 검색보다 grep이 더 정확하다.

지시사항 > 검색된 청크

Skill이 RAG보다 효과적인 근본적 이유가 있다. Skill은 Claude가 어떻게 생각할지를 바꾸고, RAG는 Claude가 무엇을 알지를 바꾼다. 둘은 다른 추상화 레벨에서 동작한다.

코딩 컨벤션, 배포 절차, 아키텍처 결정 같은 절차적 지식은 청킹된 문서 조각보다 잘 정리된 지시사항이 훨씬 효과적이다:

• 지시사항은 큐레이션된 단일 진실의 원천이다
• 논리적 흐름과 맥락이 유지된다 (청킹은 이걸 파괴한다)
• 의사결정 트리, 예시, 엣지 케이스를 일관된 구조로 포함할 수 있다

인프라 비용 제로

RAG 파이프라인의 인프라 부담은 상당하다:

• Elasticsearch: 최소 128~256GB RAM
• 스키마 변경 시 재인덱싱: 48~72시간
• 청킹 → 임베딩 → 인덱싱 → 검색 → 리랭킹 — 각 단계가 에러를 복합적으로 누적

Skill은 마크다운 파일 몇 개다. Git으로 버전 관리하고, PR로 리뷰하면 끝이다.

점진적 지식 확장: Skill의 진짜 강점

Skill 시스템이 RAG를 대체할 수 있는 가장 근본적인 이유는 위에서 다룬 기술적 요인이 아니다. 지식이 프로젝트와 함께 유기적으로 성장한다는 점이다.

학습 루프: 한 번 가르치면 영원히 기억한다

RAG는 "문서를 넣으면 검색해서 알려주는" 정적 시스템이다. Skill은 다르다. 피드백을 통해 지식이 점진적으로 쌓이는 시스템이다.

AI가 실수 → 개발자가 교정 → 교정 내용을 Skill에 반영 → 같은 실수 반복 안 함

예를 들어, Claude가 git push --force를 실행했다고 하자. 개발자가 이를 교정하고, Skill에 "git push --force 금지, --force-with-lease 사용"을 추가한다. 이후 모든 세션, 모든 팀원의 Claude가 이 규칙을 따른다.

RAG로 같은 효과를 얻으려면? 문서를 작성하고, 청킹하고, 임베딩을 생성하고, 인덱스를 업데이트해야 한다. 피드백 루프의 마찰이 완전히 다르다.

Auto Memory: AI가 스스로 지식을 축적한다

Claude Code는 ~/.claude/projects/*/memory/MEMORY.md에 세션 간 학습 내용을 자동으로 기록할 수 있다. 프로젝트에서 반복적으로 발견되는 패턴, 디버깅 인사이트, 아키텍처 결정을 AI 스스로 정리하여 다음 세션에 활용한다.

세션 1: "이 프로젝트는 bun을 쓴다"를 학습 → MEMORY.md에 기록
세션 2: 자동으로 bun 명령어 사용 (npm/yarn 대신)
세션 3: 새로운 패턴 발견 → MEMORY.md 업데이트

이것은 사실상 자가 성장하는 지식 베이스다. RAG에서는 이런 자동 학습이 불가능하다. 누군가가 문서를 작성하고 파이프라인에 넣어야 한다.

코드와 지식의 공진화

Skill의 가장 강력한 특성은 코드와 같은 저장소에 살고, 같은 라이프사이클을 따른다는 것이다.

• 코드가 변하면 Skill도 같은 PR에서 업데이트된다
• 브랜치에서 새 규칙을 실험하고, 머지하면 전체 팀에 적용된다
• Git 히스토리가 곧 지식의 진화 기록이다

git log --oneline .claude/skills/
# a1b2c3d API v3 마이그레이션에 맞춰 에러 핸들링 규칙 업데이트
# d4e5f6g Kubernetes 배포 추가 후 deploy Skill 업데이트
# g7h8i9j 초기 프로젝트 설정

RAG의 지식은 코드와 별도 시스템에 존재한다. 코드를 리팩터링해도 RAG 문서는 자동으로 따라오지 않는다. 시간이 지나면 코드와 지식 사이에 괴리가 생긴다.

계층적 지식 상속

Skill은 기업 → 개인 → 프로젝트 순으로 계층적으로 쌓인다:

1. 기업 레벨: "모든 프로젝트에서 시크릿을 커밋하지 마라"
2. 개인 레벨: "나는 항상 한국어로 커밋 메시지를 쓴다"
3. 프로젝트 레벨: "이 프로젝트는 Tailwind v4를 쓴다"

각 레벨이 독립적으로 성장하고, 하위 레벨이 상위 레벨을 자동으로 상속한다. 새 프로젝트를 시작해도 기업/개인 레벨의 축적된 지식이 즉시 적용된다.

한계: RAG가 여전히 필요한 경우

Skill 시스템이 만능은 아니다. RAG vs Skill: 언제 무엇을 쓸까에서 자세히 다루지만, 핵심 한계를 짚으면:

• 대규모 문서 코퍼스: 수백만 건의 문서는 어떤 컨텍스트 윈도우에도 들어가지 않는다
• 동적 데이터: 매일 바뀌는 정책, 제품 문서, 지원 티켓은 정적 파일로 관리하기 어렵다
• 시맨틱 검색: "매출 성장 동인"처럼 다양한 표현으로 된 정보를 찾으려면 임베딩 기반 유사도 검색이 필요하다
• 사실 근거(Grounding): 규정 준수가 중요한 도메인(법률, 의료, 금융)에서는 RAG의 인용 추적이 필수다

이 시리즈의 구성

이 시리즈는 3개의 추가 글로 구성된다:

RAG vs Skill: 언제 무엇을 쓸까

RAG와 Skill 시스템을 체계적으로 비교한다. 지식의 유형(절차적 vs 사실적), 규모, 변경 빈도에 따른 선택 기준 프레임워크를 제시하고, 두 접근법을 함께 사용하는 하이브리드 패턴도 다룬다.

→ RAG vs Skill: 언제 무엇을 쓸까

효과적인 Skill 구성 전략과 팁

실제로 Skill을 구성할 때 알아야 할 실전 팁을 정리한다. CLAUDE.md 작성법, Skill 폴더 구조 설계, 팀 공유 전략, 그리고 AGENTS.md를 활용한 크로스 도구 표준화까지.

→ 효과적인 Skill 구성 전략과 팁

Skill을 점진적으로 키우는 법

컨텍스트 파이프라이닝 설계, Claude A/B 패턴을 활용한 정제 루프, Auto Memory에서 Skill로의 승격 기준, 그리고 실전 정제 사이클 예시까지. Skill을 작게 시작해서 체계적으로 키워나가는 워크플로우를 다룬다.

→ Skill을 점진적으로 키우는 법

RAG와 Skill 너머의 도구들

MCP, A2A, Context Engineering, 영속 메모리, 멀티에이전트 프레임워크까지. RAG와 Skill을 넘어 AI 에이전트 생태계를 구성하는 전체 스택을 정리한다.

→ RAG와 Skill 너머: AI 에이전트 도구 총정리

Superpowers: 오픈소스 Skill 프레임워크

58K+ 스타의 오픈소스 Skill 프레임워크. 14개 내장 Skill로 브레인스토밍부터 TDD, 코드 리뷰까지 AI 코딩 워크플로우를 체계화하는 방법을 소개한다.

→ Superpowers로 AI 코딩 어시스턴트 200% 활용하기

References

• Claude Code Skills — Claude Code Docs
• Manage Claude's Memory — Claude Code Docs
• Equipping Agents for the Real World with Agent Skills — Anthropic Blog
• GitHub Copilot Custom Instructions — GitHub Docs
• AGENTS.md Specification