레슨 3: 실습: 첫 스킬 작성하기

학습 목표:

• 스킬의 디렉터리 구조 만들기
• 완전한 SKILL.md를 처음부터 작성하기
• 점진적 공개 원칙 이해하기
• 만든 스킬을 처음으로 호출해 보기

전제: << 레슨 2 | 다음: 레슨 4 >>

무엇을 만드는가

이번 레슨에서는 아무것도 없는 상태에서 실제로 쓸 수 있는 스킬 하나를 만듭니다. 바로 태스크 정리 도구입니다.

하는 일:

• 입력: 어수선하게 쌓인 할 일들(흩어진 텍스트, 스크린샷에서 뽑아낸 텍스트, 회의록)
• 출력: 우선순위와 마감일로 묶은 깔끔한 목록

왜 이것을 고르는가:

• 단순합니다 — 복잡한 로직이 앞을 가리지 않습니다
• 쓸모 있습니다 — 오늘부터 바로 쓸 수 있습니다
• 스킬 구조의 핵심 부분을 빠짐없이 다뤄 봅니다

1단계: 디렉터리와 파일 만들기

터미널을 열고 다음을 실행합니다.

이제 디렉터리 구조는 다음과 같습니다.

~/.claude/skills/└── task-organizer/    └── SKILL.md

평소 쓰는 텍스트 편집기(VS Code, Cursor 등 무엇이든)로 SKILL.md를 엽니다.

2단계: 프론트매터 작성하기

파일 맨 위의 메타데이터부터 시작합니다. ¹

체크리스트:

• ✓ name이 소문자와 하이픈으로 되어 있다
• ✓ description이 무엇을 하는지(할 일을 정리한다), 무엇을 입력으로 받는지(어수선한 목록), 언제 꺼내 쓰는지(회의 액션 아이템, 프로젝트 백로그)를 담고 있다

3단계: 제목과 소개 작성하기

프론트매터 뒤에 제목을 추가합니다.

제목과 소개를 굳이 쓰는 이유:

• 제목은 사람을 위한 것입니다 — 석 달 뒤에 이 파일을 다시 열어도 한눈에 용도가 떠오릅니다
• 소개는 Claude를 위한 것입니다 — description에 담을 자리가 없었던 세부 내용을 채워 줍니다

4단계: 입력 형식 정의하기

어떤 종류의 입력을 받을지 Claude에게 알려 줍니다. ²

이 섹션이 해내는 일:

• 이 스킬이 마주칠 수 있는 입력 형태를 빠짐없이 열거한다
• 구체적인 예시를 하나 제시해, 실제 입력이 어떤 모습인지 Claude가 알게 한다

5단계: 처리 단계 작성하기

여기가 지시문의 심장부이며, 구체적으로 써야 합니다. ²

이렇게까지 자세히 쓰는 이유:

Claude는 사람이 아니어서 "알아서 헤아려" 주지 않습니다. "우선순위를 부여한다"라고만 쓰면 어떤 기준을 적용해야 할지 알 수 없습니다. "'긴급'을 포함 → 긴급"이라고 쓰면 추측할 여지가 남지 않습니다. ³

6단계: 출력 형식 정의하기

결과가 어떤 모습이어야 하는지 Claude에게 알려 줍니다.

예시가 가져다주는 것:

예시를 한 번 본 뒤로는 배치, 기호, 서식이 확정됩니다. 이모지가 어디에 붙는지, 시간이 작업 앞에 오는지 뒤에 오는지 추측할 필요가 없습니다.

7단계: 엣지 케이스 처리하기

이례적인 경우를 어떻게 다룰지 명시합니다.

완성된 파일

이제 SKILL.md는 다음과 같은 모습이어야 합니다.

파일을 저장합니다.

8단계: 첫 호출

Claude Code를 열고 다음과 같이 입력합니다.

/task-organizer
분기 보고서 마무리PR #234 리뷰, 금요일까지내일 로그인 버그 수정문서 업데이트긴급: 고객이 결제 문제 제보

Claude는 다음과 같이 응답해야 합니다.

### 🔴 긴급- 로그인 버그 수정 - 내일- 고객이 제보한 결제 문제 - 마감 없음
### 🟡 중요- PR #234 리뷰 - 금요일
### ⚪ 보통- 분기 보고서 마무리 - 마감 없음- 문서 업데이트 - 마감 없음

출력이 기대와 다르더라도 당황하지 마세요. 다음 레슨 전체가 디버깅에 관한 내용입니다.

점진적 공개: 왜 모든 세부 사항을 처음부터 쓰지 않는가

이 스킬에는 다른 작업에 의존하는 작업이나, 서로 다른 사람에게 배정된 작업에 관한 이야기가 전혀 없다는 것을 눈치챘을지도 모릅니다. ^{3 2}

의도한 것입니다.

점진적 공개란, 한꺼번에 모든 것을 쏟아붓는 대신 지금 당장 필요한 것만 Claude에게 주는 것입니다. ³

첫 버전은 핵심 작업만 합니다 — 추출하고, 분류하고, 정렬하는 것. 며칠 써 보고 담당자 배정이 정말로 필요하다고 느껴지면 그때 추가하면 됩니다.

이렇게 해서 얻는 것:

• 짧은 스킬 파일: 소비하는 컨텍스트가 줄고, 로딩이 빨라진다
• 단순한 로직: 잘못될 수 있는 경로가 적어진다
• 핵심 동작이 실제로 작동하는지 빠르게 확인할 수 있다

먼저 1번 버전을 굴러가게 만들고, 그다음 반복하세요. 좋은 스킬은 모두 그렇게 만들어집니다. ³

정리

• 스킬을 만드는 7단계: 디렉터리 → 프론트매터 → 제목 → 입력 → 단계 → 출력 → 엣지 케이스
• 단계는 구체적이어야 한다: "작업을 분석한다"가 아니라 "날짜를 나타내는 말을 찾는다: 오늘, 내일…"
• 예시가 중요하다: 입력과 출력이 실제로 어떤 모습인지 Claude에게 보여 준다
• 점진적 공개: 1번 버전은 핵심 작업만 한다 — 모든 세부 사항을 처음부터 쓰지 않는다
• 호출 방법: /skill-name 뒤에 입력을 붙인다

다음 레슨에서는 스킬의 테스트와 디버깅을 다룹니다. "돌아간다"에서 "제대로 돌아간다"로 넘어가는 단계입니다.

>> 레슨 4: 테스트와 디버깅