반복 프롬프트를 자동 호출로 | Skill 만들기

Overview

Custom Commands 레슨에서 만든 /commit Command 는 슬래시로 호출해야만 동작했습니다. 같은 내용을 Skill로 옮기면 "변경사항 커밋해줘" 같은 자연어에도 자동으로 호출됩니다. 이번 레슨은 commit Skill을 수동으로 한 번, Skill Creator로 한 번 만들어 두 흐름을 비교합니다.

학습 목표

• .claude/skills/<이름>/SKILL.md 구조로 Skill을 수동으로 작성합니다
• 수동 작성에서 막히는 지점 (description·구조 판단)이 어디인지 설명할 수 있습니다
• Skill Creator 플러그인을 설치하고 같은 Skill을 자동 생성해 차이를 체험합니다

시작하기 전 확인사항

• 실습 프로젝트의 시작 브랜치로 전환합니다 (git checkout ch06-04)

ch06-04 브랜치에는 Custom Commands 레슨에서 만든 .claude/commands/commit.md 가 포함돼 있습니다. 이 Command를 Skill로 옮기는 것이 이번 실습의 출발점입니다.

Step 1: 기존 Custom Command 삭제하기

먼저 Custom Commands 레슨에서 만든 /commit Custom Command를 정리합니다. 같은 이름이 두 곳에 있으면 무엇이 호출되는지 헷갈리기 쉬워, Skill로 옮기기 전에 깨끗하게 비웁니다.

rm .claude/commands/commit.md

이제 /commit 은 사라졌습니다. 다음 Step에서 같은 동작을 Skill로 다시 만듭니다.

Step 2: 수동으로 SKILL.md 작성하기

Skill은 마크다운 파일 하나가 아니라 폴더 단위로 저장합니다. 프로젝트 루트에 .claude/skills/commit/ 폴더를 만듭니다.

mkdir -p .claude/skills/commit

폴더 이름이 곧 Skill 이름이 됩니다. 이 폴더 안에 SKILL.md 본체와 선택적으로 참조 파일이 들어갑니다.

.claude/skills/commit/
  SKILL.md                    # Skill 본체 (필수)
  references/                 # 참조 자료 (선택)

.claude/skills/commit/SKILL.md 를 다음과 같이 작성합니다.

---
name: commit
description: Conventional Commit 형식으로 변경사항을 커밋합니다. 코드 변경 후 커밋 요청, "커밋해줘", "변경사항 정리해줘" 요청 시 사용. 단순 git 명령어 질문에는 사용하지 않습니다.
---

# Commit Skill

## 커밋 절차

1. `git status` 와 `git diff --staged` 로 전체 상태를 파악합니다
2. 스테이징된 변경이 없으면 `git diff` 와 `git status` 로 수정된 파일·untracked 파일을 확인하고 관련 파일을 스테이징합니다
3. 변경 내용을 분석해 Conventional Commit 형식으로 메시지를 작성하고 자동으로 커밋합니다

## 커밋 메시지 규칙

- 형식: `<type>(<scope>): <description>`
- type: feat, fix, refactor, test, docs, chore
- scope: 변경된 주요 모듈·컴포넌트 이름
- description: 영어, 소문자, 현재형, 50자 이내

## 예시

- `feat(todo): add filter tabs for completion status`
- `fix(todo-item): resolve checkbox toggle not persisting`

Custom Command와 가장 큰 차이는 frontmatter의 description입니다. 이 한 줄이 Claude의 자동 호출 판단 기준이 됩니다. 위 예시를 세 부분으로 분해하면 이렇게 됩니다.

• 하는 일: "Conventional Commit 형식으로 변경사항을 커밋합니다."
• 긍정 트리거: "코드 변경 후 커밋 요청, '커밋해줘', '변경사항 정리해줘' 요청 시 사용"
• 부정 트리거: "단순 git 명령어 질문에는 사용하지 않습니다"

Step 3: 자동 호출 확인하기

Skill이 수동·자동 두 방식으로 모두 호출되는지 확인합니다.

수동 호출

/commit

자동 호출

변경사항 커밋해줘

자동 호출이 성공하면 프롬프트 밑에 Skill(commit) Successfully loaded skill 이 표시되고, Claude가 커밋 절차를 바로 시작합니다.

수동·자동 모두 동작합니다.

다 됐는데 석연치 않은 세 지점

동작은 합니다. 하지만 수동으로 쓰는 동안 감으로만 처리한 부분이 남습니다.

• description의 트리거가 충분하고 좁은지: "작업 마무리해줘"라고 말해도 호출될까? "git 로그 보여줘" 질문에 끼어들진 않을까? 근거 없이 판단했습니다
• 본문에 빠진 게 없는지: breaking change가 있을 때, co-author 표기가 필요할 때는 어떻게 처리할지 본문에 담지 않았습니다. 놓친 건지 확인할 길이 없습니다
• 참조 파일로 뭘 뺄지 기준: 나중에 references/commit-conventions.md 같은 걸 추가할 때 본문에서 뭘 남기고 뭘 빼야 할지 모호합니다

이 세 지점이 Step 5에서 Skill Creator를 만나며 어떻게 해소되는지 확인합니다.

Step 4: Skill Creator 플러그인 설치하기

Skill은 동작합니다. 다만 Step 3 끝에서 남긴 질문은 아직 해소되지 않았습니다. Anthropic 공식 플러그인인 Skill Creator를 설치해 같은 Skill을 다시 만들어 봅니다.

Claude Code 안에서 /plugin 을 입력해 플러그인 관리 화면을 엽니다.

/plugin

Anthropic 공식 마켓플레이스에서 skill-creator 를 찾아 설치합니다. 설치가 끝나면 /skill-creator 를 입력했을 때 응답이 돌아오는지 확인합니다.

Step 5: Skill Creator로 같은 Skill 다시 만들기

수동으로 만든 commit Skill을 먼저 삭제합니다. 같은 이름이 두 곳에 있으면 자동 호출이 어느 쪽으로 향할지 예측하기 어렵기 때문입니다.

rm -rf .claude/skills/commit

그리고 Skill Creator를 호출합니다.

/skill-creator Conventional Commit 형식으로 커밋하는 Skill을 만들어줘

Skill Creator는 대화로 요구사항을 정리합니다. 예를 들어 이런 질문이 돌아옵니다.

• 어떤 타입을 허용하는지 (feat/fix 만인지, 확장 타입까지인지)
• description 언어·길이 제한이 있는지
• breaking change는 어떻게 표기하는지
• 여러 파일 변경 시 scope를 어떻게 잡는지

Step 3 끝에서 막막했던 세 지점이 Skill Creator의 질문으로 드러납니다. 응답을 모아 SKILL.md를 자동으로 구성하고, description도 샘플 프롬프트 몇 개로 테스트하며 긍정·부정 트리거를 조정합니다. 감으로 적을 때와 달리, 놓친 게 있으면 대화 중에 드러납니다.

Skill Creator가 편한 세 지점

수동으로 써본 뒤 Skill Creator를 쓰면 특히 편한 지점이 세 가지입니다. 감으로 넘어갔던 부분을 Skill Creator가 보완해 줍니다.

description 다듬기

수동으로 쓸 땐 긍정·부정 트리거가 맞는지 감으로 판단했습니다. Skill Creator로 description을 다양한 샘플 프롬프트로 테스트해 의도한 자연어가 실제로 트리거되는지 확인할 수 있습니다.

본문과 참조 파일 분리

뭘 SKILL.md 본문에 두고 뭘 references/ 로 뺄지 기준이 모호했습니다. Skill Creator를 쓰면 Progressive Disclosure를 의식해 "매번 필요한 것 / 조건부로 필요한 것"으로 나눠 제안을 받습니다.

누락 확인

수동으로 썼을 땐 빠진 게 없는지 알 길이 없었습니다. Skill Creator의 질문이 놓치기 쉬운 부분을 짚어줍니다. Step 5에서 봤던 질문 목록이 좋은 예시입니다.

세 지점 모두 Skill Creator를 쓰면 더 편합니다. 수동 작성이 더 편하다면 그것도 좋은 선택입니다. 결과물인 SKILL.md는 어느 쪽으로 만들든 같은 파일입니다.

Skill이 자라는 방향

Skill은 처음부터 완벽할 필요가 없습니다. 한 파일만 있다가, 사용하면서 참조 자료를 하나씩 덧붙이는 방식이 가장 현실적입니다.

.claude/skills/commit/
  SKILL.md                         # 시작: 본문만
  references/
    commit-conventions.md          # 나중 추가: 타입별 예시 모음
    breaking-change-guide.md       # 나중 추가: breaking change 감지 규칙

SKILL.md 안에서 "breaking change가 감지되면 references/breaking-change-guide.md 를 읽는다"처럼 조건부로 참조 파일을 가리키면, Claude는 그 조건을 만났을 때만 참조 파일을 읽습니다.

핵심 포인트 정리

1. Skill은 폴더 단위 + description이 자동 호출의 열쇠: .claude/skills/<이름>/SKILL.md 로 만들고, description의 세 조각 (하는 일 + 긍정 트리거 + 부정 트리거)이 자동 호출 정확도를 결정합니다.
2. 수동 작성에서 막막한 부분은 Skill Creator로 해소: description 튜닝·본문/참조 분리·누락 확인을 도구의 도움으로 채웁니다. 수동이 익숙하다면 그것도 좋은 선택입니다.
3. Command를 Skill로 옮기면 수동 호출이 자동 호출로: /commit 같은 슬래시 입력 외에도 "커밋해줘" 같은 자연어에 반응합니다.

FAQ

• Q: Command와 Skill에 같은 이름이 둘 다 있으면 어떻게 되나요?

  • A: 공식 동작은 Skill이 우선입니다. /commit 입력 시 Skill이 호출되고, 자연어 호출도 Skill 자동 판단으로 넘어갑니다. 충돌은 없으므로 Command를 유지해도 되고 .claude/commands/commit.md 를 정리해도 됩니다.

• Q: Skill이 원치 않는 상황에서 자동 로드됩니다

  • A: description에 부정 트리거를 추가합니다. 예를 들어 "단순 git 명령어 질문에는 사용하지 않음" 처럼 제외 조건을 명시하면 Claude가 해당 상황에서 Skill을 로드하지 않습니다.

• Q: Skill의 자동 호출을 끄고 싶을 때는요?

  • A: SKILL.md의 frontmatter에 disable-model-invocation: true 를 추가하면 사용자가 /skill-name 으로 직접 부를 때만 로드됩니다. 배포·데이터 삭제처럼 실수가 치명적인 작업에 권장합니다.

이어서 배울 내용

Skill을 직접 만드는 방법을 익혔습니다. 그런데 모든 Skill을 직접 만들 필요는 없습니다. Anthropic 공식 플러그인과 커뮤니티 Skill을 그대로 가져다 사용할 수 있습니다. 다음 레슨에서는 Skill 마켓 두 곳(Plugin과 skills.sh)을 비교하고, shadcn Skill을 설치해 Todo 앱에 적용해 봅니다.

• /plugin 으로 Anthropic 공식 Plugin 설치
• npx skills add 로 커뮤니티 Skill 설치
• 직접 만들기 vs 가져다 쓰기 판단 기준