Claude Code에는 「스킬 (Skill)」이라는 메커니즘이 있습니다. SKILL.md라는 파일을 두는 것만으로, Claude Code가 특정 용어나 커맨드 (Command)에 반응하여 움직이기 시작합니다.

이 기사에서는 SKILL.md의 메커니즘과 구조를, 실제로 만든 zenn-article-generator 스킬을 실례로 들어 해설합니다. Series C는 「AI에 대한 지시를 외부 파일로 관리한다」 시리즈이며, C1은 그 입구가 되는 기사입니다.

시리즈 구성

SKILL.md란 무엇인가

SKILL.md란, Claude Code에게 특정 작업을 맡기기 위한 「전용 명령서」 파일입니다. .claude/skills/<스킬명>/SKILL.md에 배치하면, Claude Code가 자동으로 읽어 들여 사용할 수 있게 됩니다.

스킬을 호출하는 것은 간단합니다. Claude Code의 채팅에서 /zenn-article-generator라고 입력하는 것만으로 해당 스킬이 기동합니다. 혹은 description (설명)에 적은 문구를 자연어로 입력하는 것만으로도 자동으로 호출됩니다. 예를 들어 「다음 기사의 지시서를 만들어줘」라고 입력하면, Claude Code가 zenn-article-generator 스킬이라고 판단하여 읽어 들여 줍니다.

CLAUDE.md와 SKILL.md는 역할이 다릅니다. CLAUDE.md는 프로젝트 전체에 상시 적용되는 규칙을 적는 파일로, Claude Code가 기동할 때마다 읽힙니다. 반면 SKILL.md는 특정 태스크 (Task) 전용 명령서로, 명시적으로 호출되었을 때만 읽힙니다. 「상시 적용 규칙」과 「호출형 전문 명령」이라는 구분법을 기억해 두면 이해하기 쉽습니다.

SKILL.md의 구조

SKILL.md는 크게 3가지 요소로 구성되어 있습니다.

① 프론트매터 (Frontmatter) (name / description)

---
name: zenn-article-generator
description: 언제 사용하는지・무엇을 하는지를 여기에 작성
...

name은 스킬의 식별명이며, 디렉토리명과 일치시킵니다. description은 「언제 호출할 것인가」의 판단 기준이 되는 가장 중요한 필드입니다. Claude Code는 description을 상시 유지하고 있으며, 사용자의 지시가 description의 내용과 일치할 때 스킬을 호출합니다.

② 본문 (마크다운 (Markdown))

프론트매터 아래는 Markdown으로 작성한 지시 내용입니다. 실행 절차・규칙・포맷 (Format)・참조 정보 등을 여기에 상세히 기술합니다.

③ 배치 장소

.claude/
└── skills/
└── zenn-article-generator/
...

디렉토리명이 그대로 스킬명이 됩니다. SKILL.md라는 파일명은 고정입니다.

실제 SKILL.md를 살펴보기

zenn-article-generator 스킬의 실제 SKILL.md 도입부를 인용합니다.

---
name: zenn-article-generator
description: Zenn 기사의 생성 지시서를 작성한다. 「Zenn 기사를 써줘」 「기사 생성 지시서를 만들어줘」 「Series C의 기사를 작성해줘」 「다음 기사의 지시서를 만들어줘」라고 말하면 반드시 사용한다.
...

description에 「기사 생성 지시서를 만들어줘」 「다음 기사의 지시서를 만들어줘」 등의 트리거 문구 (Trigger phrase)를 나열하고 있는 것이 포인트입니다. 또한 「반드시 사용한다」라는 표현을 넣어둠으로써, Claude Code가 호출 타이밍을 놓치는 것을 방지하고 있습니다.

막혔던 점・깨달은 점

SKILL.md를 만드는 것만으로는 작동하지 않았습니다. description에 「언제 사용하는지」를 구체적으로 적지 않으면, Claude Code가 스킬의 존재를 파악하고 있더라도 호출 타이밍을 판단하지 못해 무시되어 버립니다. 「무엇을 하는 스킬인가」뿐만 아니라 「어떤 말로 불렸을 때 움직이는가」를 description에 명시하는 것이 중요합니다.

또 하나, CLAUDE.md와 SKILL.md의 역할 구분을 처음에 이해하지 못했기 때문에, 어느 쪽에 적어야 할지 망설여지는 장면이 있었습니다. 「상시 적용인가・호출형인가」라는 기준을 가지고 있다면 혼란 없이 해결할 수 있습니다. 또한, 스킬의 파일명은 SKILL.md

고정이며, 디렉터리 이름이 스킬 이름이 된다는 점도 처음에는 이해하기 어려웠습니다.

요약

SKILL.md는 Claude Code를 위한 「전용 명령서」입니다. .claude/skills/<스킬 이름>/SKILL.md에 배치하고, 프론트매터 (Frontmatter)의 description에 트리거 문구 (Trigger phrase)를 작성하면 Claude Code가 적절한 타이밍에 호출해 줍니다.

description을 작성하는 방식이 스킬 호출 정밀도를 직접적으로 좌우합니다. 트리거가 되는 문구를 구체적으로 열거하는 것, 「반드시 사용」과 같은 강한 표현을 넣어두는 것이 실용적인 포인트입니다.

다음 회차(C2)에서는 실제로 SKILL.md를 작성하여 claude.ai와 Claude Code 양쪽 환경에 설치하는 절차를 skill-creator를 사용한 경험과 함께 해설하겠습니다.

시리즈 링크 (Series C)

Discussion