도입

아침 7시, 클로드 코드에 "모닝 커피 스킬 실행해 줘"라고 입력합니다. 에이전트는 캘린더를 확인하고, 프로젝트 관리 도구에서 이번 주 태스크를 가져오고, 분기 목표 진행률을 점검한 뒤, 오늘 하루의 시간표를 제안합니다. 동시에 다른 창에서는 "최근 유튜브 댓글 분석해 줘"라고 보냈고, 또 다른 창에서는 "팀 펄스 체크 돌려 줘"라고 보냈습니다.

세 개의 에이전트가 병렬로 작동합니다. 각각이 서로 다른 스킬을 실행하고 있습니다. 이 모든 것을 입력하는 데 걸린 시간은 1분 남짓이고, 수동으로 했다면 최소 25분은 소요되었을 작업들입니다.

이것이 스킬(Skill)의 세계입니다.

스킬과 워크플로우의 관계

앞서 WAT 프레임워크에서 워크플로우(Workflow)를 다루었습니다. 마크다운으로 작성된 작업 지시서, 에이전트가 읽고 실행하는 SOP(Standard Operating Procedure). 스킬은 이 워크플로우와 본질적으로 같은 것입니다.

이름만 다릅니다. 워크플로우라는 단어가 "일회성 작업 흐름"의 느낌을 준다면, 스킬은 "반복적으로 사용할 수 있는 숙련된 기술"이라는 뉘앙스를 가집니다. 워크플로우에는 도구(Tool)로서 파이썬 스크립트가 붙었습니다. 스킬에도 파이썬 스크립트가 붙습니다. 워크플로우는 마크다운 파일이었고, 스킬도 마크다운 파일입니다. 구조가 동일합니다.

차이가 있다면 스킬에는 YAML 프론트매터(YAML Front Matter)가 추가된다는 점입니다. 파일 상단에 ---로 감싸인 영역이 있고, 그 안에 스킬의 이름(name)과 설명(description)이 기록됩니다. 이 프론트매터가 에이전트의 스킬 탐색 효율을 극적으로 높입니다. 에이전트는 모든 스킬 파일의 전체 내용을 읽지 않습니다.

프론트매터의 이름과 설명만 훑어보고, 현재 요청에 맞는 스킬을 골라낸 뒤, 선택된 스킬의 본문만 상세히 읽습니다. 이를 점진적 컨텍스트 로딩(Progressive Context Loading)이라 합니다.

name: morning-coffee

description: 캘린더, 프로젝트 현황, 분기 목표를 종합하여 오늘의 일정을 계획합니다.



# 모닝 커피 스킬



## 언제 사용하는가

사용자가 하루 계획을 세우고 싶을 때, 아침 루틴을 시작할 때



## 실행 절차

1. 오늘의 캘린더 이벤트를 확인한다

2. ClickUp에서 이번 주 태스크를 가져온다

   ...

스킬을 워크플로우의 진화형이라고 볼 수도 있고, 같은 개념에 대한 다른 이름이라고 볼 수도 있습니다. 중요한 것은 둘 다 "에이전트에게 주는 자연어 지시서"이며, 사람이 읽을 수 있고 사람이 수정할 수 있다는 점입니다. 프로그래밍 언어가 아닌 일상 문장으로 에이전트의 행동을 정의합니다.

.claude/skills 디렉터리에 스킬 파일 만들기

스킬 파일의 물리적 위치는 프로젝트의 .claude/skills/ 디렉터리입니다. 각 스킬은 하위 폴더로 구분되며, 폴더 안에 skill.md 파일이 핵심입니다.

프로젝트/

└── .claude/

    └── skills/

        ├── morning-coffee/

        │   └── skill.md

        ├── research/

        │   ├── skill.md

        │   └── scripts/

        │       └── perplexity_search.py

        ├── infographic-builder/

        │   ├── skill.md

        │   ├── scripts/

        │   │   └── overlay_logo.py

        │   └── references/

        │       └── api_reference.md

        └── excalidraw-diagram/

            └── skill.md

[그림 12-1] .claude/skills 디렉터리 구조 예시]

스킬 폴더 안에는 skill.md 외에 보조 파일들이 들어갈 수 있습니다. 파이썬 스크립트를 scripts/ 폴더에, 참조 문서를 references/ 폴더에 넣는 식입니다. 이렇게 스킬 내부에 모든 것을 담는 방식을 자체 포함(Self-Contained) 구조라 합니다.

다른 방법도 있습니다. 스크립트나 참조 파일이 프로젝트의 다른 위치에 있을 수 있습니다. 예를 들어 유튜브 분석 스킬의 skill.md에서 ../../references/youtube_channel.md를 참조하도록 경로를 지정하면, 파일이 스킬 폴더 바깥에 있어도 문제없습니다. 에이전트는 skill.md에 기록된 경로를 따라가서 필요한 파일을 읽습니다.

이를 외부 참조(External Reference) 구조라 합니다.

어느 쪽이든, 핵심 원칙은 하나입니다. skill.md 안에 올바른 경로가 기록되어 있으면 됩니다.

스킬을 처음 만드는 과정은 직접 마크다운 파일을 작성하는 것이 아닙니다. 에이전트와의 대화를 통해 만듭니다. 계획 모드에서 "리서치 스킬을 만들어 줘. Perplexity API를 사용하고, .env에 API 키 자리를 만들어 줘"라고 요청하면, 에이전트가 폴더 구조를 설계하고, skill.md를 작성하고, 필요한 스크립트를 생성하고, CLAUDE.md를 업데이트하여 새 스킬의 존재를 등록합니다.

왜 이 과정을 수동이 아닌 에이전트에게 맡기는 것이 나을까요? 에이전트는 프론트매터 형식, 파일 경로 규칙, 모델이 세는 글 조각 효율적인 구조 같은 모범 사례를 이미 알고 있기 때문입니다. 다만, 에이전트가 항상 완벽한 구조를 만들지는 않습니다. YAML 프론트매터 없이 순수 마크다운으로만 스킬을 생성하는 경우가 있습니다.

이때는 직접 프론트매터를 추가하거나, Anthropic의 공식 문서 URL을 에이전트에게 주고 "이 문서를 참고해서 모범 사례대로 만들어 줘"라고 지시하면 됩니다.

skill.md의 권장 분량은 500줄 이하입니다. 상세한 참조 자료는 별도 파일로 분리하는 것이 모델이 세는 글 조각 절약에 유리합니다.

스킬 설명문 작성법

스킬이 올바르게 작동하려면 에이전트가 그 스킬을 찾을 수 있어야 합니다. 에이전트가 사용자의 요청을 분석한 뒤 수십 개의 스킬 중에서 적합한 것을 고르는 과정에서, 설명문(Description)이 결정적 역할을 합니다.

점진적 컨텍스트 로딩의 첫 번째 단계에서, 에이전트는 각 스킬의 이름과 설명문만 읽습니다. 이 단계에서 소모되는 모델이 세는 글 조각은 스킬당 대략 100개 내외입니다. 설명문이 모호하면 에이전트가 잘못된 스킬을 선택하거나, 적합한 스킬이 있는데도 지나칠 수 있습니다.

좋은 설명문의 조건은 세 가지입니다.

트리거 상황을 명시합니다. "사용자가 하루 계획을 세우거나, 모닝 커피라고 말할 때 사용"처럼, 이 스킬이 호출되어야 하는 구체적인 상황을 기술합니다. 에이전트가 사용자의 자연어 요청과 설명문을 대조하여 매칭 여부를 판단하기 때문입니다.

결과물을 명시합니다. "캘린더, 태스크, 목표를 종합하여 시간 블록이 할당된 일정표를 출력한다"처럼, 스킬 실행의 결과물이 무엇인지 적어 둡니다. 이것이 사용자의 기대와 일치하는지를 에이전트가 확인하는 근거가 됩니다.

범위를 한정합니다. "이 스킬은 일정 계획만 다루며, 콘텐츠 생성이나 리서치는 포함하지 않음"처럼 경계를 설정합니다. 유사한 스킬이 여러 개 있을 때, 에이전트가 혼동하지 않도록 돕습니다.

[그림 12-2] 점진적 컨텍스트 로딩의 3단계: 프론트매터 스캔 → 스킬 본문 로드 → 참조 파일 로드]

스킬의 호출 방식은 두 가지입니다. 첫째, 슬래시 명령어입니다. /morning-coffee라고 입력하면 해당 스킬이 바로 실행됩니다. 둘째, 자연어입니다. "오늘 하루 계획 좀 세워 줘"라고 말하면 에이전트가 설명문을 검색하여 모닝 커피 스킬을 찾아냅니다.

슬래시 명령어는 빠르고 정확합니다. 해석 과정이 없으니 즉시 실행됩니다. 자연어는 유연합니다. 스킬 이름을 몰라도 의도만 전달하면 됩니다. 둘 다 활성화해 두는 것이 보통이지만, 스킬이 의도치 않게 너무 자주 호출된다면 YAML 프론트매터에서 disable_model_invocation: true를 설정하여 자연어 트리거를 끄고 슬래시 명령어로만 호출되도록 제한할 수 있습니다.

스킬이 호출되지 않는 문제가 발생하면, 대부분 설명문이 원인입니다. "유용한 스킬"처럼 추상적인 설명은 어떤 요청과도 매칭되지 않습니다. "사용자가 인포그래픽 제작을 요청하거나, 시각적 콘텐츠가 필요할 때 Krea AI의 Nano Banana 모델을 호출하여 브랜드 가이드라인에 맞는 PNG 이미지를 생성한다"처럼 구체적으로 쓸수록 정확도가 올라갑니다.

GitHub에 커밋하여 팀과 공유하기

스킬이 .claude/skills/ 폴더에 존재하는 한, 그 스킬은 해당 프로젝트에서만 유효합니다. 프로젝트 폴더를 깃허브(GitHub)에 푸시하면, 팀원 누구든 이 레포지터리를 클론하여 동일한 스킬을 사용할 수 있습니다.

이것이 의미하는 바를 생각해 봅니다. 한 사람이 리서치 스킬을 만들고 수십 번 반복 실행하며 다듬었습니다. 프롬프트를 조정하고, 출력 형식을 개선하고, 불필요한 API 호출을 줄이는 최적화를 거쳤습니다. 그 결과물을 깃허브에 커밋하는 순간, 팀 전원이 같은 품질의 리서치를 수행할 수 있게 됩니다. 한 사람의 학습 곡선이 팀 전체의 역량으로 전환됩니다.

커밋과 공유의 절차는 간단합니다. 프로젝트에서 git init으로 깃 레포지터리를 초기화하거나, 에이전트에게 "이 프로젝트를 깃허브에 올려 줘"라고 요청합니다. 에이전트가 레포지터리를 생성하고, 커밋하고, 푸시합니다. 이후 스킬을 수정할 때마다 커밋을 남기면, 버전 관리가 자동으로 이루어집니다. 어떤 버전의 스킬이 더 나았는지 비교할 수 있고, 문제가 생기면 이전 버전으로 돌릴 수 있습니다.

[그림 12-3] 스킬의 공유 흐름: 개인 작성 → Git 커밋 → GitHub 푸시 → 팀원 클론]

스킬의 저장 위치에 대해 한 가지 선택이 더 있습니다. 프로젝트 스킬과 글로벌 스킬의 구분입니다.

프로젝트 스킬은 .claude/skills/에 위치하며, 해당 프로젝트에서만 작동합니다. 팀원과 공유할 수 있습니다. 프론트엔드 디자인 스킬이 웹 개발 프로젝트에만 필요하다면, 프로젝트 스킬로 두는 것이 맞습니다.

글로벌 스킬은 홈 디렉터리의 ~/.claude/skills/에 위치하며, 어떤 프로젝트를 열든 사용 가능합니다. 팀원과 공유되지 않습니다. 나만 사용하는 개인 스킬, 혹은 모든 프로젝트에서 공통으로 쓰이는 스킬이 여기에 해당합니다. 프론트엔드 디자인 스킬이 어떤 프로젝트에서든 필요하다면, 글로벌에 두는 편이 편리합니다.

스킬의 진정한 가치는 완성된 스킬 하나에 있지 않습니다. 수정 의견 루프(Feedback Loop)에 있습니다. 스킬을 실행하고, 에이전트의 작업 과정을 관찰하고, "이 부분은 불필요한 API 호출이었어", "출력 형식이 마음에 안 들어"라고 수정 의견하고, 에이전트가 skill.md를 수정합니다.

이 순환을 열 번, 스무 번 반복하면, 처음에 어색했던 스킬이 자신의 업무 방식에 꼭 맞는 도구로 변모합니다. 에이전트에게 완벽한 스킬을 처음부터 기대하는 것은 비현실적입니다. 완벽은 반복에서 나옵니다.

스킬의 최적화 과정에서 발견하게 되는 패턴이 있습니다. 에이전트가 매번 같은 데이터를 검색하느라 시간을 소모한다면, 자주 참조하는 ID나 경로를 skill.md에 하드코딩합니다. 에이전트가 한 번에 읽는 범위를 너무 많이 소모한다면, 무거운 작업을 보조 에이전트에게 위임하도록 스킬에 지시를 추가합니다.

에이전트가 외부 API 문서를 매번 검색한다면, 그 문서를 웹 정보 수집하여 참조 마크다운 파일로 저장합니다. 마크다운 파일을 읽는 것이 API 문서를 크롤링하는 것보다 훨씬 빠르고 저렴합니다.

이 모든 최적화의 방향은 하나입니다. 스킬을 실행한 뒤 다른 일을 하다가 10분 후 돌아와서 완성된 결과물을 확인하는 것. 그 경지에 도달하면, 한 사람이 네 개의 에이전트를 동시에 굴리며 하루치 업무를 오전 중에 끝내는 풍경이 비현실이 아닌 일상이 됩니다.

그리고 이 스킬들이 서로 연결되고, 보조 에이전트가 서로를 호출하고, 외부 서비스가 MCP를 통해 에이전트와 대화하기 시작하면, 개인 비서 수준을 넘어선 무언가가 만들어집니다.