Claude 스킬 튜토리얼: 10분 만에 첫 번째 SKILL.md 만들기 (2026)

Claude 스킬 튜토리얼: 10분 만에 첫 번째 SKILL.md 만들기 (2026)

스킬(Skills)은 아마도 여러분이 아직 사용하지 않고 있는 가장 중요한 Claude Code 기능일 것입니다. Claude 스킬은 SKILL.md 파일이 포함된 폴더로, 프롬프트가 해당 설명과 일치하는 순간 Claude가 자동으로 로드합니다. 프롬프트를 복사해 붙여넣을 필요도, 비대해진 CLAUDE.md를 관리할 필요도, 어떤 템플릿을 가져와야 할지 기억할 필요도 없습니다. 저희는 이 저장소의 .claude/skills/agent/ 폴더 안에 4개의 스킬을 배포했으며, Skills 2.0과 2026년 초에 등장할 Anthropic Marketplace 덕분에 이 포맷은 마침내 본격적인 궤도에 오르게 되었습니다. 다음은 함정들을 피한 뒤에 실제로 작동하는 패턴입니다.

핵심 요점

• Claude 스킬은 YAML frontmatter가 포함된 SKILL.md 파일을 담고 있는 폴더로, 관련성이 있을 때 Claude가 자동으로 로드합니다.
• 스킬은 ~/.claude/skills/(개인용) 또는 .claude/skills/(프로젝트용)에 위치하며, Claude는 시작 시 두 곳 모두를 스캔합니다.
• 반복 가능한 워크플로에는 스킬을, 실시간 외부 데이터에는 MCP를, 다단계 계획에는 서브에이전트를, 결정론적 이벤트에는 훅을 사용하세요.
• 첫 번째 스킬을 만드는 가장 빠른 방법은 Claude에게 자체 skill-creator 스킬을 호출해 달라고 요청하는 것입니다. 그러면 SKILL.md를 대신 작성해 줍니다.

Claude 스킬이란?

Claude 스킬은 SKILL.md 파일( YAML 프론트매터로 name, description, 선택적 allowed-tools 포함)을 담은 폴더로, 프롬프트가 description과 일치하면 Claude Code가 자동으로 컨텍스트에 로드합니다. 스킬은 /commit이나 /explain-code처럼 재사용 가능한 워크플로를 시스템 프롬프트를 비대하게 만들지 않으면서 패키징합니다.

Anthropic 공식 문서에 따르면, 모든 스킬 폴더에는 세 가지가 있습니다. 필수인 SKILL.md, 선택적으로 번들된 스크립트(Python 헬퍼부터 JSON 설정까지 무엇이든), 그리고 본문과 함께 로드되는 선택적 참조 문서입니다. 그게 전부입니다. 빌드 단계도, 설치도, 매니페스트도 없습니다.

영리한 부분은 점진적 공개(progressive disclosure) 입니다. 시작 시 Claude는 모든 스킬의 description 필드만 스캔합니다. 본문, 즉 지침, 예시, 도구 호출 패턴은 프롬프트가 실제로 일치할 때까지 디스크에 남아 있습니다. 그래서 스킬을 50개 설치해 두고도 하나가 실행되기 전까지는 토큰 비용이 전혀 들지 않습니다.

스킬을 Claude가 프롬프트에서 재료를 발견했을 때 펼쳐 보는 요리책 레시피처럼 생각하세요. 스킬은 Claude가 필요할 때 읽는 폴더이지, 붙여넣기를 기억해야 하는 프롬프트가 아닙니다. 이게 이 개념의 전부입니다.

최소한의 SKILL.md는 다음과 같습니다:

---
name: Summarize file
description: Use when the user asks for a 3-sentence summary of a file or function.
---

Read the file at $ARGUMENTS. Summarize purpose, key dependencies, and the
single most surprising thing about it. Three sentences max.

열 줄. 진짜 스킬. 바로 실행 가능합니다.

빠른 시작: 10분 만에 첫 스킬 만들기

10분 만에 첫 Claude 스킬을 만들려면: (1) ~/.claude/skills/explain-code/ 디렉터리를 생성하고, (2) name, description, 워크플로 본문이 담긴 SKILL.md 파일을 추가한 뒤, (3) Claude Code를 재시작하여 새 디렉터리를 스캔하게 하고, (4) description과 일치하는 프롬프트로 스킬을 실행하세요.

전체 흐름은 다음과 같습니다.

1단계: 디렉터리 생성

mkdir -p ~/.claude/skills/explain-code

개인 스킬(본인만 사용)은 ~/.claude/skills/ 아래에 둡니다. 프로젝트 스킬(git을 통해 팀과 공유)은 저장소 루트의 .claude/skills/ 아래에 둡니다. 일상적으로 쓰는 워크플로에는 개인 스킬을, 저장소의 모든 기여자가 상속받게 하려면 프로젝트 스킬을 선택하세요.

2단계: SKILL.md 작성

이 파일을 ~/.claude/skills/explain-code/SKILL.md에 저장하세요:

---
name: Explain code
description: Use when the user asks for a plain-English walkthrough of a code snippet, function, or file. Use $ARGUMENTS for the path or snippet.
---

You are explaining code to a developer who is new to this codebase.

1. Read the file or snippet at $ARGUMENTS.
2. State the file's purpose in one sentence.
3. Walk through the control flow line by line in plain English.
4. Flag any non-obvious dependencies or side effects.
5. End with one question the reader should ask before changing this code.

이것이 스킬의 전부입니다. frontmatter는 계약이고, 본문은 플레이북입니다.

3단계: Claude Code 재시작

실시간 감지는 Skills 2.0 기능으로, 이전 버전의 Claude Code는 새 디렉터리를 인식하려면 새로 시작해야 합니다. 어떤 버전을 사용 중인지 확실하지 않다면, 한 번 재시작하는 것쯤은 아무런 부담이 없습니다.

4단계: 트리거하기

프로젝트를 열고 다음과 같이 프롬프트를 입력하세요:

walk me through what auth/middleware.ts does

Claude는 프롬프트를 description 필드와 대조하여 explain-code를 찾아낸 뒤, SKILL.md 본문을 컨텍스트에 조용히 로드합니다. 도구 로그에 "Using skill: explain-code"라는 메시지가 표시됩니다. 이것으로 끝입니다.

프로 팁: 파일을 직접 작성하기 귀찮으신가요? Claude Code를 열고 Use the skill-creator skill to scaffold an explain-code skill for me.라고 입력해 보세요. Anthropic이 기본으로 제공하는 skill-creator는 여러분에게 질문을 던지고, 적절한 allowed-tools를 골라주며, 올바른 폴더에 SKILL.md를 작성해 주는 메타 스킬입니다. 단언컨대, 첫 번째 스킬로 가는 가장 빠른 길입니다.

이것이 바로 10분의 약속입니다. 5분의 타이핑, 한 번의 재시작, 한 번의 테스트 프롬프트면 됩니다.

SKILL.md 내부: 프런트매터 레퍼런스

SKILL.md의 프런트매터는 --- 구분자로 감싼 YAML입니다. 필수 필드는 두 가지입니다. name(64자 이하, 슬래시 명령어 이름으로 사용됨)과 description(Claude가 사용자의 프롬프트와 매칭하는 트리거 텍스트)입니다. 선택 필드로는 도구 접근, 모델 호출, 파일 글롭, 실행 컨텍스트를 제어할 수 있습니다.

Anthropic의 스킬 문서에서 가져온 전체 레퍼런스는 다음과 같습니다.

context: fork 행은 따로 짚고 넘어갈 가치가 있습니다. 이는 Skills 2.0의 프리미티브로, 격리된 컨텍스트 창 안에서 스킬을 실행합니다. 오래 실행되는 리서치 스킬이나, 메인 스레드를 오염시키고 싶지 않은 많은 중간 토큰을 생성하는 모든 작업에 유용합니다. 이 개념이 처음이라면, 컨텍스트 엔지니어링 가이드에서 트레이드오프를 다룹니다. 모든 필드가 채워진 맥시멀리스트 SKILL.md 전문(frontmatter):

---
name: Deploy preview
description: Use when the user wants to deploy a preview build of the current branch to staging.
allowed-tools: ["Bash(git status:*)", "Bash(npm run build:*)", "Bash(vercel:*)"]
disable-model-invocation: true
user-invocable: true
argument-hint: <branch-name or 'current'>
model: claude-opus-4-7
context: fork
globs: ["package.json", "vercel.json"]
references: ["./deploy-runbook.md"]
bundled-files: ["./scripts/preflight.sh"]
tags: ["deploy", "vercel", "preview"]
---

Pro tip: description에서 가장 흔한 실수는 바로 사람을 위해 쓴다는 것입니다. Claude를 위해 쓰세요. 마케팅 문구가 아니라, 구체적인 트리거 문구를 넣으세요. 나쁜 예: "강력한 Git 자동화 스킬." 좋은 예: "사용자가 변경 사항을 커밋하거나, 커밋 메시지를 작성하거나, PR을 열고 싶어 할 때 사용."

두 가지 실전 스킬, 처음부터 끝까지

두 가지 스킬 패턴이면 실제 사용 사례의 80%를 커버할 수 있습니다: (1) disable-model-invocation: true와 allowed-tools: Bash(git *)를 설정하여 결정적 동작을 수행하는 사용자 호출형 /commit 스킬, (2) 기본 frontmatter를 사용하여 프롬프트가 설명과 일치할 때 Claude가 자동으로 트리거하는 자동 호출형 /explain-code 스킬.

대부분의 튜토리얼은 코드 조각만 보여줍니다. 여기 지금 바로 ~/.claude/skills/에 복사해 넣을 수 있는 두 개의 완성된 파일이 있습니다.

/commit 스킬 (사용자가 호출 가능)

---
name: Commit
description: Use when the user wants to stage and commit code changes with an AI-written conventional-commit message.
disable-model-invocation: true
user-invocable: true
allowed-tools:
  - "Bash(git status:*)"
  - "Bash(git diff:*)"
  - "Bash(git add:*)"
  - "Bash(git commit:*)"
---

1. Run `git status` and `git diff` to see what's staged and unstaged.
2. Group changes into one logical commit. If there are multiple unrelated
   changes, ask the user which to include.
3. Draft a Conventional Commits message: `type(scope): subject` (≤72 chars),
   blank line, body explaining *why*, not *what*.
4. Show the message to the user. Ask "Commit this?" Wait for explicit yes.
5. On confirmation, run `git add` for the included files and `git commit -m`.
6. Print the resulting commit hash.

테스트 프롬프트: /commit

동작 방식: Claude가 git 상태를 검사하고, 커밋 메시지를 작성한 뒤, 사용자에게 확인을 요청하고, 그 후에야 git commit을 실행합니다. disable-model-invocation: true는 "내 변경사항 저장해줘" 같은 모호한 프롬프트에 자동으로 실행되지 않음을 의미하며, /commit을 직접 입력할 때만 실행됩니다. allowed-tools 화이트리스트는 이 스킬을 git 하위 명령어로만 제한하므로, rm -rf를 실행하거나 원격에 푸시하는 것은 물리적으로 불가능합니다. 이것은 실제로 저희 자체 파이프라인에 적용해 운영 중인 스킬입니다.

결정론적인 커밋 후 작업(린트 실행, 타입 재생성, Slack 웹훅 전송 등)이 필요하다면 대신 Claude Code hooks를 사용하세요. 스킬은 확률적으로 동작하지만, 훅은 매번 빠짐없이 실행됩니다.

/explain-code 스킬 (모델 호출 가능)

---
name: Explain code
description: Use when the user asks for a plain-English walkthrough of a code snippet, function, or file. Use $ARGUMENTS for the path or snippet.
argument-hint: <file path or pasted snippet>
model: claude-opus-4-7
---

1. Read the file or snippet at $ARGUMENTS. If $ARGUMENTS is empty, ask
   the user which file to explain.
2. State the file's purpose in one sentence.
3. Walk through the control flow line by line in plain English.
4. Flag any non-obvious dependencies, side effects, or hidden assumptions.
5. End with one question the reader should ask before modifying this code.

테스트 프롬프트: walk me through what auth/middleware.ts does

동작 방식: 사용자가 /explain-code를 입력하지 않았다는 점에 주목하세요. Claude는 "walk me through"라는 표현을 description 필드와 대조해 해당 스킬을 찾아내고 자동으로 호출합니다. 이것이 바로 마법입니다. description이 라우팅을 담당하는 것이죠. model: claude-opus-4-7 필드는 기본값으로 설정한 모델에 관계없이 이 스킬을 Opus에 고정시키므로, 심층적인 코드 워크스루는 항상 더 똑똑한 모델을 사용하게 됩니다. (Claude Code를 다른 모델로 실행하는 방법에 대한 자세한 내용.)

왜 두 가지 패턴인가? 스킬 #1은 사용자 호출 가능 + 특정 도구에 고정되어 있어 예측 가능하고 안전하며 git이나 배포에 완벽합니다. 스킬 #2는 자동 호출 + 자유 형식으로, 스킬의 마법이지만 description 필드를 신뢰해야 합니다. 사용자 호출 가능 스킬은 예측 가능성을, 모델 호출 가능 스킬은 마법을 제공합니다. 리포지토리 단위가 아니라 스킬 단위로 선택하세요.

더 많은 실제 예제 스킬을 보려면 공식 anthropics/skills 리포지토리와 커뮤니티에서 관리하는 awesome-claude-skills 목록을 확인하세요.

스킬 vs MCP vs 서브에이전트 vs 훅: 언제 무엇을 써야 하는가

스킬(Skills) 은 Claude가 자동으로 트리거하거나 슬래시 명령어로 호출할 수 있는 재사용 가능한 워크플로에 사용하세요. MCP 서버는 실시간 외부 데이터(데이터베이스, API, 작업 디렉터리 외부의 파일시스템)가 필요할 때 사용하세요. 서브에이전트는 Claude가 새로운 컨텍스트에 위임해야 하는 다단계 계획에 사용하세요. 훅(Hooks) 은 반드시 항상 실행되어야 하는 결정론적 이벤트(pre-commit, post-tool-use)에 사용하세요. 확률적으로 실행되어서는 안 됩니다.

간단한 프레임: 스킬은 워크플로, Model Context Protocol은 데이터, 서브에이전트는 계획, 훅은 이벤트입니다. 각각 Claude Code의 서로 다른 레이어에 존재하며, 잘못된 레이어를 선택하면 잘못된 도구를 쓰는 것입니다. Anthropic의 Skills explained 포스트에서도 바로 이 프레임을 내재화하라고 권합니다.

이들은 조합됩니다. 스킬은 allowed-tools를 통해 MCP 도구를 호출할 수 있습니다. 훅은 스킬 완료 후 실행될 수 있습니다. 서브에이전트는 접근 권한이 부여된 스킬을 사용할 수 있습니다. 가장 깔끔한 멘탈 모델: 먼저 올바른 레이어를 선택한 다음, 쌓아 올리세요. 스킬은 Claude가 선택할 수 있는 워크플로를 원할 때 꺼내 드는 컨텍스트 엔지니어링 프리미티브이고, Claude가 건너뛸 수 없는 무언가를 원할 때 훅으로 자동화합니다. 각각을 가장 잘못 사용하는 방법: 실시간 데이터에 Skills를 쓰는 것 (MCP를 사용하세요); 일회성 프롬프트 템플릿에 MCP를 쓰는 것 (Skills를 사용하세요); 결정적 파일 편집에 subagents를 쓰는 것 (hooks를 사용하세요); 분기 로직에 hooks를 쓰는 것 (Skills를 사용하세요). Skills는 워크플로, MCP는 데이터, subagents는 계획, hooks는 이벤트입니다. 버즈워드가 아닌 레이어로 선택하세요.

스킬의 위치: 개인, 프로젝트, 플러그인, 엔터프라이즈

Claude 스킬은 네 가지 범위에 설치됩니다: 개인(~/.claude/skills/, 본인만 사용), 프로젝트(저장소 루트의 .claude/skills/, git을 통해 팀과 공유), 플러그인(Anthropic 마켓플레이스 또는 임의의 플러그인 URL을 통해 배포), 그리고 엔터프라이즈(IT 부서에서 MDM/관리자 정책을 통해 푸시). Claude는 시작 시 이 네 가지를 모두 스캔합니다.

번들 문서 스킬은 잊기 쉽습니다. Claude Code에는 이미 pdf, docx, pptx, xlsx 스킬이 기본적으로 포함되어 있으며, /debug, /simplify 등의 소규모 내장 라이브러리도 함께 제공됩니다. (자매 도구인 Claude Design에는 디자인 생성을 위한 자체 번들 워크플로 스킬이 포함되어 있습니다. 동일한 모델, 다른 도메인입니다.)

언제 프로젝트 대신 플러그인으로 배포할까요? 동일한 워크플로가 여러 저장소에 도움이 될 때는 플러그인이 더 유리합니다. 다섯 개의 클라이언트 코드베이스 전반에서 사용하는 /release 스킬은 각 저장소의 .claude/skills/에 복사해 붙여넣을 것이 아니라 플러그인으로 만들어야 합니다. 프로젝트 스킬은 코드베이스별 컨벤션(팀의 PR 템플릿, 커스텀 테스트 러너)에 적합합니다. Anthropic 마켓플레이스와 임의의 URL에서 실행하는 /plugin install 덕분에, 저장소 간 재사용에는 플러그인이 정답입니다. 플러그인 문서에 따르면, 검색과 업데이트는 자동으로 처리됩니다.

고급 패턴: $ARGUMENTS, 동적 셸 삽입, context: fork

가장 중요한 고급 스킬 패턴은 세 가지입니다. $ARGUMENTS는 사용자가 호출 가능한 스킬에 매개변수를 전달할 수 있게 해주고(/translate $ARGUMENTS), 동적 셸 삽입(allowed-tools: Bash(...) 사용)은 스킬이 스크립트를 실행한 뒤 그 출력을 컨텍스트로 파이프 처리할 수 있게 해주며, context: fork(Skills 2.0)는 분리된 컨텍스트 창에서 스킬을 실행합니다. 2026년 5월 기준 context: fork에 대한 표준 참고 자료는 Anthropic의 Complete Guide 백서입니다.

매개변수화된 스킬을 위한 $ARGUMENTS

---
name: Translate
description: Translate the most recent message into the target language.
user-invocable: true
argument-hint: <target-language, e.g. spanish, japanese, brazilian portuguese>
---

Translate the user's previous message into $ARGUMENTS. Preserve tone,
preserve markdown formatting, return only the translation.

테스트 프롬프트: /translate spanish. Claude가 런타임에 spanish를 $ARGUMENTS에 대입합니다. 별도 변형을 작성하지 않고도 스킬을 다목적용으로 만드는 가장 깔끔한 방법입니다.

allowed-tools를 통한 동적 셸 인젝션

---
name: Review last commit
description: Use when the user wants a code review of the last git commit.
allowed-tools: ["Bash(git diff HEAD~1:*)", "Bash(git log -1:*)"]
---

Run `git diff HEAD~1` and `git log -1`. Review the diff for bugs, security
issues, and style violations. Output a 5-bullet review.

이 스킬은 외부 셸을 호출하고, diff를 컨텍스트로 파이프한 뒤 검토합니다. allowed-tools는 특정 명령어(Bash(git diff HEAD~1:*))로 고정하고, 맨 Bash는 절대 사용하지 마세요. 맨 Bash 권한은 이 패턴의 보안 자충수 버전입니다.

context: fork (Skills 2.0)

---
name: Deep research
description: Use when the user wants a multi-source research summary on a topic.
context: fork
---

Research the topic in $ARGUMENTS using available web tools. Produce a
2-page summary with citations. Do not pollute the main thread.

포킹을 사용하면 스킬이 고유한 컨텍스트 창을 갖게 되어, 5만 토큰에 달하는 중간 조사 노트가 메인 세션으로 흘러들어가지 않습니다. 긴 조사 작업, 대규모 리팩터링 계획, 또는 버려질 토큰을 대량으로 생성하는 모든 작업에 유용합니다. Skills 2.0 전용 기능으로, 이전 버전의 Claude Code는 이 필드를 무시합니다.

문제 해결: 스킬이 실행되지 않는 이유

스킬이 실행되지 않는 경우는 대개 다음 네 가지 원인 중 하나입니다: (1) description이 너무 일반적이어서 Claude가 사용자의 프롬프트와 매칭하지 못하는 경우, (2) 디렉터리가 잘못된 경로에 있는 경우 (.claude/skills/가 아니라 claude/skills/로 되어 있음), (3) 스킬 추가 후 Claude Code를 재시작하지 않은 경우 (Skills 2.0 이전 버전에만 해당), 또는 (4) 스킬 이름이 번들로 제공되거나 우선순위가 더 높은 스킬과 충돌하는 경우입니다. Claude Code GitHub 이슈 트래커에서 가장 많이 검색된 실패 유형에 따르면, 이 네 가지가 "왜 작동하지 않나요"라는 신고의 약 95%를 차지합니다.

실패 모드 1: "내 스킬이 전혀 표시되지 않아요"

가장 흔한 원인은 잘못된 경로입니다. .claude/skills/(점 있음)와 claude/skills/(점 없음)는 우리 모두 새벽 1시에 한 번쯤 저지르는 오타입니다. ls -la ~/.claude/skills/를 실행해 점이 포함된 디렉터리가 존재하는지 확인하세요. 디렉터리가 있는데도 Claude가 여전히 인식하지 못한다면, Claude Code를 한 번 재시작하세요. Skills 2.0 이전 버전은 시작할 때만 스캔합니다.

실패 모드 2: "Claude가 내 스킬을 자동으로 호출하지 않아요"

description 필드가 너무 모호하거나, Claude가 아닌 사람 대상으로 작성된 경우입니다. 사용자가 실제로 요청을 표현하는 방식을 반영한 구체적인 트리거 문구로 다시 작성하세요. 이 저장소에서 스킬 4개를 만들면서 제가 빠졌던 함정은 설명을 "SEO에 도움이 되는 스킬"처럼 남겨둔 것이었습니다. 전혀 쓸모없죠. 이렇게 다시 작성하세요: "사용자가 Markdown 게시물에 JSON-LD 스키마, 메타 태그, SEO frontmatter를 추가하려 할 때 사용하세요." 트리거 정확도가 약 30%에서 약 95%로 올라갔습니다. 트리거 정확도는 description 필드에서 결정됩니다. 이력서가 아니라 Claude를 위해 쓰세요.

실패 모드 3: "설명(description)이 슬래시 명령어 팔레트에서 잘림"

description이 1024자를 초과하거나 name이 64자를 초과한 경우입니다. 둘 다 엄격한 제한이 있습니다. 해결 방법: 스킬을 더 좁은 범위의 두 개 스킬로 나누거나, 긴 세부 내용을 SKILL.md 본문으로 옮기세요. frontmatter는 라우팅용이지 문서화용이 아닙니다.

실패 모드 4: "실시간 변경 감지가 작동하지 않아요"

Skills 2.0 이전의 Claude Code는 SKILL.md를 수정할 때마다 완전히 다시 시작해야 합니다. 스킬을 반복해서 수정하고 있는데 변경 사항이 반영되지 않는다면, 아마 이전 버전을 사용 중일 가능성이 높습니다. Skills 2.0(실시간 감지)이 포함된 Claude Code 버전으로 업그레이드하거나, 저장할 때마다 다시 시작하는 습관을 들이세요. 번거롭긴 하지만, 비용은 들지 않습니다.

Claude를 넘어선 스킬: 오픈 에이전트 스킬 표준

네, 스킬은 오픈 표준입니다. agentskills.io의 Agent Skills 표준은 어떤 벤더에도 종속되지 않는 SKILL.md 형식을 정의합니다. OpenAI의 Codex CLI와 ChatGPT Desktop은 2025년 12월에 이 표준을 채택했습니다. Claude Code용으로 작성한 동일한 SKILL.md가 약간의 프론트매터 조정만으로 Codex에서도 실행됩니다.

2026년 5월 기준 크로스 툴 지원 매트릭스는 다음과 같습니다. Claude Code는 Agent Skills를 완전히 지원합니다(레퍼런스 구현). OpenAI의 Codex CLI도 완전히 지원합니다. ChatGPT Desktop은 부분적으로 지원하는데, name, description, 본문은 작동하지만 allowed-tools 호환성은 아직 갖춰지지 않았습니다. Gemini CLI는 2026년 초에 지원을 발표했지만 이 글을 쓰는 시점에는 아직 출시되지 않았습니다. Cursor는 예외적인 사례로, 자체적인 Cursor rules 형식을 사용하며 SKILL.md를 네이티브로 읽지 않지만, 커뮤니티 차원의 심(shim)이 존재합니다.

스킬이 올해 내내 살아남도록 지금 작성해 두어야 할 것들입니다. name과 description은 깔끔하고 툴에 구애받지 않게 유지하세요. 크로스 툴로 운영한다면 벤더 전용 프론트매터는 네임스페이스(claude: 또는 codex:) 뒤로 분리하세요. 이식 가능한 표면, 즉 name, description, 본문, $ARGUMENTS는 어디서나 작동합니다. context: fork 같은 고급 필드는 다른 벤더가 동등한 기능을 출시할 때까지 Claude 전용입니다. Anthropic은 유출된 Claude Code 로드맵에 따라 더 깊은 마켓플레이스 통합도 추진하고 있으므로, 이식성은 점점 더 쉬워질 것입니다.

예제 스킬을 찾아볼 수 있는 세 곳입니다. anthropics/skills(공식), awesome-claude-skills(커뮤니티), 그리고 agentskills.io(표준의 스펙 페이지)입니다. 스킬은 더 이상 Claude의 기능이 아닙니다. Claude가 먼저 출시한 오픈 표준입니다.

자주 묻는 질문

Claude 스킬과 MCP 서버의 차이점은 무엇인가요?

Claude 스킬은 워크플로 지침이 담긴 SKILL.md 파일로, 프롬프트가 해당 설명과 일치할 때 Claude가 이를 불러옵니다. MCP 서버는 Claude가 실시간 데이터(데이터베이스, API, 작업 디렉터리 외부의 파일 시스템)를 가져오기 위해 호출하는 별도의 프로세스입니다. 워크플로에는 Skills를, 데이터에는 MCP를 사용하세요. 이 둘은 조합할 수 있으며, 스킬이 MCP 도구를 호출할 수도 있습니다.

Claude 스킬은 무료인가요?

네, 스킬은 Claude Code의 기본 내장 기능으로, 추가 비용이 없습니다. 스킬이 실행될 때 소비되는 모델 토큰에 대해서만 비용을 지불하면 됩니다. Anthropic 마켓플레이스에서 설치하는 스킬은 유료일 수 있지만(현재는 드뭅니다), 공식 anthropics/skills 리포지토리와 커뮤니티 awesome 리스트는 모두 무료로 복사하여 사용할 수 있습니다.

Claude 스킬은 어디에 설치되나요?

개인 스킬은 ~/.claude/skills/{skill-name}/에, 프로젝트 스킬은 저장소 루트의 .claude/skills/{skill-name}/에 저장됩니다. 플러그인 스킬은 /plugin install <url>로 설치되며 플러그인 디렉터리에 보관됩니다. 엔터프라이즈 스킬은 조직의 IT 팀이 관리 설정을 통해 배포합니다. Claude Code는 시작 시 이 네 가지 범위를 모두 스캔합니다.

Claude 스킬을 처음부터 만들려면 어떻게 하나요?

~/.claude/skills/ 아래에 폴더를 만들고, YAML 프론트매터(name, description) 뒤에 워크플로 지침을 이어 붙인 SKILL.md 파일을 추가한 다음, Claude Code를 재시작하세요. 가장 빠른 방법: Claude Code를 열고 번들로 제공되는 skill-creator 스킬을 호출해 달라고 요청하면, 1분도 안 되어 SKILL.md를 자동으로 만들어 줍니다.

내 Claude 스킬이 트리거되지 않는 이유는?

가장 흔한 네 가지 원인: (1) description이 너무 모호해서 Claude가 프롬프트와 매칭하지 못하는 경우로, 구체적인 트리거 문구로 다시 작성하세요; (2) 스킬이 잘못된 경로에 있는 경우 (.claude/skills/여야 하며 claude/skills/가 아님); (3) Skills 2.0 이전 버전에서는 Claude Code를 재시작해야 함; (4) 스킬 이름이 번들된 스킬과 충돌하는 경우. ls -la ~/.claude/skills/로 확인하세요.

ChatGPT나 Cursor에서도 Claude 스킬을 사용할 수 있나요?

ChatGPT Desktop과 Codex CLI는 Claude와 동일한 Agent Skills 표준을 지원하며, 같은 SKILL.md를 프론트매터만 약간 수정하면 양쪽에서 모두 실행할 수 있습니다. Cursor는 자체적인 Cursor rules 형식을 사용하며 SKILL.md를 기본적으로 읽지 않습니다. Gemini CLI는 2026년 초에 지원 계획을 발표했지만, 2026년 5월 기준 아직 출시되지 않았습니다.

skill-creator 스킬이란?

skill-creator는 anthropics/skills 저장소에 포함된 메타 스킬로, Claude가 새로운 SKILL.md 파일을 작성할 수 있도록 도와줍니다. 원하는 스킬의 기능을 Claude에게 설명하면, skill-creator가 설명을 위한 인터뷰를 진행하고, 적절한 allowed-tools를 선택한 뒤, 올바른 폴더에 SKILL.md를 작성합니다. 가장 빠른 스캐폴딩 방법입니다.

disable-model-invocation은 어떤 역할을 하나요?

스킬의 frontmatter에서 disable-model-invocation: true로 설정하면, 프롬프트 매칭을 기반으로 Claude가 해당 스킬을 자동으로 실행하는 것을 막을 수 있습니다. 이렇게 하면 해당 스킬은 사용자가 직접 호출할 수만 있게 되며, 슬래시 명령 팔레트에 /skill-name 형태로 표시되고 명시적으로 호출했을 때만 실행됩니다. /commit이나 /deploy처럼 파괴적이거나 결정론적인 작업에 사용하세요.

스킬을 몇 개 만들어서 프로젝트에 적용해 보고, 무엇이 효과가 있는지 확인해 보세요. 여러 저장소에서 "스킬이 트리거되지 않는" 문제들을 반복해서 겪고 있고, .claude/skills/ 구성에 대해 제3자의 시선으로 검토받고 싶다면 연락해 주세요. 함께 살펴보겠습니다.