[LLM 아키텍처 딥다이브] 프롬프트 엔지니어링의 종말? 'Claude Skills'가 컨텍스트 창을 다루는 우아하고도 무서운 방법

여러분, 솔직해져 봅시다. 최근 1~2년 사이 실무 프로젝트에 대형 언어 모델(LLM)을 도입하면서 가장 골치 아팠던 게 뭔가요? 저는 단연코 ‘프롬프트 비대증(System Prompt Bloat)’을 꼽습니다.

처음에는 귀여웠죠. 시스템 프롬프트에 “너는 10년 차 시니어 프론트엔드 개발자야. 간결하게 답해줘” 정도만 넣으면 마법처럼 작동했으니까요. 하지만 현실의 비즈니스는 그렇게 호락호락하지 않습니다. 사내 코딩 컨벤션 추가하고, “이 API는 Deprecated 됐으니 절대 쓰지 마” 같은 예외 조항 넣고, 시니어들이 겪은 트러블슈팅 사례까지 꾸역꾸역 집어넣다 보면 어느새 system_prompt.txt나 .cursorrules 파일은 수천, 수만 자의 거대한 텍스트 괴물이 되어버립니다.

결과는 어땠나요? 토큰 비용은 감당할 수 없이 폭발하고, 정작 중요한 지시사항은 ‘Lost in the middle(중간 누락)’ 현상으로 AI에게 가볍게 무시당하기 일쑤였습니다. 우리는 이 문제를 해결하겠다고 LangChain 같은 무거운 프레임워크를 욱여넣어 복잡한 RAG를 구축하거나, 얽히고설킨 에이전트 오케스트레이션 코드를 짰습니다. “AI를 편하게 쓰기 위해 AI보다 더 복잡하고 유지보수하기 힘든 글루 코드(Glue code)를 짜고 있는” 아이러니한 상황. 저 역시 최근까지 이 딜레마에서 허우적대며 깊은 회의감에 빠져 있었습니다.

그러다 최근 Anthropic이 조용히, 하지만 생태계에 치명적으로 내놓은 ‘Claude Skills(클로드 스킬)’ 아키텍처를 뜯어보고는 뒤통수를 한 대 세게 맞은 기분이 들었습니다. 처음엔 흔한 ‘GPTs’ 짝퉁이거나 단순한 커스텀 인스트럭션 템플릿인 줄 알았습니다. 하지만 코드를 까보니 아니더라고요. 이건 단순히 프롬프트를 저장해두는 기능이 아닙니다. 컨텍스트 창(Context Window)을 다루는 패러다임 자체를 완전히 뒤집어버린, 아주 우아하고도 무서운 접근이었습니다.

TL;DR Claude Skills는 거대한 텍스트 프롬프트를 무식하게 욱여넣는 대신, 파일 시스템 기반의 ‘점진적 노출(Progressive Disclosure)’과 샌드박스 코드 실행을 결합하여, LLM 스스로 필요한 순간에 필요한 전문 지식과 스크립트만 동적으로 꺼내 쓰도록 만든 모듈형 에이전트 아키텍처입니다.

본격적으로 뚜껑을 열어 아키텍처를 딥다이브 해봅시다. 기술적인 관점에서 Claude Skills가 기존의 방식과 결정적으로 다른 점은 ‘Push 모델’에서 ‘Pull 모델’로의 대전환입니다.

기존에는 우리가 AI에게 “네가 이걸 모를 수도 있으니, 일단 다 읽고 시작해!”라며 관련된 모든 컨텍스트를 프롬프트에 담아 ‘Push’ 했습니다. 하지만 Claude Skills는 철저하게 디렉토리(Directory) 기반의 모듈 시스템을 채택했습니다. 스킬은 단순한 텍스트 파일 하나가 아닙니다. 폴더 내부에 SKILL.md(핵심 지침), 파이썬 유틸리티 스크립트, 레퍼런스 JSON, 심지어 셸 스크립트까지 품고 있는 하나의 ‘독립된 실행 캡슐’입니다. 이 캡슐이 어떻게 컨텍스트를 최적화하는지 그 이면(Under the Hood)을 파헤쳐보면 기가 막힙니다.

1. 점진적 컨텍스트 로딩 (Progressive Disclosure) 로컬 환경에 50개의 스킬이 설치되어 있다고 가정해 봅시다. Claude는 대화가 시작될 때 이 스킬들의 내용을 전부 읽어 컨텍스트 윈도우를 낭비할까요? 절대 아닙니다. 초기 로딩 시점에는 오직 YAML Frontmatter에 정의된 name과 description (대략 스킬당 100토큰 내외)만 메타데이터 형태로 컨텍스트에 주입됩니다.

---
name: frontend-design
description: 유저가 웹 컴포넌트, 페이지, 또는 UI를 만들거나 수정해달라고 요청할 때 반드시 이 스킬을 사용하세요.
disable-model-invocation: false
---

사용자가 “새로운 대시보드 UI 좀 짜줘”라고 요청하면, Claude는 자신이 가진 도구(Tool) 목록 중 이 description과 매칭되는 스킬을 찾아냅니다. 그리고 내장된 Bash 도구를 이용해 스스로 파일 시스템에 접근하여 cat ~/.claude/skills/frontend-design/SKILL.md를 실행합니다. 그제야 비로소 구체적인 사내 UI 가이드라인과 규칙이 컨텍스트 창으로 ‘Pull’ 되는 겁니다. 필요할 때만 지식을 동적으로 지연 로딩(Lazy Loading)하는 완벽한 추상화입니다.

2. 코드 실행을 통한 극단적 토큰 다이어트 (Token Efficiency Magic) 제가 가장 감탄한 부분이자, 개발자들이 열광해야 할 포인트는 바로 여기입니다. 스킬 내부에 복잡한 데이터 유효성 검사 로직을 담은 파이썬 스크립트(validate_data.py)가 있다고 치죠. 과거에는 이 스크립트의 소스 코드 전체를 AI에게 보여주고 “이 코드의 로직에 맞춰서 데이터를 검증해봐”라고 해야 했습니다. 하지만 Claude Skills 환경에서는 스크립트 소스 코드 자체가 컨텍스트 창에 로드되지 않습니다. Claude는 샌드박스 환경에서 단순히 python validate_data.py input.json 이라는 명령어만 실행(Action)합니다. 그리고 스크립트가 뱉어낸 결과값(stdout/stderr), 즉 “Validation passed” 또는 특정 에러 메시지만 컨텍스트로 반환(Observation) 받습니다. 지시사항은 시스템 레벨에서 명확히 강제하면서도, 컨텍스트 윈도우와 토큰 비용은 극단적으로 절약하는 미친 효율성을 보여줍니다.

3. 보안과 권한 최소화 (Least Privilege) 제어 단순히 AI가 알아서 쓰게 두는 것을 넘어, 개발자가 통제권을 쥘 수 있는 장치도 훌륭합니다. 프론트매터의 disable-model-invocation: true 속성을 주면, AI가 마음대로 이 스킬을 발동시키지 못하게 막습니다. /deploy 나 /commit 처럼 시스템에 영향을 주는(Side-effect) 작업은 오직 사용자만이 명시적으로 호출할 수 있게 격리합니다. 반대로 allowed-tools: [Read, Grep, Glob]처럼 정의해두면, 해당 스킬이 활성화된 상태에서는 Claude가 절대 파일을 수정(Write)하거나 삭제할 수 없습니다. 보안 원칙을 에이전트 레벨에서 선언적으로 구현할 수 있게 된 것이죠.

아키텍처 비교 항목	기존 방식 (System Prompt / .cursorrules)	Claude Skills 아키텍처
컨텍스트 주입 방식	무조건 전체 텍스트 로드 (Push)	메타데이터 100토큰 로드 후 동적 읽기 (Pull)
토큰 및 비용 낭비	매우 심함 (안 쓰는 엣지 케이스 규칙도 매번 과금)	극도로 효율적 (필요한 순간, 필요한 파일만 과금)
코드 확장성	단일 파일이 거대해져 유지보수 및 버전 관리 불가	디렉토리 단위의 철저한 모듈화 (단일 책임 원칙)
실행 및 보안 능력	텍스트 기반의 권고안 수준, 강제성 약함	스크립트 실행 격리, allowed-tools로 권한 제어

자, 내부 원리가 훌륭한 건 알겠고, “그래서 당장 내 프로젝트에 어떻게 쓰는데?” 싶으실 겁니다. 현업에서 즉시 피부로 느낄 수 있는 실용적인 시나리오 두 가지를 제안합니다.

실무 시나리오 1: ‘영혼 없는 보일러플레이트’를 거부하는 맞춤형 UI 스캐폴딩 프론트엔드 개발자분들, AI가 짜주는 React 컴포넌트가 항상 똑같은 Tailwind 떡칠에 개성 없는 템플릿 형태라 지치셨죠? 당장 brand-ui-generator라는 스킬 디렉토리를 만들어보세요. SKILL.md에는 회사의 디자인 시스템 철학(예: “우리는 여백을 넓게 쓰고, 모서리는 둥글게 처리한다. 반드시 Radix UI를 기반으로 한다”)을 적습니다. 그리고 폴더 안에 tokens.json(사내 컬러 팔레트)과 check-a11y.sh(접근성 검사 셸 스크립트)를 넣습니다. 이제 대화창에 “결제 페이지 모달 만들어줘”라고 하면, Claude는 알아서 이 스킬을 발동시켜 tokens.json을 읽고 회사의 고유 컬러 코드를 적용한 뒤, 컴포넌트를 생성합니다. 그리고 스스로 check-a11y.sh를 돌려 접근성 위반 사항이 없는지 확인까지 마친 완성된 코드를 내놓습니다. 더 이상 “버튼 색깔은 #FF5500으로 해줘”라고 매번 구질구질하게 프롬프트를 입력할 필요가 없습니다.

실무 시나리오 2: 깐깐한 사수 빙의, ‘Automagical’ PR 리뷰어 자동화된 코드 리뷰를 위한 스킬(strict-pr-reviewer)도 강력합니다. 지시사항에 “우리 팀은 1. 비동기 처리 시 반드시 React Suspense Error Boundary를 고려하고, 2. 콘솔 로그가 남아있으면 안 되며, 3. 커밋 메시지는 Conventional Commits를 철저히 따른다”라고 명시합니다. Claude Code(CLI) 환경에서 코드 작성을 마치고 터미널에 /strict-pr-reviewer를 타이핑해 보세요. Claude가 현재 Git diff를 쓱 읽어오고, 로컬의 ESLint를 샌드박스에서 돌려본 뒤, 우리 팀의 규칙에 한 치의 오차도 없이 입각한 날카로운 PR 코멘트 초안을 마크다운으로 깔끔하게 생성해 줍니다. 단순한 문법 검사기를 넘어, 팀의 철학을 이해하는 시니어 사수를 로컬에 한 명 두는 것과 같습니다.

하지만, 칭찬만 늘어놓는다면 그건 테크 칼럼니스트가 아니라 영업 사원이겠죠. 세상에 은탄환(Silver Bullet)은 없듯, 이 녀석도 실무에 깊게 써보면 뼈아픈 한계와 트레이드오프(Trade-off)가 존재합니다. 진짜 장단점을 가감 없이 짚어보겠습니다.

불편한 진실 1: 느려터진 Thought-Action 루프의 답답함 점진적 노출과 파일 시스템 접근 방식은 아키텍처적으로는 정말 아름답지만, ‘속도(Latency)’라는 치명적인 대가를 치릅니다. 기존처럼 거대한 프롬프트 하나로 모든 걸 때려 넣었을 때는 LLM이 한 번의 스트리밍으로 쭉 답변을 생성하면 끝이었습니다. 하지만 Skills 환경에서는 Claude가 “이 스킬이 필요하군(Thought) -> Bash로 파일을 읽는다(Action) -> 내용을 파악했다(Observation) -> 스크립트를 돌려본다(Action) -> 결과를 분석한다(Observation) -> 최종 코드를 생성한다”라는 지루한 오케스트레이션 루프를 돕니다. 간단한 리팩토링 하나 시켰는데 혼자 터미널을 들락날락하며 한참을 생각하는 걸 보고 있으면, 한국인 특유의 ‘빨리빨리’ DNA가 요동칠 때가 한두 번이 아닙니다.

불편한 진실 2: ‘스킬 디스크립션’을 위한 또 다른 프롬프트 엔지니어링의 늪 이게 참 얄궂은 지점인데요. 스킬이 10개, 50개, 100개씩 늘어나면 (최근 GitHub의 claude-skills 오픈소스 저장소에는 이미 160개가 넘는 스킬이 올라와 있죠) Claude가 “대체 어떤 스킬을 언제 꺼내 써야 할지” 헷갈려 하며 충돌하기 시작합니다. 결국 YAML Frontmatter의 description을 얼마나 기가 막히게 작성하느냐에 따라 스킬의 발동 여부가 갈립니다. “이 스킬은 ~할 때 쓰세요”라고 너무 상세히 적으면 결국 초기 로딩 토큰을 낭비하게 되고, 너무 짧고 모호하게 적으면 스킬이 아예 발동하지 않는 ‘Discovery Failure(발견 실패)’를 겪게 됩니다. 지긋지긋한 프롬프트 지옥에서 벗어나려다 ‘메타-프롬프트 지옥(Meta-prompting Hell)’에 빠져버린 느낌이랄까요.

불편한 진실 3: 팀 단위 동기화(Sync)와 인프라 관리의 부재 Claude.ai(웹 뷰)와 Claude Code(CLI)를 오가며 작업할 때, 이 로컬 디렉토리 기반의 스킬들을 전사적으로 어떻게 관리하고 배포할 것인가에 대한 Admin 기능이 아직 턱없이 부족합니다. 결국 팀원들끼리 Github 레포지토리를 하나 파서 ~/.claude/skills/ 폴더를 심볼릭 링크나 Git Submodule로 동기화해야 하는 등, 인프라적인 번거로움(DevOps 오버헤드)이 고스란히 개발자 개인의 몫으로 남습니다.

글을 맺으며, 저는 이 기술이 시사하는 바가 단순한 기능 업데이트 그 이상이라고 생각합니다. 우리는 지금까지 AI를 ‘모든 것을 다 아는 전지전능한 챗봇’으로 대하며, 하나의 거대한 텍스트 상자 안에서 모든 문제를 꾸역꾸역 해결하려고 애썼습니다. 하지만 Claude Skills는 AI를 하나의 운영체제(OS)처럼 다루고, 스킬들을 그 위에서 돌아가는 ‘초소형 특수 목적 앱(Micro-agents)’으로 격상시켰습니다. 더욱이 이는 MCP(Model Context Protocol)라는 오픈 표준과 맞물려, 특정 플랫폼에 종속되지 않는 범용적인 에이전트 생태계로 진화하고 있습니다.

이러한 아키텍처의 거대한 변화는 현업 개발자인 우리에게 던지는 메시지가 명확합니다. 단순히 “리액트 코드를 짜줘”라고 명령하는 1차원적인 프롬프트 엔지니어링의 시대는 빠르게 저물고 있습니다. 앞으로의 시니어 개발자는 “우리의 AI 파트너가 어떤 도구(Tool)를 쥐고, 어떤 맥락(Context)을 어느 시점에 동적으로 열어보며, 어떤 제약 조건 속에서 안전하게 코드를 실행할지” 그 작업 환경 전체를 정교하게 설계하는 ‘에이전트 아키텍트(Agent Architect)’ 혹은 ‘컨텍스트 오케스트레이터(Context Orchestrator)’로 진화해야만 합니다.

당신의 로컬 환경에는 지금 어떤 스킬이 잠들어 있나요? 오늘 당장 의미 없이 비대해진 시스템 프롬프트를 쿨하게 지워버리고, 당신만의 철학과 팀의 룰이 담긴 작고 단단한 첫 번째 SKILL.md를 만들어보시길 권합니다. AI와 코드를 주고받으며 협업하는 감각 자체가 완전히 달라질 테니까요.

References

• https://github.com/alirezarezvani/claude-skills
• https://github.com/ComposioHQ/awesome-claude-skills
• https://docs.anthropic.com/en/docs/agents-and-tools/mcp