클로드 스킬이란? 클로드 코드 스킬과 뭐가 다를까

클로드에게 새 능력 하나를 가르치는 데 얼마나 걸릴까요. 저는 최근에 그게 파일 하나로 끝나는 걸 보고 좀 놀랐어요. 이 글에서는 “스킬(Skill)“이 정확히 뭔지, 그리고 클로드 코드와 클로드 브라우저(claude.ai) 양쪽에 어떻게 적용하는지를 순서대로 정리해 보겠습니다. 실전 예시가 궁금하신 분들을 위해 뒤에 Grill Me 스킬 설치 및 사용 방법 글도 따로 준비해뒀습니다.

클로드 스킬이란 무엇인가

스킬은 사실 폴더 하나에 SKILL.md 파일 하나, 그게 전부예요. 안에는 클로드가 이 능력을 언제 써야 하는지 설명하는 부분(description)과, 실제로 뭘 해야 하는지 적은 지시문. 딱 이 두 가지만 들어갑니다.

CLAUDE.md와 헷갈리시는 분들이 많은데, 차이는 로딩 시점입니다. CLAUDE.md는 대화가 시작될 때부터 항상 컨텍스트에 올라가 있고, 스킬은 실제로 호출될 때만 불러옵니다. 그래서 저희가 market-pedia.com 저장소에서 쓰는 썸네일 생성 스킬, SEO 뉴스 발행 스킬처럼 길고 상세한 지시문을 몇 개씩 넣어둬도 평소 대화 비용에는 영향이 없습니다. 필요할 때만 불려나오니까요.

SKILL.md 파일 구조 이해하기

말보다 실제 파일을 보는 게 빠르죠. 제가 계획을 검증할 때 쓰는 grill-me 스킬의 프론트매터, 이렇게 생겼습니다.

---
name: grill-me
description: A relentless interview to sharpen a plan or design.
disable-model-invocation: true
---

이 중에서 진짜 중요한 건 description 한 줄입니다. 클로드가 대화 내용과 이 설명을 비교해서, 지금 이 스킬을 꺼내 쓸지 말지를 판단하거든요. disable-model-invocation: true는 반대로 “이건 사람이 직접 부를 때만 실행해라”는 뜻입니다. 계획을 그대로 승인해버릴지 말지 같은, 부작용 있는 판단은 클로드가 알아서 트리거하면 안 되니까요.

클로드 코드에 스킬 적용하는 방법

클로드 코드에서는 스킬을 어디에 저장하느냐가 곧 적용 범위를 정합니다.

개인 스킬 · 모든 프로젝트

~/.claude/skills/
└── grill-me/
    └── SKILL.md

프로젝트 스킬 · 이 저장소만

.claude/skills/
└── grill-me/
    └── SKILL.md

개인 스킬(~/.claude/skills/)은 컴퓨터에 있는 모든 프로젝트에서 씁니다. 프로젝트 스킬(.claude/skills/)은 그 저장소에서만 동작하고, 팀원과 같이 커밋해서 공유할 수 있습니다. 저희 웹사이트 저장소에는 썸네일 생성기, SEO 뉴스 발행기 같은 프로젝트 스킬이 여러 개 들어있는데, 새로 합류하는 사람도 저장소만 클론하면 바로 같은 스킬을 쓸 수 있다는 게 꽤 편합니다.

만드는 순서는 딱 세 단계예요. 폴더를 만들고, SKILL.md를 쓰고, 실제로 불러서 테스트합니다. 저장하자마자 바로 반영되니 재시작할 필요도 없고요.

클로드 브라우저(claude.ai)에 스킬 적용하는 방법

코드 편집기가 없는 브라우저 환경에서도 스킬을 쓸 수 있습니다. 다만 방식이 다릅니다.

Customize > Skills로 들어갑니다.
+ Create skill 또는 업로드 메뉴에서 스킬 폴더를 ZIP으로 압축해 올립니다. 폴더명이 스킬 이름과 같아야 하고, 그 안에 SKILL.md가 반드시 있어야 합니다.
업로드하자마자 켜지는 게 아닙니다. 목록에서 토글을 직접 켜야 실제로 작동합니다 — 저는 처음에 이걸 놓쳐서 “왜 안 되지” 하고 몇 분 헤맸습니다.

팀·엔터프라이즈 플랜에서는 관리자가 조직 전체에 스킬을 배포할 수도 있습니다. 다만 아무 스킬이나 올리기 전에 어디서 받은 건지는 꼭 확인하시길 권합니다. 스킬은 결국 클로드가 그대로 따르는 지시문이라, 신뢰할 수 없는 출처의 스킬을 올리면 프롬프트 인젝션 같은 위험이 생길 수 있습니다.

클로드에서 쓰는 스킬 vs 클로드 코드에서 쓰는 스킬

저장 위치만 다른 게 아닙니다. 실제로 쓸 수 있는 기능 자체가 다릅니다.

클로드 코드는 Agent Skills라는 공개 표준을 따르면서, 여기에 몇 가지를 더 얹었습니다. 사람이 직접 부를지 클로드가 알아서 부를지 정하는 disable-model-invocation, 스킬을 별도 서브에이전트로 돌리는 context: fork, 그리고 !명령어 형태로 셸 명령을 실행해 그 결과를 스킬 본문에 끼워 넣는 “동적 컨텍스트 주입”까지 씁니다.

claude.ai(브라우저)에 업로드하는 스킬은 이 확장 기능을 못 씁니다. 실제로 지원하는 프론트매터는 name, description, license, compatibility, metadata, allowed-tools 6개뿐입니다. disable-model-invocation이나 context: fork 같은 필드를 넣으면 업로드 자체가 오류로 막힙니다. !명령어 같은 동적 주입 구문도 claude.ai 채팅이나 API에서는 그냥 텍스트로 취급되고 실행되지 않습니다.

이유는 실행 환경이 다르기 때문입니다. claude.ai의 스킬은 별도로 켜야 하는 “코드 실행 환경” 안에서 샌드박스로 돌아가는 반면, 클로드 코드는 제 컴퓨터에서 파일과 셸에 직접 접근하며 돌아갑니다. 그래서 같은 이름의 스킬이라도, 클로드 코드용으로 짠 SKILL.md를 그대로 claude.ai에 올리면 일부 기능이 조용히 무시되거나 업로드가 거부될 수 있습니다.

클로드 코드 vs 브라우저 — 무엇이 다른가

구분	개인 스킬	프로젝트 스킬	브라우저 스킬
저장 위치	~/.claude/skills/	.claude/skills/	claude.ai 계정
적용 범위	내 컴퓨터의 모든 프로젝트	이 저장소만	이 계정으로 로그인한 모든 세션
호출 방식	/스킬명 (자동 또는 수동)	/스킬명 (자동 또는 수동)	대화 중 자동, 토글을 켜야 작동
공유 방법	파일 복사	git 커밋	ZIP 업로드

저는 실무에서는 프로젝트 스킬을 가장 많이 씁니다. 팀 전체가 같은 워크플로우를 저장소만으로 그대로 물려받을 수 있어서요.

이 원리를 실제로 써서 기획 단계의 허점을 잡아주는 스킬 하나를 소개하고 싶은데요. grill-me라는 스킬인데, 구현을 시작하기 전에 계획을 집요하게 캐물어서 서로 다른 걸 그리고 있었다는 걸 뒤늦게 발견하는 사고를 미리 걸러줍니다. 설치법과 실제 사용법은 Grill Me 스킬 설치 및 사용 방법에 따로 정리해뒀습니다.