클로드 코드 스킬 실전: AI 매뉴얼을 만들고 개선하는 법

이 글은 4부작 중 3편입니다. 2편에서 설계 원칙을 봤다면, 이번 편에서는 작은 SKILL.md를 실제로 만들고 개선하는 흐름을 봅니다.

이 글에서 가져갈 것

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

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

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

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

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

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

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

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

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

marketing

blog-writing

source-based-korean-blog

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

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은 보통 표시용 이름에 가깝고, 호출 이름을 정하는 핵심은 폴더 이름입니다.

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

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

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

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

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

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

# Blog Writing

## 목적

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

## 작성 방식

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

## 자주 하는 실수

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

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

여기서 name을 적었다고 해서 호출 이름이 반드시 name 값으로 정해지는 것은 아닙니다. 일반적인 Claude Code Skill에서는 폴더 이름이 직접 호출 이름이 됩니다. 그래서 이 예시는 폴더도 blog-writing으로 만들었다고 보는 게 자연스럽습니다.

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

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

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

예를 들면 이렇게 요청합니다.

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

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

오히려 그게 정상입니다.

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

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

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에 넣으면 오히려 읽기 어려워집니다.

그때는 파일을 나눕니다.

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. 다시 실행하고 비교합니다

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

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

좋아졌다면 그 방향이 맞습니다.

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

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

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

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

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

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

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

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

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

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

정리하면

3편에서 볼 핵심은 간단합니다.

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

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

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