Claude Code에 「자주 사용하는 정형 작업」을 기억시키는 방법에는 슬래시 명령어 (Slash Command), 서브 에이전트 (Sub-agent), 그리고 Agent Skills 세 가지가 있다. 이 기사는 세 번째인 Skills를 직접 제작하여 자동으로 발화(Trigger)시키는 단계까지를 다룬다.

• 상정 독자: Claude Code를 일상적으로 사용하고 있으며, .claude/commands나 .claude/agents는 다뤄봤지만 Skills는 아직 손대지 않은 엔지니어
• 전제 환경: Claude Code v2.x (2026년 7월 시점) / macOS 또는 Linux / 에디터는 임의 선택
• 이 기사의 목표: 최소한의 Skill을 1개 만들고, /를 입력하지 않아도 Claude가 상황을 보고 알아서 호출하는 상태로 만들기

「만들었는데 전혀 발화하지 않는다」며 허비하는 시간이 가장 길기 때문에, 그 부분을 중점적으로 해결한다.

• Skill의 실체는 .claude/skills/<name>/SKILL.md 파일 한 장이다.
• frontmatter에 name과 description을 작성하는 것만으로 동작한다.
• Claude는 기동 시 description만을 읽고, 관련이 있다고 판단될 때 비로소 본체를 읽는다 (progressive disclosure). 따라서 description을 어떻게 쓰느냐가 발화율을 결정한다.
• 함정의 9할은 「description이 모호하여 발화하지 않음」, 「본체에 너무 많은 내용을 담아 무거워짐」, 「name 규칙 위반 및 재시작 누락」의 세 가지다.

Skills는 「특정 작업의 방법을 정리한 설명서 폴더」이며, Claude가 스스로 필요하다고 판단했을 때 읽어들인다. 사용자가 명시적으로 호출하는 슬래시 명령어와는 트리거가 다르다.

대략 말하자면, 명령어는 「수동 단축키」, 서브 에이전트는 「병렬 별동대」, Skills는 「알아서 열어주는 매뉴얼」이다.

예시로 「커밋 메시지를 Conventional Commits 형식으로 작성하는」 Skill을 만든다.

1. 폴더와 SKILL.md 만들기

mkdir -p .claude/skills/commit-writer

.claude/skills/commit-writer/SKILL.md:

---
name: commit-writer
description: >
...

2. 인식시키기

추가한 것만으로는 읽히지 않을 때가 있다. 세션을 다시 열거나, /를 한 번 입력하여 Claude가 스킬 목록을 재스캔하게 한다. 인식되었는지 여부는 Claude에게 「사용 가능한 스킬은?」이라고 물어보면 확인할 수 있다.

3. 동작 확인

git add를 한 상태에서 「커밋 메시지 만들어줘」라고 요청한다. /commit-writer라고 입력하지 않았음에도 Claude가 위의 절차에 따라 차이점(diff)을 읽고, Conventional Commits 형식으로 답변한다면 발화 성공이다.

가장 많은 실패 사례. description: 커밋 메시지용과 같이 한 줄로만 적으면, Claude는 「지금이 그 상황인가」를 판단하지 못해 그냥 지나쳐 버린다.

description에는 **「무엇을 하는가」 + 「언제 사용하는가 (트리거가 되는 상황·단어)」**를 3인칭으로 구체적으로 적는다.

# NG: 무엇을 하는가만 적혀 있음
description: 커밋 메시지를 생성한다
# OK: 언제 발화해야 하는지까지 적음
...

발화하지 않을 때는 본체를 수정하기 전에 먼저 description을 의심하라.

Skills의 핵심은 「기동 시에는 description만, 필요해지면 본체를 읽는다」는 단계적 읽기이다. 여기서 SKILL.md 본체에 절차를 수천 줄씩 채워 넣으면, 발화할 때마다 전부가 컨텍스트에 올라가 무거워진다.

본체는 가볍게 유지하고, 긴 절차표·템플릿·샘플은 같은 폴더 내의 별도 파일로 분리하여 필요할 때만 참조하게 한다.

.claude/skills/commit-writer/
├── SKILL.md # 개요와 절차의 골자만(수십 줄)
├── examples.md # 좋은 커밋 예시(필요할 때 읽게 함)
...

SKILL.md 내부에는 "상세한 type 정의는 types-reference.md를 참조"라고 적어두면, Claude는 해당 작업이 필요할 때만 파일을 연다. 본체 = 목차, 상세 = 별도 파일로 확실히 구분한다.

name은 폴더명과 일치해야 하며 kebab-case를 사용한다. name: Commit Writer와 같이 공백이나 대문자를 넣으면 로드되지 않는다. 폴더명이 commit-writer라면 name: commit-writer로 작성해야 한다.

스코프 (Scope): 프로젝트 공유용은 .claude/skills/, 개인 전용은 ~/.claude/skills/이다. 팀원들에게 배포하고 싶은데 personal 측에 두어 "다른 사람에게 나타나지 않는" 실수를 하기 쉽다.

allowed-tools를 지정하지 않으면 모든 도구(tools)를 상속한다. 안전하게 제한하고 싶은 Skill에서는 Bash(git diff:*)와 같이 허용 범위를 명시한다. 반대로 너무 제한하여 필요한 git status가 작동하지 않는 것도 흔한 사례다.

왜 명령어(command)가 아니라 Skills인가? 명령어는 "인간이 실행 타이밍을 기억하고 있다"는 전제가 필요하지만, 실무에서는 타이밍 자체를 잊어버린다. Skills는 description(설명)을 트리거 사전(trigger dictionary)으로 활용함으로써, "이 상황이라면 이 절차"라는 절차적 지식을 Claude 측에 상주 시킬 수 있다. 사용할수록 "그 정형화된 작업, 알아서 해줬네"라는 경험이 늘어나는 것이 이점이다.

Skill은 .claude/skills/<name>/SKILL.md를 배치하기만 하면 된다. frontmatter의 name / description이 핵심이다.

• Claude는 description만을 상시 읽고, 관련 상황 발생 시에만 본체를 연다 (progressive disclosure, 단계적 공개).
• 발화율은 description의 구체성에 의해 결정된다 - 막힌다면 "description이 모호함" → "본체에 너무 많은 내용을 담음" → "name/scope/allowed-tools" 순으로 점검한다.
• 본체는 목차, 상세 내용은 별도 파일. 본체를 가볍게 유지할수록 속도가 빠르고 발화가 안정된다.