가이드

Claude Code skills: 사용법과 SKILL.md 작성법

게시일 2026년 10월 30일 · 최종 확인 2026년 10월 30일

skill은 지침을 담은 SKILL.md 파일입니다. Claude가 관련이 있을 때 사용하거나, 사용자가 /skill-name으로 직접 호출할 수 있습니다. 이 글은 Anthropic의 Extend Claude with skills 문서를 따라가며, 첫 skill 만들기, skills의 위치, frontmatter 작성법, 누가 skill을 호출할지 제어하는 방법, skill이 트리거되지 않을 때 확인할 것을 설명하는 사용법 가이드입니다. 문서는 2026년 10월 30일에 확인했습니다.

skill을 작성해야 할 때

문서의 기준은 이렇습니다. 같은 지침, 체크리스트, 여러 단계의 절차를 채팅에 계속 붙여넣고 있거나, CLAUDE.md의 한 섹션이 사실이 아니라 절차로 커졌을 때입니다. CLAUDE.md의 내용과 달리 skill의 본문은 사용될 때만 로드되므로, 긴 참고 자료도 필요해지기 전까지는 비용이 거의 들지 않습니다. CLAUDE.md 자체는 CLAUDE.md 작성법을 참고하세요.

문서는 커스텀 명령어가 skills에 통합되었다고도 설명합니다. .claude/commands/deploy.md 파일과 .claude/skills/deploy/SKILL.md skill은 둘 다 /deploy를 만들고 똑같이 동작하며, 기존의 .claude/commands/ 파일도 계속 동작합니다. skills가 더하는 것은 보조 파일을 담는 디렉터리, 사용자와 Claude 중 누가 호출할지 제어하는 frontmatter, 그리고 Claude가 관련이 있을 때 자동으로 로드하는 기능입니다.

첫 skill 만들기

이 예시는 문서에서 가져온 것으로, git 저장소의 커밋되지 않은 변경 사항을 요약하고 위험한 부분을 짚어 주는 skill입니다. 먼저 개인 skills 폴더에 디렉터리를 만듭니다. 개인 skills는 모든 프로젝트에서 사용할 수 있습니다.

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

둘째, SKILL.md를 작성합니다. 모든 skill에는 이 파일이 필요하며 두 부분으로 구성됩니다. --- 표시 사이에 Claude가 skill을 언제 쓸지 알려 주는 YAML frontmatter와, skill이 실행될 때 Claude가 따르는 지침을 담은 마크다운 내용입니다.

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

디렉터리 이름(name을 frontmatter에 지정했다면 그 값)이 입력하는 명령어가 되고, description은 Claude가 skill을 언제 자동으로 로드할지 판단하는 데 쓰입니다. !`git diff HEAD` 줄은 동적 컨텍스트 주입을 사용합니다. Claude가 skill 내용을 보기 전에 Claude Code가 그 명령을 실행해 줄을 출력으로 대체하므로, 지침에는 현재 diff가 이미 인라인으로 들어간 채 전달됩니다.

셋째, 테스트합니다. git 프로젝트를 열고 아무 파일이나 조금 수정한 뒤 claude를 실행해 Claude Code를 시작하세요. 어느 쪽이든 됩니다.

What did I change?     # matches the description, so Claude can invoke it automatically
/summarize-changes     # or invoke it directly with the skill name

어느 쪽이든 Claude는 수정 내용의 짧은 요약과 위험 목록으로 응답해야 합니다.

skills의 위치

skill을 어디에 저장하느냐에 따라 어떤 세션이 그것을 로드할지 정해집니다. 홈 디렉터리 아래에 저장하면 모든 프로젝트에서 쓸 수 있고, 저장소에 커밋하면 그곳에서 작업하는 모두와 공유하며, 플러그인이나 관리 설정으로 배포하면 팀 전체에 전달됩니다.

두 skill의 이름이 같을 때는 다음과 같습니다(문서 표의 발췌).

• enterprise, personal, project 중 두 곳에 같은 이름이 있으면 enterprise가 personal보다, personal이 project보다 우선합니다. deploy가 ~/.claude/skills/와 프로젝트의 .claude/skills/에 모두 있으면 /deploy는 personal 쪽을 실행합니다.
• skill과 .claude/commands/의 파일: skill이 우선합니다.
• plugin skill과 위의 어느 위치에 있는 skill: plugin skills는 /plugin-name:skill-name으로 네임스페이스가 붙으므로 둘 다 로드됩니다.

규칙이 하나 더 있습니다. 시작한 위치보다 아래에 있는 .claude/skills/ 디렉터리의 skills는 시작할 때 로드되지 않습니다. Claude가 그 하위 디렉터리의 파일을 처음 읽거나 편집할 때 로드됩니다. 그때까지는 / 메뉴에 나타나지 않고 이름으로 호출할 수도 없습니다.

skill을 바꾼 뒤 재시작할 필요는 없습니다. Claude Code가 skill 디렉터리를 감시하므로 ~/.claude/skills/나 프로젝트의 .claude/skills/ 아래에서 skill을 추가, 편집, 삭제하면 현재 세션 안에서 바로 적용됩니다. 세션을 시작할 때 없던 최상위 skills 디렉터리를 만들었다면 /reload-skills를 실행하세요.

가장 중요한 frontmatter 필드

모든 필드는 선택 사항이며 description만 권장됩니다. 필드 이름은 하이픈을 포함해 표와 정확히 일치해야 합니다. Claude Code는 인식하지 못하는 필드를 오류 없이 무시합니다. 불리언 필드는 true, false 외에도 대소문자를 가리지 않고 yes, no, on, off, 1, 0을 받습니다.

문서에는 model, effort, agent, background, hooks, shell, metadata, license, compatibility를 포함해 더 많은 필드가 나열되어 있으며, 여기서는 다루지 않습니다. 한 가지 주의할 점이 있습니다. Claude Code는 여는 ---가 파일의 첫 줄일 때만 frontmatter를 읽습니다. 그렇지 않으면 --- 표시를 포함한 파일 전체를 skill 내용으로 취급합니다.

직접 호출할지 Claude가 고르게 할지

기본적으로 사용자와 Claude 모두 어떤 skill이든 호출할 수 있습니다. 사용자는 /skill-name을 입력해 직접 호출하고, Claude는 대화와 관련이 있을 때 자동으로 로드할 수 있습니다. 두 frontmatter 필드가 이를 제한합니다.

• disable-model-invocation: true: Claude가 스스로 skill을 호출할 수 없습니다. /commit, /deploy, /send-slack-message처럼 부작용이 있거나 시점을 직접 통제하고 싶은 워크플로에 쓰세요. 코드가 준비된 것 같다는 이유로 Claude가 배포를 결정하는 것은 원치 않을 것입니다.
• user-invocable: false: Claude만 skill을 호출할 수 있습니다. 오래된 시스템의 동작 방식을 설명하는 legacy-system-context skill처럼 명령어로 실행할 수 없는 배경 지식에 쓰세요.

문서의 배포(deploy) 예시입니다.

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

Deploy $ARGUMENTS to production:

1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

그래도 Claude가 시도하면 Claude Code가 그 호출을 막고, 배포 단계를 다른 방식으로 재현하지 말라고 지시합니다. 따라서 Claude가 사용자에게 직접 /deploy를 실행하라고 제안할 것으로 예상하세요.

skill을 직접 실행하려면 메시지 맨 앞에 이름을 넣으세요. /deploy staging은 skill을 직접 실행합니다. go ahead and /deploy to staging처럼 일반 텍스트 뒤에 오면 직접 실행되는 것은 없습니다. 이 경우 이름은 해당 메시지에 대한 허가로 간주됩니다. Claude는 응답하는 동안 skill을 실행할 수 있고, 사용자의 표현을 보고 실행을 요청했는지 판단합니다. 실행을 허가하지 않고 skill에 대해 쓰고 싶다면 슬래시를 빼세요.

인자와 보조 파일

skill을 호출할 때 사용자와 Claude 모두 인자를 전달할 수 있습니다. 인자는 $ARGUMENTS 자리표시자로 사용할 수 있으며, skill 이름 뒤에 오는 내용으로 치환됩니다.

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit

/fix-issue 123을 실행하면 Claude는 "Fix GitHub issue 123 following our coding standards..."를 받습니다. 개별 인자를 위치로 접근하려면 $ARGUMENTS[N]이나 더 짧은 $N을 사용합니다. 인자와 함께 skill을 호출했는데 skill 내용에 인자를 받는 자리표시자가 없으면, Claude Code는 skill 내용 끝에 ARGUMENTS: <your input>를 덧붙여 Claude가 입력한 내용을 그래도 볼 수 있게 합니다.

skill 디렉터리에는 여러 파일을 둘 수 있습니다. 그러면 SKILL.md는 핵심에 집중하고, Claude는 필요할 때만 상세한 참고 자료를 읽습니다.

my-skill/
├── SKILL.md (required - overview and navigation)
├── reference.md (detailed API docs - loaded when needed)
├── examples.md (usage examples - loaded when needed)
└── scripts/
    └── helper.py (utility script - executed, not loaded)

Claude가 각 파일에 무엇이 있고 언제 로드해야 하는지 알 수 있도록 SKILL.md에서 보조 파일을 참조하세요.

## Additional resources

- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)

문서의 팁: SKILL.md는 500줄 이하로 유지하고, 상세한 참고 자료는 별도 파일로 옮기세요.

좋은 description 쓰기

• 사용자가 자연스럽게 말할 키워드를 쓰세요. 문서의 문제 해결 목록에서 첫 번째 항목은 description에 그런 키워드가 있는지 확인하라는 것입니다. 위 예시는 트리거를 직접 밝힙니다. "Use when the user asks what changed, wants a commit message, or asks to review their diff."
• 핵심 사용 사례를 앞에 두세요. description과 when_to_use를 합친 텍스트는 skill 목록에서 1,536자에서 잘립니다.
• 너무 자주 발동하면 더 구체적으로 쓰세요. 원치 않을 때 skill이 트리거되는 경우 문서가 가장 먼저 제안하는 방법입니다.
• 꺾쇠 괄호는 이스케이프됩니다. description과 when_to_use의 <와 >는 <와 >로 표시됩니다. <branch> 같은 자리표시자를 보여 주려면 대괄호 [branch]를 쓰거나 별도의 argument-hint 줄로 옮기세요.
• 본문은 짧게 유지하세요. skill이 로드되면 그 내용은 턴을 넘어 컨텍스트에 남으므로 모든 줄이 반복되는 토큰 비용입니다. 어떻게, 왜를 서술하기보다 무엇을 할지를 쓰세요.

문제 해결

skill이 트리거되지 않을 때

• description에 사용자가 자연스럽게 말할 키워드가 들어 있는지 확인하세요.
• What skills are available?에 대한 답에 skill이 나타나는지 확인하세요.
• description에 더 가깝게 맞도록 요청을 다시 표현해 보세요.
• skill이 사용자 호출 가능하다면 /skill-name으로 직접 호출하세요.
• /skill-name도 인식되지 않는다면, Claude Code가 skill 이름을 거부했는지 확인하세요(폭 없는 공백, 제어 문자, <, > 같은 문자가 원인이 됩니다).
• skill에 paths를 설정했다면, Claude가 읽고, 편집하고, 쓰는 파일이 Claude의 현재 작업 디렉터리 안에 있는지 확인하세요. 형제 git worktree의 파일처럼 그 밖에 있는 파일에는 skill이 활성화되지 않으며, /add-dir로 추가한 것이어도 마찬가지입니다.

frontmatter YAML의 형식이 잘못되면 Claude Code는 메타데이터를 비운 채 skill 본문을 로드하므로, /skill-name은 여전히 동작하지만 Claude가 description과 대조할 수 없습니다. --debug로 실행하면 파싱 오류를 볼 수 있습니다. frontmatter가 파싱되지 않는 SKILL.md 파일을 찾으려면 skills 디렉터리에 claude plugin validate를 실행하세요. 예: claude plugin validate .claude/skills 또는 claude plugin validate ~/.claude/skills. Claude Code v2.1.233 이상이 필요합니다.

skill이 너무 자주 트리거될 때

description을 더 구체적으로 만드세요. 수동으로만 호출하고 싶다면 disable-model-invocation: true를 추가하세요.

Claude가 skill을 따르지 않게 될 때

skill이 호출되면 Claude Code는 그 내용을 대화에 추가하고 이후 턴에서 파일을 다시 읽지 않습니다. 그러므로 작업 전체에 적용되는 지침은 "Run the tests"가 아니라 "Run the tests after every edit"처럼 표현하세요. compact 후에는 Claude Code가 호출된 skill의 앞부분만 유지할 수 있으므로, 가장 중요한 지침을 SKILL.md 위쪽에 두고, 전체 내용을 복원하려면 skill을 다시 호출하세요. 매번 반드시 지켜야 하는 규칙에는 문서가 hook을 대신 쓰라고 권장합니다.

description이 잘릴 때

skills가 많으면 Claude Code는 목록의 글자 수 예산에 맞추려고 일부 description을 버리며, 이는 Claude가 요청을 매칭하는 데 필요한 키워드를 없앱니다. 예산은 모델 컨텍스트 윈도우의 1%에 비례하며, description은 가장 적게 호출한 skill부터 버려집니다. /doctor를 실행하면 목록의 컨텍스트 비용과 가장 큰 요인에 대한 추정치를 볼 수 있습니다.

FAQ

출처

• Claude Code: Extend Claude with skills (skill 위치, 이름 충돌, frontmatter 필드, 호출 제어, 인자, 보조 파일, 문제 해결)