에이전트 스킬 초보자 가이드: 나만의 첫 번째 스킬 만들기

AI를 다루는 모든 사람이 한 번쯤 겪는 문제가 있습니다:

어제 가르쳐준 내용을 오늘 새로운 대화에서 시작하면 처음으로 초기화됩니다.

3일 동안 워크플로우를 다듬고 Claude와 주고받으며 완성해도, 다음 날 다시 모든 걸 설명해야 합니다.

메모장에 프롬프트를 저장해두고 매번 붙여넣기 하지만, 500자짜리 지시문을 한 달 내내 매일 붙여넣다 보면 '이게 정말 AI를 제대로 쓰는 건가' 싶어집니다.

Skill 은 바로 이 문제를 해결하기 위해 탄생했습니다.

Anthropic이 2025년 10월에 출시했고, 12월에 오픈 스탠다드가 되었죠.

오늘날 인터넷 전체가 "Skill이 생산성을 바꾼다"고 외치고 있지만, 대부분은 이름만 들어봤을 뿐 Skill과 프롬프트, 지식 베이스, MCP, Agent의 차이를 제대로 이해하지 못하고 있습니다. 직접 만들어본 사람은 더더욱 드물죠.

이 글에서 모든 것을 한 번에 설명드리겠습니다.

먼저 한 가지를 이해해야 합니다: Skill 은 특정 AI에 종속되지 않습니다.

많은 사람이 "Claude Skill"이라고 들어서 Claude 전용 기능이라고 생각하지만, 아닙니다. Agent Skills 는 Anthropic이 출시한 오픈 스탠다드이며, Claude는 그중 가장 앞선 구현체일 뿐입니다.

동일한 Skill 폴더를 Claude Code의 ~/.claude/skills/에 넣을 수도 있고, Cursor의 ~/.cursor/skills/에 넣을 수도 있으며, OpenAI Codex, Gemini CLI, VS Code Copilot, JetBrains Junie에서도 사용할 수 있습니다.

오늘 작성한 Skill은 내일 다른 Agent로 자유롭게 옮길 수 있습니다. 여러분의 투자가 하나의 회사에 갇히지 않는다는 뜻입니다.

이 글에서는 주로 Claude Code를 예시로 사용하겠습니다(표준을 만들고 생태계가 가장 완성된 곳이니까요). 하지만 모든 원칙, 작성 방법, 문제 해결 경험은 Agent Skills를 지원하는 모든 AI 도구에 동일하게 적용됩니다.

"Claude Skill"이라는 말이 나오면 "Agent Skill"이라고 생각하세요.

1. Skill 이란 정확히 무엇인가요?

한 문장으로 정의하자면:

Skill 은 SKILL.md라는 마크다운 파일을 중심으로 구성된 폴더로, 여러분이 정의한 SOP에 따라 AI가 특정 유형의 전문 작업을 안정적으로 수행하도록 지시합니다.

즉, "특정 유형의 작업을 어떻게 처리해야 하는지"를 재사용 가능하고 자동으로 트리거되는 기능 모듈로 캡슐화한 것입니다.

기본적으로 범용 AI를 위한 "확장팩"이라고 보면 됩니다.

일반 AI는 지능은 있지만 도메인 지식이 부족한 베어본 머신과 같습니다. Skill 은 플러그 앤 플레이 모듈입니다. "샤오홍슈 스타일 Skill"을 설치하면 AI가 즉시 여러분의 브랜드를 이해하는 편집자가 되고, "주간 보고서 Skill"을 설치하면 AI가 회사 형식에 맞는 보고서를 즉시 생성합니다.

그리고 이 "확장팩"은 AI를 가리지 않습니다. Claude Code, Codex, Cursor, Gemini CLI, Junie 모두 동일한 형식을 인식합니다.

여러분은 Claude 전용 스크립트가 아닌 Agent Skill 을 만드는 것입니다.

다른 네 가지 개념과의 경계:

많은 사람이 Skill을 프롬프트, 지식 베이스, MCP, Agent와 혼동하지만, 이들은 서로 다릅니다:

일반적인 비유:

• 프롬프트 = 직원에게 위챗 메시지를 보내는 것. 끝나면 잊어버립니다.
• Skill = 직원에게 매뉴얼을 작성해 책상 위에 두고, 도구 상자도 함께 제공하는 것.
• 지식 베이스 = 세상에 무엇이 있는지 알려주는 도서관.
• MCP = "할 수 있는가"의 문제를 해결하는 다양한 주방 도구.
• Agent = 기억과 의사 결정 능력을 갖춘 전체 직원 시스템. Skill 은 그중 한 부분일 뿐입니다.

이 네 가지는 상호 배타적이지 않습니다.

실제 작업에서는 종종 결합해서 사용합니다. MCP는 Claude가 Reddit에 연결해 데이터를 스크래핑하게 하고, Skill은 해당 데이터를 필터링/분류/추천하는 방법을 가르치며, 지식 베이스는 브랜드 자료를 제공하고, Agent는 전체 프로세스를 실행하는 시스템입니다.

2. 아키텍처와 작동 메커니즘

파일 구조

각 하위 디렉토리는 서로 다른 문제를 해결하지만, 동일한 목표를 위해 존재합니다. 바로 컨텍스트를 절약하고 품질을 안정화하는 것입니다:

• scripts/: 정확한 계산을 수행하며 컨텍스트를 소모하지 않습니다.
• references/: 필요할 때만 로드되어 공간을 낭비하지 않습니다.
• assets/: 출력 형식을 표준화합니다.

3단계 점진적 공개—Skill 디자인의 핵심

Skill 의 핵심 메커니즘은 3단계 로딩입니다. 이것이 여러 개의 Skill이 컨텍스트를 폭발시키지 않고 공존할 수 있는 이유입니다:

예를 들어:

Claude가 시작되면 모든 Skill의 "표지"만 훑어보고 어떤 것을 사용할지 결정합니다. 실제 작업을 할 때가 되어서야 본문을 열고, 부록을 확인해야 할 때만 참조 자료를 펼쳐봅니다.

이 메커니즘을 통해 17개의 Skill을 동시에 활성화해도 200K 컨텍스트 창이 막히지 않습니다.

YAML 메타데이터

필드 설명:

설명이 성패를 좌우한다

3단계 아키텍처에서 L1 설명이 가장 중요합니다. 이 설명이 Skill이 트리거될지 여부를 결정하기 때문입니다.

핵심 사실:

1. Claude는 시작 시 모든 Skill의 설명만 읽습니다.
2. 설명을 기반으로 의미론적 판단을 내리지, 키워드 매칭을 하지 않습니다.
3. Claude는 보수적인 경향이 있습니다. 확실하지 않으면 트리거하지 않습니다. 테스트 결과, 모호한 설명의 트리거 정확도는 55%에 불과했습니다.

부정적인 예시 (절대 트리거되지 않음):

[모호한 설명]

긍정적인 예시 (Anthropic이 권장하는 "적극적인" 스타일):

[구체적인 설명]

설명 작성의 세 가지 황금률:

1. WHAT + WHEN을 함께 작성: 무엇을 하고 언제 사용하는지 명시합니다.
2. 트리거 단어를 한국어와 영어로 모두 나열: 사용자가 무슨 말을 하든 매칭되도록 합니다.
3. 보수적이기보다 적극적으로: Anthropic은 주요 문제가 트리거 부족이라고 명시적으로 밝히고 있습니다.

3. 좋은 Skill 을 작성하는 핵심 원칙

세 가지 주요 원칙

자유도를 처리하는 방법:

다섯 가지 디자인 패턴

Anthropic은 초기 사용자들로부터 다섯 가지 Skill 디자인 패턴을 도출했습니다:

유용한 Skill은 종종 여러 패턴을 혼합합니다. 엄격하게 따를 필요는 없지만, 존재를 알면 더 체계적으로 디자인하는 데 도움이 됩니다.

황금률: "~해야 한다(Must)" 대신 "이유(Why)"를 사용하라

이는 skill-creator (Skill을 만들기 위한 Anthropic의 공식 메타 스킬) 소스 코드에서 인용한 내용입니다:

"Try to explain to the model why things are important in lieu of heavy-handed musty MUSTs."

부정적인 예시:

[엄격한 MUST 규칙]

긍정적인 예시:

[이유 설명]

첫 번째 경우, Claude는 그 두 가지 규칙만 따릅니다. 규칙이 다루지 않는 상황(예: 겉보기에 안전하지만 위험한 명령)에서는 막힙니다. 두 번째 경우, Claude는 "안전이 중요한 이유"를 이해하고 애매한 상황에서도 주의 쪽으로 기울게 됩니다.

이유를 제시하면 모델이 일반화할 수 있지만, 규칙은 여러분이 생각할 수 있는 시나리오만 다룹니다. 유일한 예외는 출력 형식입니다. "출력은 이 템플릿을 사용해야 함"과 같은 기계적 요구 사항은 설명할 "이유"가 없으므로 그냥 하드코딩하세요.

정보 소유권: 반복하지 마라(DRY)

skill-creator에도 철칙이 있습니다:

"Information should exist in SKILL.md or references—not both."

SKILL.md에는 기본 절차만 포함하고, 세부 사항은 references/로 옮기세요. 중복 저장하면 한 곳을 업데이트하고 다른 곳을 잊어버려 불일치가 발생합니다.

피해야 할 파일

Skill 은 AI를 위한 것이지, 사람을 위한 것이 아닙니다. README.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md, CHANGELOG.md는 추가하지 마세요. 이런 사람용 문서는 컨텍스트만 낭비합니다.

4. 첫 번째 Skill 만들기

Anthropic의 공식 6단계

skill-creator 내부에 정의된 표준 프로세스입니다:

1. 의도 파악: 무엇을 할지 / 언제 트리거할지 / 출력 형식 / 테스트 요구 사항을 명확히 합니다.
2. 인터뷰 및 조사: 엣지 케이스 / 입출력 형식 / 예제 파일 / 종속성을 파악합니다.
3. SKILL.md 작성: 초안을 작성합니다.
4. 테스트 케이스: 2~3개의 실제 테스트 케이스를 작성합니다.
5. 실행 및 평가: Skill을 적용한 경우와 기본(no skill) 상태를 나란히 실행하여 벤치마킹합니다.
6. 반복: 피드백에 따라 수정하고 만족할 때까지 다시 실행합니다.

일반 사용자를 위한 네 가지 빠른 경로

skill-creator: Skill 을 만들기 위한 메타 스킬

Anthropic의 공식 skill-creator를 먼저 설치하는 것을 강력히 추천합니다. Skill을 만드는 데 도움을 주도록 설계된 Skill입니다. 시작하면 Claude가 여러분을 인터뷰하며 워크플로우, 트리거 조건, 경계 등을 물어본 후 자동으로 SKILL.md와 폴더 구조를 생성합니다.

설치 명령어:

[명령어]

단순히 출력만 생성하는 것이 아니라, 다음과 같은 작업도 도와줍니다:

• 평가: Skill이 올바르게 트리거되는지 확인하기 위해 테스트 케이스를 자동 생성합니다.
• 개선: 테스트 결과를 바탕으로 설명과 지침을 자동 최적화하며, 과적합을 방지하기 위해 60/40 훈련/테스트 분할을 사용합니다.
• 벤치마킹: 성공률과 토큰 사용량을 추적하고, 두 버전 간 A/B 테스트도 실행할 수 있습니다.

최소 예시

여러분이 샤오홍슈 푸드 블로거이고, 일반 레시피를 샤오홍슈 스타일로 다시 작성하려고 한다고 가정해 보겠습니다:

~/.claude/skills/xiaohongshu-recipe/SKILL.md에 배치하세요. 앞으로 "샤오홍슈 버전으로 바꿔줘"라고 말하면 자동으로 트리거됩니다.

파일을 만드는 것부터 사용하는 것까지 20분도 채 걸리지 않습니다.

5. 설치, 저장, 그리고 도구 간 사용

로딩 우선순위 (4단계)

Claude Code는 다음 순서로 검색하며, 더 구체적인 위치가 더 높은 우선순위를 가집니다:

팁: 프로젝트별로 특화된 것이 아니라면 개인 ~/.claude/skills/ 디렉토리에 보관하여 통합 관리하세요.

세 가지 설치 방법:

설치 후 Claude Code를 재시작하는 것을 잊지 마세요.

도구 간 호환성 (다시 강조)

앞서 언급했듯이 Skill은 Claude에 종속되지 않습니다. 경로 비교는 다음과 같습니다:

운영상의 의미: 동일한 SKILL.md 폴더를 다른 도구 디렉토리에 심볼릭 링크할 수 있습니다. 이것이 Agent Skills가 오픈 스탠다드로서 가지는 가장 큰 장점입니다.

국내 사용자의 고충

• 공식 Claude는 비쌉니다: 프록시 API를 사용하면 비용 대비 성능이 좋습니다.
• CC Switch: 여러 API 구성을 관리하고 전환할 수 있는 오픈소스 도구입니다 (github.com/farion1231/cc-switch).
• 네이티브 설치가 npm보다 안정적입니다: curl -fsSL https://claude.ai/install.sh | bash.

6. 고급—멀티 스킬 협업 아키텍처

세분화

핵심 원칙: Skill 하나당 명확한 작업 하나. "만능 Skill"을 만들지 마세요.

세분화가 너무 거칠면 설명이 불명확해지고 트리거가 부정확해집니다. 너무 세밀하면 관리 비용이 증가합니다. 합리적인 세분화는 문제 유형당 하나의 Skill이며, SKILL.md 본문은 약 200~500줄 정도입니다.

사례 연구: 블로그 작성 Skill 제품군

"올인원 작성 Skill"을 만들지 마세요. 대신 협업하는 5개의 Skill로 분할하세요:

협업 방식: 메인 Skill이 ## Steps 섹션에서 다른 Skill을 명시적으로 호출합니다.

이렇게 분할했을 때의 이점:

다섯 가지 엔지니어링 경험

1. 세밀한 세분화: Skill 하나당 명확한 작업 하나.
2. 명시적 협업: 메인 Skill의 ## Steps를 사용하여 다른 Skill을 호출합니다.
3. 계산에는 스크립트 사용: SEO 글자 수나 링크 통계에는 스크립트를 사용하고, 모델이 추정하게 두지 마세요.
4. 독립적인 스타일 가이드: 안정적인 지식(글쓰기 스타일/브랜드 사양)은 references/에 보관하여 하나의 파일만 변경하면 스타일이 업데이트되도록 합니다.
5. 템플릿 폴백: 템플릿은 출력이 너무 빗나가지 않도록 기본적인 보장을 제공합니다.

7. 전문적인 평가와 반복

평가 시스템:

skill-creator의 표준 프로세스:

1. evals/evals.json에 테스트 프롬프트를 작성합니다.
2. with_skill과 baseline(no skill)을 동시에 실행하여 이중 맹검 비교를 수행합니다.
3. agents/grader.md를 사용하여 각 평가 항목에 점수를 매깁니다.
4. aggregate_benchmark를 사용하여 pass_rate / time / tokens에 대한 보고서를 출력합니다.

자동 설명 최적화

skill-creator에서 가장 가치 있는 부분은 설명 최적화입니다:

• 20개의 트리거 평가 쿼리를 작성합니다 (8~10개는 트리거되어야 하고, 8~10개는 트리거되지 말아야 함).
• 어려운 점: 트리거되지 말아야 할 쿼리의 "near misses"—키워드는 공유하지만 다른 도구가 필요한 쿼리입니다.
• 최적화 스크립트: 60% 훈련 + 40% 홀드아웃 테스트로 과적합을 방지합니다.
• 5회 실행하고 가장 높은 테스트 점수를 받은 설명을 선택합니다.

트리거의 좋은 예: "PDF 표 추출"이라고만 쓰지 말고, 실제 사용자처럼 작성하세요:

"ok so my boss just sent me this xlsx file (it's in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage."

여기에는 파일 경로, 개인적 맥락, 열 이름, 일상적인 언어, 잠재적인 오타가 포함됩니다.

반복 마인드셋

skill-creator의 네 가지 포인트:

1. 피드백에서 일반화: 단일 사례에 대해 까다로운 규칙을 추가하지 마세요. 문제가 반복되면 다른 비유나 워크플로우를 시도해 보세요.
2. 간결하게 유지: 시간을 낭비하는 지침이 있는지 대화 기록을 확인하고 도움이 되지 않는 부분은 삭제하세요.
3. 이유 설명: LLM은 마음 이론을 가지고 있어 일반화할 수 있습니다.
4. 중복 작업 찾기: 모든 하위 Agent가 독립적으로 create_docx.py를 작성하고 있다면 scripts/로 묶으세요.

첫 번째 버전은 결코 완벽하지 않습니다.

실제 반복 사례: 한 작성자의 /daily 스킬은 안정화되는 데 6버전이 걸렸습니다.

• v1: 불명확한 단계, 잘못된 경로.
• v2: 콘텐츠 발견 시스템 통합 추가.
• v3: 주간 진행률 계산 오류 수정.
• v4: 자동 트리거 추가 (화요일 알림, 월말 아카이빙).
• v5: iPhone 라이트 모드 추가 (모바일에서 Python 단계 건너뛰기).
• v6: 드디어 "사용하기 좋은" 상태.

Skill 은 설정하고 잊어버리는 구성 파일이 아닙니다. 여러분의 워크플로우가 담긴 살아있는 문서입니다.

8. 언제 Skill 을 만들어야 할까요?

모든 것이 Skill을 만들 가치가 있는 것은 아닙니다. 다음 세 가지 신호 중 하나가 나타날 때만 행동하세요:

반대로: 만들지 말아야 할 때

• 일회성 작업: 그냥 프롬프트를 사용하세요.
• 과도한 캡슐화: 세 번밖에 사용하지 않았는데 Skill을 나누는 것. 유지보수 비용이 이점보다 큽니다.
• 완벽 추구: v1을 완벽하게 만들려고 함. 실제로 사용해보면 요구 사항이 상상에 불과했음을 알게 됩니다.

9. 함정 체크리스트

10. 생태계와 필수 목록

Skill 리소스 맵

필수 Skill 목록

11. Skill 의 상업적 잠재력

Skill은 단순한 개인 생산성 도구를 넘어, AI 애플리케이션을 생산하는 방식을 재정의하고 있습니다.

과거에는 수직적 AI 앱을 개발하는 데 긴 주기, 높은 비용, 기술 팀이 필요했습니다. 이제는:

• 코드 없음: 코딩 없이 수직적 Agent를 구축할 수 있습니다.
• 빠른 검증: 개발 주기가 몇 주에서 몇 분으로 단축되었습니다.
• API 서비스: Skill을 API로 패키징하여 기존 제품에 기능을 추가할 수 있습니다.
• Skill as a Product: 프롬프트 컬렉션을 판매하는 것과 유사하지만, 더 높은 가치를 제공합니다.

실제 사례:

• Article-Copilot: 자료 정리부터 글쓰기까지 전체 체인을 담당하는 단일 Skill.
• AI Partner Skill: 일반 Agent에게 깊은 기억을 부여하여 진정한 동반자로 만듭니다.
• 면접 준비 Skill: 회사/직무/이력서를 기반으로 전체 보고서를 생성합니다. 누군가는 이걸로 Hithink RoyalFlush 면접을 보기도 했습니다.
• Super Huang의 방법: 수십 개의 Skill을 크론 작업과 함께 실행하여 그가 자는 동안에도 시간별 보고서를 생성합니다.

업계에 깊이 종사하는 사람이라면 누구나 자신의 경험을 Skill로 추출하여 시간을 절약하거나 제품으로 판매할 수 있습니다.

결론

Agent가 AI 세계의 몸이라면, Skill은 그 몸에 주입되는 영혼입니다.

Steam과 Workshop의 관계와 같습니다. 확장 가능한 아키텍처는 게임에 무한한 생명력을 불어넣습니다.

Skill은 어렵지 않습니다. 그저 구조가 있는 마크다운일 뿐입니다. 하지만 이것이 나타내는 트렌드는 매우 중요합니다. AI가 "매번 가르쳐야 하는" 상태에서 "한 번만 가르치면 되는" 상태로 나아가고 있다는 것입니다.

그리고 그 표준은 개방되어 있습니다. 오늘 Claude Code용으로 작성한 Skill을 내일은 Cursor나 Gemini로 옮길 수 있습니다.

아직 지켜보고 있는 분들께:

Skills aren't designed; they grow out of repeated labor.

Skill 은 설계되는 것이 아니라, 반복된 노동에서 자라나는 것입니다.

먼저 한 가지를 실행해보고, 그런 다음 캡슐화하세요. 좋은 워크플로우는 계획되는 것이 아니라 반복을 통해 만들어집니다.

터미널을 열고 skill-creator를 설치한 다음, 오늘 세 번이나 반복한 그 문단을 첫 번째 SKILL.md로 만들어 보세요.