Claude Code Skill 만들기: SKILL.md로 시작해 개선하는 법 (실전편)

이 글의 성공 기준은 분명합니다. 끝까지 읽고 나서 작은 SKILL.md 하나를 만들고, 한 번 실행해본 뒤, 마음에 안 드는 결과를 gotchas로 바꿀 수 있으면 성공입니다.

1. 먼저 “반복되는 일” 하나만 고릅니다

처음부터 회사 전체 업무를 자동화하려고 하면 막힙니다.

스킬은 이렇게 시작하는 편이 좋습니다.

매번 비슷하게 시키는 일 하나를 고른다.

예를 들어 블로그 작업에서는 이런 일이 반복됩니다.

• 공식 글을 읽고 한국어 초보자용 블로그로 바꾸기
• 원문 사실과 내 해설을 분리하기
• 제목, 설명, 태그를 함께 만들기
• 발행 전에 링크와 코드블록을 확인하기

이 중에서 처음 스킬로 만들기 좋은 것은 하나입니다.

공식 자료를 바탕으로 한국어 블로그 초안을 만든다.

너무 넓은 이름은 피합니다.

marketing

blog-writing

source-based-korean-blog

다만 처음에는 너무 잘게 쪼개지 않아도 됩니다. 이 글에서는 blog-writing이라는 이름으로 시작하겠습니다.

잠깐 멈춰서 내 일에도 적용해보세요.

나는 AI에게 자주 ________를 부탁한다.
이때 항상 ________ 기준을 지켜야 한다.
AI는 자주 ________를 빼먹는다.

2. 최소 폴더는 이렇게 생겼습니다

Claude Code Skills에서 꼭 필요한 파일은 SKILL.md입니다.

파일 이름은 정확히 대문자 SKILL.md여야 합니다.

공식 문서 기준으로 SKILL.md는 크게 두 부분으로 나뉩니다.

1. 위쪽 YAML frontmatter
2. 아래쪽 Markdown 본문

YAML frontmatter는 --- 사이에 적는 설정 영역입니다. 여기에는 보통 description을 적습니다. 이 설명은 사람이 읽는 소개글이라기보다, Claude가 “이 요청에는 이 스킬을 불러야겠다”라고 판단할 때 보는 신호입니다.

또 하나 헷갈리기 쉬운 점이 있습니다. 일반적인 Claude Code Skill에서는 폴더 이름이 직접 호출할 때 쓰는 명령 이름이 됩니다. 예를 들어 폴더가 blog-writing이면 사용자는 /blog-writing처럼 부를 수 있습니다. name은 보통 표시용 이름에 가깝고, 호출 이름을 정하는 핵심은 폴더 이름입니다.

실제 위치는 쓰는 범위에 따라 달라집니다. 초보자는 아래 표 정도만 기억하면 됩니다.

처음 실습은 프로젝트 안의 .claude/skills/blog-writing/SKILL.md 구조를 떠올리면 이해하기 쉽습니다.

처음부터 references/, templates/, scripts/를 다 만들 필요는 없습니다.

먼저 SKILL.md 하나로 실제 결과가 나오는지 확인하는 게 좋습니다.

공식 문서의 첫 예시는 “변경사항 요약 스킬”입니다

공식 문서는 summarize-changes라는 예시로 시작합니다. 이 스킬은 현재 git 변경사항을 읽고, 무엇이 바뀌었는지와 위험한 부분을 요약합니다.

---
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.

여기서 !`git diff HEAD` 표기는 Claude가 추측으로 답하지 않도록, 현재 변경사항을 먼저 읽어 넣는 장치입니다. 초보자는 “스킬 실행 전에 필요한 자료를 자동으로 가져오는 줄” 정도로 이해하면 됩니다.

이 글에서는 같은 원리를 블로그 작성 업무로 바꿔보겠습니다.

3. 첫 SKILL.md는 짧아도 됩니다

처음 버전은 완벽할 필요가 없습니다.

예를 들어 이렇게 시작할 수 있습니다.

---
description: 공식 글이나 문서를 바탕으로 한국어 블로그 초안, 제목 후보, SEO 메타 설명을 작성해야 할 때 사용한다.
---

# Blog Writing

## 목적

공식 자료를 한국어 초보자용 블로그 초안으로 바꾼다.

## 작성 방식

- 단순 번역처럼 쓰지 않는다.
- 공식 자료가 말한 사실과 우리의 해설을 구분한다.
- 초보자가 모를 만한 영어/개발 용어는 먼저 쉽게 설명한다.
- 제목 후보, description, tags를 함께 제안한다.

## 자주 하는 실수

- 출처 링크를 마지막에만 몰아서 넣지 않는다.
- 공식 회사의 주장처럼 과장해서 쓰지 않는다.
- 한국어 문장을 번역투로 쓰지 않는다.

이 정도면 작지만 실제로 써볼 수 있습니다.

공식 문서 기준으로 초보자가 꼭 챙길 것은 description입니다. name은 표시용 이름이라 처음에는 생략해도 됩니다. 호출 이름은 보통 폴더 이름에서 정해집니다. 그래서 이 예시는 폴더를 blog-writing으로 만들었다고 보는 게 자연스럽습니다.

중요한 건 “잘 써줘”가 아니라, 이 작업에서 흔들리기 쉬운 부분을 적는 것입니다.

4. 한 번 실행해보고 결과를 봅니다

이제 이 스킬로 실제 글을 하나 써봅니다.

실행 전에는 세 가지만 확인하세요.

- blog-writing 폴더가 있다.
- 그 안에 SKILL.md가 있다.
- SKILL.md 위쪽에 description이 있다.

스킬을 직접 부를 수 있다면 이렇게 요청합니다.

/blog-writing
Anthropic 공식 블로그를 바탕으로 한국어 초보자용 블로그 초안을 작성해줘.
공식 사실과 우리 해설을 구분하고, SEO 제목과 description도 함께 만들어줘.

직접 호출하지 않는 흐름이라면 이렇게 말해도 됩니다.

이 작업에는 blog-writing 스킬의 기준을 사용해줘.
Anthropic 공식 블로그를 바탕으로 한국어 초보자용 블로그 초안을 작성해줘.

첫 결과는 완벽하지 않을 가능성이 높습니다.

오히려 그게 정상입니다.

처음부터 완벽한 스킬을 기대하기보다, 결과물을 보고 이런 질문을 합니다.

이 질문에서 나온 답이 다음 수정 재료가 됩니다.

5. 마음에 안 드는 결과를 gotchas로 바꿉니다

Claude Code 팀은 공식 글에서 gotchas를 아주 중요하게 다룹니다.

여기서 gotchas는 어렵게 볼 필요 없습니다.

AI가 이 일을 할 때 자주 틀리는 부분

정도로 보면 됩니다.

이미 ## 자주 하는 실수 섹션이 있다면 새 섹션을 또 만들지 말고, 그 아래에 한 줄씩 추가하면 됩니다.

예를 들어 첫 결과가 단순 번역처럼 나왔다면, SKILL.md에 이렇게 추가합니다.

## 자주 하는 실수

- 공식 글을 문단별로 옮기지 않는다. 한국 독자가 이해해야 할 맥락을 먼저 설명한다.
- “원문에서는”이라는 표현을 반복하지 않는다. “Anthropic은”, “Claude Code 팀은”처럼 자연스럽게 지칭한다.
- 공식 예시는 삭제하지 말고, 공식 원문과 한글 풀이를 분리해서 보여준다.

링크가 마지막에만 몰려 있었다면 이렇게 추가합니다.

## 자주 하는 실수

- 공식 출처 링크를 글 마지막에만 몰아넣지 않는다.
- 특정 공식 주장이나 예시를 설명하는 문장 가까이에 링크를 둔다.

이렇게 하면 다음 실행에서 같은 실수가 줄어듭니다.

6. 뻔한 말보다 실제 실패를 적습니다

스킬에는 이런 문장이 별로 도움이 되지 않습니다.

좋은 블로그를 작성한다.
독자가 이해하기 쉽게 쓴다.
제목과 본문을 포함한다.

AI도 이미 아는 말이기 때문입니다.

공식 글에서는 frontend design skill 예시를 들며, Claude가 자주 반복하던 패턴을 피하게 만드는 식으로 스킬을 개선했다고 설명합니다. 예를 들어 Inter 폰트나 보라색 그라디언트처럼 반복적으로 나오는 디자인 습관을 피하라고 적는 방식입니다.

블로그 작업도 마찬가지입니다.

- 제목을 “AI 자동화의 중요성”처럼 추상적으로 쓰지 않는다.
- 공식 글의 예시를 빼고 요약만 하지 않는다.
- 초보자가 모를 standup, hook, config.json 같은 단어는 나오기 전에 설명한다.

스킬은 멋진 선언문이 아니라, 실패를 줄이기 위한 실전 메모입니다.

7. 반복되는 자료는 references로 뺍니다

처음에는 SKILL.md 하나로 충분합니다.

하지만 스킬을 여러 번 쓰다 보면 이런 내용이 길어집니다.

• 브랜드 톤
• 출처 표시 규칙
• SEO 체크리스트
• 예시 제목 모음
• 발행 전 확인 항목

이걸 전부 SKILL.md에 넣으면 오히려 읽기 어려워집니다.

그때는 파일을 나눕니다.

references는 판단 기준을 담는 곳이고, templates는 결과물의 모양을 담는 곳입니다.

SKILL.md에는 길 안내만 둡니다.

출처 표시는 references/source-attribution.md를 참고한다.
SEO 메타데이터는 references/seo-checklist.md를 참고한다.

이 방식이 2편에서 말한 progressive disclosure입니다.

처음부터 모든 자료를 읽히는 게 아니라, 필요한 순간에 필요한 파일만 보게 만드는 겁니다.

8. 반복되는 형식은 templates로 뺍니다

매번 같은 구조로 결과물을 만들고 싶다면 templates/가 유용합니다.

templates/blog-outline.md에는 이런 식으로 적습니다.

# 블로그 초안 구조

## 도입

- 독자가 겪는 문제
- 왜 지금 이 주제가 필요한지

## 핵심 개념

- 공식 자료가 말한 내용
- 초보자용 한글 설명

## 공식 예시

- 공식 원문
- 한글 풀이
- 실무 적용

## 정리

- 오늘 가져갈 것
- 다음 글로 이어지는 내용

그러면 매번 “블로그 구조는 이렇게 해”라고 길게 설명하지 않아도 됩니다.

9. 검증이 반복되면 scripts로 옮깁니다

공식 글에서 특히 중요하게 말하는 범주 중 하나가 Product verification입니다.

Anthropic은 verification skills가 내부적으로 Claude 출력 품질에 측정 가능한 영향을 크게 줬다고 설명합니다. 그리고 결과를 영상으로 기록하거나, 각 단계마다 프로그램으로 검증하는 방식도 언급합니다.

블로그 작업에서는 이렇게 바꿔볼 수 있습니다.

• 링크가 모두 살아 있는지 확인한다.
• description이 160자를 넘지 않는지 확인한다.
• 코드블록이 짝이 맞는지 확인한다.
• 개인 컴퓨터의 로컬 절대 경로가 남아 있지 않은지 확인한다.

처음에는 사람이 체크해도 됩니다.

하지만 매번 반복된다면 스크립트로 옮길 수 있습니다.

예를 들면 이런 검사를 자동화할 수 있습니다.

description length <= 160
no local absolute paths
balanced code fences
required frontmatter exists

스킬은 “글쓰기 지침”에서 끝나지 않습니다. 반복 검증까지 붙으면 업무가 훨씬 안정됩니다.

10. 다시 실행하고 비교합니다

스킬을 고쳤다면 다시 같은 일을 시켜봅니다.

그리고 이전 결과와 비교합니다.

좋아졌다면 그 방향이 맞습니다. 비교할 때는 표로 남기면 더 선명합니다.

| 확인 항목   | 1차 결과  | 고친 내용        | 2차 결과 |
| ----------- | --------- | ---------------- | -------- |
| 출처 표시   | 부족함    | gotchas 추가     | 개선됨   |
| 용어 설명   | 일부 부족 | 설명 규칙 추가   | 개선됨   |
| 결과물 구성 | SEO 누락  | 필수 결과물 추가 | 개선됨   |

아직 부족하다면 gotchas를 한 줄 더 추가합니다.

이게 스킬을 개선하는 가장 현실적인 방법입니다.

11. 너무 세세하게 묶지는 않습니다

스킬을 고치다 보면 이런 유혹이 생깁니다.

항상 이 순서로만 써.
항상 이 표현만 써.
항상 이 제목 패턴만 써.

하지만 Claude Code 팀은 이런 식으로 Claude를 지나치게 묶어두는 것도 조심하라고 설명합니다.

스킬은 판단을 없애는 장치가 아닙니다.

해야 할 일과 피해야 할 실수는 알려주되, 상황에 맞게 판단할 여지는 남겨둬야 합니다.

공식 사실과 우리 해설을 구분한다.

모든 문단을 반드시 “쉽게 말하면”으로 시작한다.

정리하면

이번 편의 핵심은 간단합니다.

작게 만든다.
실제로 써본다.
마음에 안 드는 지점을 찾는다.
gotchas에 추가한다.
반복되는 자료는 references/templates/scripts로 분리한다.
다시 써보고 비교한다.

처음부터 완벽한 스킬을 만들 필요는 없습니다.

오히려 좋은 스킬은 실제 작업을 하면서 조금씩 좋아집니다.

다음 편