클로드 스킬(Agent Skills) 정리: 만드는 법과 놓치기 쉬운 함정 3개 (2026)

Claude 스킬은 “SKILL.md 만들면 된다”까지는 어디서나 설명하는데, 정작 막히는 건 그다음이다 — claude.ai에 올린 스킬이 왜 Claude Code에서 안 보이는지, 왜 엑셀 스킬은 Claude Code에서 못 쓰는지, 이름을 왜 거부당하는지. 공식 문서 기준으로 구조와 함정을 갈라서 정리했다.

아래 내용은 platform.claude.com 에이전트 스킬 문서, code.claude.com/docs/en/skills, Anthropic 엔지니어링 블로그를 2026-07-28에 확인한 값이다. 스킬은 기능이 빠르게 붙는 영역이라 설정 직전에 공식 문서를 재확인하는 편이 안전하다.

스킬은 언제 만드나

기준은 단순하다. 같은 지시·체크리스트·절차를 반복해서 붙여넣고 있을 때다. 공식 문서가 제시하는 또 하나의 신호가 정확한데 — CLAUDE.md의 한 섹션이 “사실”이 아니라 “절차”로 자라났을 때다.

이 구분이 중요한 이유가 있다. CLAUDE.md 내용은 세션마다 항상 로드되지만, 스킬 본문은 쓰일 때만 로드된다. 그래서 긴 참고 자료를 스킬에 넣어두면 쓰기 전까지는 비용이 거의 없다.

그리고 알아둘 점: 스킬은 Anthropic 전용 규격이 아니다. Agent Skills 오픈 표준을 따르고 여러 AI 도구에서 동작한다. Claude Code는 여기에 호출 제어·서브에이전트 실행 같은 기능을 얹은 형태다.

왜 컨텍스트를 안 먹나 — 3단계 로딩

이게 스킬 설계의 핵심이고, 대부분의 소개 글이 “자동으로 불린다”까지만 쓰고 넘어가는 부분이다. 스킬은 세 단계로 나눠서 로드된다.

단계	로드 시점	토큰 비용	내용
1. 메타데이터	항상 (시작 시)	스킬당 약 100토큰	frontmatter의 name·description
2. 본문	스킬이 호출될 때	5k토큰 미만	SKILL.md 본문 지시
3. 리소스	필요할 때만	접근 전까지 0	번들 파일·스크립트

여기서 실무적으로 중요한 결론 두 개가 나온다.

첫째, 스킬은 많이 깔아도 된다. 호출 안 된 스킬은 이름과 설명만 차지하니까 100개를 깔아도 컨텍스트 부담이 크지 않다. MCP 서버와 대비되는 지점이다 — MCP는 연결하면 도구 정의가 컨텍스트에 올라간다.

둘째, 스크립트를 번들하는 게 이득이다. Claude가 validate.py를 실행하면 스크립트 코드는 컨텍스트에 안 들어가고 출력만 들어간다. 매번 같은 코드를 생성하게 하는 것보다 훨씬 싸고, 결과도 결정적이다.

세 번째 단계 덕분에 번들 용량에 실질적 제한이 없다. API 문서 전체, 큰 데이터셋, 예시 모음을 넣어둬도 안 읽으면 0토큰이다.

어디서 쓸 수 있나

여기서 갈린다. 표를 먼저 보고 자기 상황을 찾는 게 빠르다.

	claude.ai	Claude Code	Claude API
사전 제작 문서 스킬 (PPT·엑셀·워드·PDF)	✅	❌	✅
커스텀 스킬	✅ (zip 업로드)	✅ (파일시스템)	✅ (Skills API)
공유 범위	개인 전용	개인 / 프로젝트 / 플러그인	워크스페이스 전체
네트워크 접근	설정에 따라 다름	전체	❌ 없음
패키지 설치	—	로컬만 권장	❌ 불가

함정 1: 서피스 간 동기화가 안 된다

이게 제일 많이 당황하는 지점이다. 공식 문서가 명시한다 — 커스텀 스킬은 서피스 간에 동기화되지 않는다.

• claude.ai에 올린 스킬 → API에서 안 보임
• API에 올린 스킬 → claude.ai에서 안 보임
• Claude Code 스킬은 파일시스템 기반이라 위 둘과 완전히 별개

즉 세 곳에서 다 쓰려면 세 번 올려야 한다. “한 번 만들면 어디서나”가 아니다.

함정 2: 엑셀·PPT 스킬은 Claude Code에 없다

“클로드로 엑셀 만들기”를 기대하고 Claude Code를 켰다면 방향이 틀렸다. 사전 제작 문서 스킬(pptx·xlsx·docx·pdf)은 Claude Code에서 제공되지 않는다. claude.ai와 API에서만 쓴다. Claude Code에는 대신 오픈소스 Claude API 스킬이 번들돼 있다.

claude.ai에서 쓰기

사전 제작 문서 스킬은 설정이 필요 없다. 문서를 만들라고 하면 Claude가 알아서 쓴다.

커스텀 스킬을 올리려면 설정 > Features에서 zip으로 업로드한다. 조건이 두 개다:

• Pro·Max·Team·Enterprise 플랜
• 코드 실행(code execution)이 켜져 있어야 함

한 가지 제약을 미리 알아두는 게 좋다. claude.ai의 커스텀 스킬은 사용자 개인 단위다. 팀원마다 각자 올려야 하고, 관리자가 조직 전체에 중앙 배포하는 기능은 지원되지 않는다.

Claude Code에서 만들기

여기가 가장 유연하다. 파일시스템 기반이라 업로드가 없다.

mkdir -p ~/.claude/skills/summarize-changes

그 안에 SKILL.md를 만든다:

---
name: summarize-changes
description: 커밋 안 된 변경사항을 요약하고 위험한 부분을 표시한다. 사용자가 무엇이 바뀌었는지 묻거나, 커밋 메시지를 원하거나, diff 리뷰를 요청할 때 사용한다.
---

1. `git status`와 `git diff`로 변경사항을 확인한다.
2. 변경을 목적 단위로 묶어 요약한다.
3. 시크릿·설정 파일·마이그레이션이 포함됐으면 별도로 경고한다.

이제 /summarize-changes로 직접 부를 수도 있고, description에 맞는 요청을 하면 Claude가 알아서 부른다.

어디에 두나

종류	경로	적용 범위
개인	~/.claude/skills/<이름>/SKILL.md	내 모든 프로젝트
프로젝트	.claude/skills/<이름>/SKILL.md	이 프로젝트만
플러그인	<플러그인>/skills/<이름>/SKILL.md	플러그인이 켜진 곳

이름이 겹칠 때 우선순위가 직관과 다르다: enterprise > 개인 > 프로젝트 순이다. 개인 스킬이 프로젝트 스킬을 덮어쓴다는 뜻이니, 팀 레포에 스킬을 커밋했는데 동작이 다르면 자기 ~/.claude/skills/를 확인해봐야 한다.

디렉터리 이름이 곧 명령어 이름이 된다. name 필드는 개인·프로젝트 스킬에서는 목록에 보이는 표시 이름일 뿐이고, 실제 호출 이름은 디렉터리에서 온다.

슬래시 명령어는 스킬로 합쳐졌다

기존에 .claude/commands/를 쓰고 있었다면 알아둘 변화다. 커스텀 명령어가 스킬로 통합됐다. .claude/commands/deploy.md와 .claude/skills/deploy/SKILL.md는 둘 다 /deploy를 만들고 동일하게 동작한다. 기존 파일은 계속 쓸 수 있지만, 스킬 쪽만 지원 파일 번들·호출 제어·자동 로딩을 쓸 수 있다.

Claude Code 전용 frontmatter

표준 스킬은 name·description만 있으면 되는데, Claude Code는 필드를 더 얹었다. 실제로 자주 쓰는 것들만:

필드	용도
disable-model-invocation	true면 Claude가 자동으로 안 부름 (/이름으로만 수동 호출)
user-invocable	false면 / 메뉴에서 숨김 (배경 지식용)
allowed-tools	이 스킬이 도는 턴 동안 허가 없이 쓸 도구
disallowed-tools	이 스킬이 활성인 동안 아예 빼버릴 도구
context: fork	서브에이전트 컨텍스트에서 실행
paths	특정 파일 패턴을 다룰 때만 자동 로드
model / effort	이 스킬이 활성인 동안 모델·추론 강도 변경

allowed-tools와 disallowed-tools의 권한 부여는 다음 메시지를 보내면 해제된다. 영구 설정이 아니다.

한 가지 편의 기능: Claude Code는 스킬 디렉터리의 변경을 감시해서 SKILL.md를 고치면 재시작 없이 현재 세션에 반영된다. 단 세션 시작 시점에 없던 최상위 skills 디렉터리를 새로 만든 경우엔 재시작이 필요하다.

함정 3: 이름 규칙

name 필드에 제약이 있는데 모르면 한참 헤맨다.

• 최대 64자
• 소문자·숫자·하이픈만
• XML 태그 불가
• 예약어 anthropic·claude 포함 불가

description도 규칙이 있다. 최대 1024자, 비어 있으면 안 되고, “무엇을 하는지”와 “언제 쓰는지”가 둘 다 들어가야 한다. Claude가 이 필드를 요청과 대조해서 호출 여부를 판단하기 때문이다. Claude Code에서는 description과 when_to_use를 합친 텍스트가 목록에서 1,536자에서 잘린다 — 핵심 용례를 앞에 쓰는 게 유리하다.

이 규칙은 만들다 보면 바로 걸린다. 이 블로그를 운영하면서 “글 발행 전 점검” 스킬을 만들려고 claude-publish-check라고 이름을 지었다가 예약어에 막혔다. publish-check로 바꾸면 통과한다.

붙이기 전에 검사하는 스크립트를 만들어두면 편하다:

// SKILL.md 프론트매터 자가 점검
const raw = require("fs").readFileSync("SKILL.md", "utf8");
const fm = Object.fromEntries(
  raw.match(/^---\n([\s\S]*?)\n---\n/)[1]
    .split("\n")
    .filter((l) => l.includes(":"))
    .map((l) => [l.slice(0, l.indexOf(":")).trim(), l.slice(l.indexOf(":") + 1).trim()])
);

const errs = [];
if (!/^[a-z0-9-]+$/.test(fm.name)) errs.push("name: 소문자·숫자·하이픈만");
if (fm.name.length > 64) errs.push("name: 64자 초과");
if (/claude|anthropic/i.test(fm.name)) errs.push("name: 예약어 포함");
if (!fm.description) errs.push("description 없음");
if (fm.description.length > 1024) errs.push("description 1024자 초과");

console.log(errs.length ? "❌ " + errs.join(" / ") : "✅ 통과");

실제로 돌아가는 스킬 하나

앞의 summarize-changes는 구조를 보여주는 최소 예제였고, 실전에서는 이 정도 분량이 된다. 이 블로그의 발행 전 점검 스킬 전문이다:

---
name: publish-check
description: 블로그 글을 발행하기 전 마크다운 오류·내부링크·빌드를 점검한다. 사용자가 글을 다 썼다고 하거나, 발행·배포·커밋을 요청하거나, 점검을 요청할 때 사용한다.
allowed-tools: Bash Read
---

발행 전 점검을 순서대로 수행하고, 실패한 항목만 보고한다.

1. **강조 구문 오류** — 닫는 `**` 앞이 문장부호면 CommonMark에서 강조가 닫히지 않는다.
   ```bash
   grep -rnE '[)\.,:;!?]\*\*[^ )\.,:;!?]' src/content/blog/ || echo "통과"
   ```

2. **내부링크 유효성** — 빌드 결과에서 깨진 링크를 찾는다.
   ```bash
   npm run build && node scripts/check-links.mjs
   ```

3. **프론트매터 필수 필드** — title·description·pubDate·category가 모두 있는지 확인한다.

세 항목이 모두 통과하면 "발행 가능"이라고만 답하고, 하나라도 실패하면 실패 항목과
해당 파일 경로를 보고한다. 자동으로 고치지는 않는다.

여기서 설계상 눈여겨볼 게 세 가지다.

description에 트리거 문구를 나열했다. “글을 다 썼다”, “발행”, “배포”, “커밋”, “점검” — Claude는 이 필드를 사용자 요청과 대조하므로, 실제로 사용자가 쓸 법한 표현을 넣어야 자동 호출된다. “발행 전 점검을 한다”고만 쓰면 잘 안 불린다.

allowed-tools: Bash Read로 승인을 미리 준다. 이게 없으면 명령마다 권한을 물어서 점검이 끊긴다. 다만 이 권한은 다음 메시지를 보내면 해제된다 — 영구 설정이 아니라 이 턴 한정이다.

마지막 문단이 출력 형식을 못 박는다. “자동으로 고치지는 않는다”까지 쓴 이유가 있다. 안 쓰면 점검만 시켰는데 파일을 고쳐놓는 경우가 생긴다. 스킬 본문은 절차서이므로 하지 말아야 할 것도 절차의 일부다.

보안 — “소프트웨어 설치처럼 다뤄라”

공식 문서의 권고가 명확하다. 직접 만든 스킬이나 Anthropic이 제공한 스킬만 쓰라는 것이다. 이유는 구조상 당연하다 — 스킬은 지시와 코드로 Claude에게 새 능력을 주는 것이므로, 악의적인 스킬은 표시된 목적과 다르게 도구를 부르거나 코드를 실행하도록 유도할 수 있다.

특히 위험한 유형으로 문서가 콕 집는 것: 외부 URL에서 데이터를 가져오는 스킬이다. 가져온 내용에 악성 지시가 심겨 있을 수 있고, 처음엔 믿을 만했던 스킬도 외부 의존성이 나중에 바뀌면 위험해질 수 있다.

출처가 불확실한 스킬을 꼭 써야 한다면 SKILL.md만 보고 넘어가면 안 된다. 번들된 스크립트·이미지·리소스를 전부 열어보고, 스킬의 명시된 목적과 맞지 않는 네트워크 호출이나 파일 접근이 있는지 확인해야 한다.

한 가지 더: 스킬은 ZDR(제로 데이터 보존) 대상이 아니다. 스킬 정의와 실행 데이터는 Anthropic 표준 보존 정책에 따라 보관된다. 민감한 내용을 스킬에 넣을 때 고려할 지점이다.

MCP와 뭐가 다른가

둘을 헷갈리는 경우가 많은데 역할이 다르다.

	MCP	스킬
제공하는 것	도구·데이터로 가는 통로	그 도구를 쓰는 절차
컨텍스트 비용	연결 시 도구 정의가 올라감	호출 전까지 ~100토큰
설치	claude mcp add / 커넥터	디렉터리 + SKILL.md

공식 엔지니어링 문서도 스킬이 MCP를 대체하는 게 아니라 보완한다고 설명한다 — 외부 도구가 얽힌 복잡한 워크플로를 가르치는 역할이다. 그러니까 “슬랙에 붙이기”는 MCP, “슬랙에서 이슈를 모아 주간 보고서를 만드는 절차”는 스킬이다. MCP 설정은 클로드 MCP 연결하기에 따로 정리해뒀다.

정리

하려는 일	답
엑셀·PPT·워드 만들기	claude.ai (설정 불필요) 또는 API
반복 절차를 자동화	Claude Code 스킬 (~/.claude/skills/)
팀과 공유	프로젝트 .claude/skills/ 커밋 또는 플러그인
세 곳에서 다 쓰기	세 번 각각 업로드 (동기화 없음)
자동 호출 안 될 때	description에 “언제 쓰는지” 넣기
수동 호출만 원할 때	disable-model-invocation: true

스킬이 사용량에서 몇 %를 먹는지는 Claude Code의 /usage로 스킬별 breakdown을 볼 수 있다. 사용량 한도 구조 자체는 Pro와 Max 요금제 정리에, API로 직접 쓸 때의 토큰 단가는 API 요금 정리에 있다. 스킬이 만들어낸 결과물을 남에게 공유하는 방법은 아티팩트 정리 쪽이다.

스킬이 특히 값어치를 하는 용도가 검증 절차다. “결과물을 만들고 끝”이 아니라 “만든 뒤 검증 스크립트를 돌린다”까지 절차에 못박아두면 매번 지시할 필요가 없다 — 인용이 원문에 실제로 있는지 대조하는 스크립트를 그렇게 엮는 방법은 할루시네이션 검증 파이프라인에 있다.