Claude Skills in Practice Claude Skills 실전 가이드

The Complete Guide to Building Skills for Claude

개발자와 팀을 위한, 단계를 밟아 가는 안내서.
SOP와 전문 지식을 자동화된 업무 흐름으로 바꾸기까지.

먼저 개념: Skill이란 무엇인가

Skill은 지시와 절차를 담은 폴더입니다. 대화할 때마다 배경을 다시 설명하지 않아도, 당신 고유의 진행 방식을 Claude가 정확히 쥐게 할 수 있습니다.

표준적인 Skill 폴더의 내용물:

  • SKILL.md(필수) 중심이 되는 지시. 언제 켜질지 정하는 YAML 머리말을 포함합니다.
  • scripts/(선택) 실행할 수 있는 자동화 스크립트(Python, Bash 등).
  • references/(선택) Claude가 필요할 때 읽는 참고 자료와 안내서.

듣는 지점: 한 번 가르치면 그다음부터 계속 듣습니다. 팀 산출물의 형태도 고르게 맞습니다.

단계를 밟는 개발 경로 (The Staircase)

Step 1. 용도와 상황을 정한다

쓰임새를 분명히 하고 켜지는 조건과 목표를 정한 뒤, 외부 도구(MCP)가 필요한지 봅니다.

Step 2. 뼈대를 만든다

폴더를 만들고 필수인 SKILL.md를 두고, kebab-case 이름 규칙을 엄격히 지킵니다.

Step 3. 지시를 쓴다

YAML의 방아쇠 말을 정확히 정하고, 단계적으로 여는 원칙에 따라 Markdown 지시를 씁니다.

Step 4. 시험하고 배포한다

먼저 단일 작업을 손으로 시험해 API와 동작에 문제가 없음을 확인한 뒤 ZIP으로 묶어 팀에 배포합니다.

MCP와 Skills의 조합

The Connectivity
MCP
바깥과 잇는 힘
(What Claude can do)

도구에 혼을 넣는 두뇌

MCP(Model Context Protocol)가 바깥과 잇는 '손발' — Notion을 읽고 Linear에 과제를 세우는 — 이라면, Skills는 그 도구를 어떻게 제대로 쓸지 알려 주는 '두뇌'입니다.

Skill이 없는 MCP: 도구함을 앞에 두고 어디부터 손댈지 몰라, 매번 복잡한 지시를 다시 씁니다.

Skill이 있는 MCP: 기본 흐름이 알아서 켜지고, 정석이 주고받을 때마다 심어집니다. 익힐 것이 줄어듭니다.

자주 쓰이는 세 가지 (Use Cases)

1. 문서와 산출물 생성

형태와 질이 고른 산출물을 만들 때. 브랜드 지침, 템플릿 구조, 공개 전 체크리스트를 심을 수 있습니다. (외부 도구 불필요)

2. 업무 흐름 자동화

손이 많이 가는 흐름에 어울립니다. Claude가 순서대로 밟게 하고 확인 장치도 넣을 수 있습니다. 여러 MCP 서버를 묶는 일이 많아집니다.

3. MCP 보강

이미 있는 MCP 서버를 보강할 때. 영역 지식을 넣고(Sentry로 버그를 자동 분석하는 등), 문맥을 자동으로 더하고, 흔한 API 실수를 미리 막습니다.

YAML 쓰는 법: 여기서 생사가 갈린다

이름 짓는 규칙 (Naming)

Claude는 폴더 이름과 파일 이름의 형태에 아주 까다로워서, 사소한 차이에도 Skill이 읽히지 않습니다.

  • 주 파일 이름은 정확히 SKILL.md(대소문자를 구분합니다. skill.md는 안 됩니다)
  • 폴더와 name: 항목에는 다음을 씁니다 kebab-case.
  • 엄금 공백, 대문자, 밑줄을 넣지 말 것(예: Notion_Setup는 틀립니다)
  • 두지 말 것: README.md을 Skill 바로 아래에

설명과 방아쇠 말 (Description)

Description은 Claude가 스스로 Skill을 켤지 판단하는 유일한 근거입니다. 1024자 미만으로 씁니다.

  • 둘 다 반드시 씁니다: '무엇을 할 수 있는가'와 '언제 쓰는가'(구체적인 방아쇠 말)
  • 예: "디자인 원고를 읽어 낼 때 쓴다. 사용자가 fig 파일을 올렸을 때, 또는 『디자인 사양』을 요청했을 때."
  • 보안상 금지: YAML 안에서 XML 태그 < >를 쓰지 말 것. 프롬프트 인젝션을 막기 위해서입니다.

지시를 쓰는 정석 (Best Practices)

구체적이고 실행할 수 있게

막연한 지시는 피합니다. "데이터를 잘 검증한다"가 아니라 이렇게 씁니다. "scripts/validate.py을 실행하고, 오류가 나면 필수 항목이 빠졌는지 확인한다." 코드는 말보다 애매함이 없습니다.

단계적으로 열기

토큰을 너무 쓰지 않도록, SKILL.md은 중심 절차만 남깁니다. 자세한 API 사양이나 큰 틀은 references/ 폴더로 옮겨, Claude가 필요할 때 읽으러 가게 합니다.

미리 오류에 대비하기

일어날 수 있는 오류를 내다보고 고치는 법까지 적어 둡니다. 예컨대 「자주 있는 문제」 절을 두고, "연결이 거부되면 설정 > 확장 기능에서 다시 연결해 주세요." 사람이 끼어드는 횟수가 뚜렷하게 줄어듭니다.

실전 예 하나: 코드 리뷰 도우미

단일 작업의 표준 형태

외부 MCP를 쓰지 않는 표준적인 SKILL.md 쓰는 법입니다. 요점은 분명한 전제 조건과 실수를 막는 장치.

  • YAML 부분: 켜지는 조건을 정확히 정한다.
  • Role(역할): Claude에 전문가의 시선을 준다.
  • Workflow(절차): 번호로 순서를 강제한다.
  • Rules(하지 말 것): '하지 않을 일'을 밝혀 지나친 개입을 막는다.
---
name: strict-pr-reviewer
description: 사용자가 코드 조각을 올렸을 때, 또는 코드 리뷰를 요청했을 때 켜진다.
---

# Role
당신은 엄격하고 경험 많은 백엔드 설계자입니다.

# Workflow
켜지면 다음 절차를 순서대로 실행하세요:
1. **보안 점검**: SQL 인젝션이나 그대로 박힌 비밀번호가 없는지 본다.
2. **성능 평가**: 계산량이 O(N^2)를 넘는 작성법을 짚는다.
3. **보고서 산출**: 수정안을 Markdown 표로 제시한다.

# Rules
- 다시 쓴 완전한 코드를 **주지 말 것**.
- 구체적인 고치는 법과 생각의 갈래만 제시할 것.

실전 예 둘: MCP에 잇는 자동화

---
name: linear-bug-reporter
description: 대화 속 오류 로그를 그대로 Linear 과제로 만든다.
---

# Objective
오류 로그를 읽어 내고, `linear` MCP를 스스로 써서 버그 티켓을 세운다.

# Instructions
1. 사용자의 Error Log에서 뽑아낸다: 코드, 시각, 있을 수 있는 원인.
2. `linear_create_issue`를 스스로 부른다.
3. Title은 `[Bug] {오류 코드}` 형태로 한다.

# Error Handling (Fallbacks)
- `linear`를 못 찾거나 연결에 실패했을 때 **사과하지 말 것**.
- 그대로 바꾼다: Markdown 버그 보고서를 내고 사용자가 손으로 옮기게 한다.

손이 많이 가는 흐름과, 실패했을 때의 퇴로

Claude를 RPA처럼 외부 API를 부르게 하면서, 스스로 추스르는 갈래까지 갖게 한 예입니다.

  • Objective(목적): 이 절차가 끝내 무엇을 이루는지 한 문장으로.
  • 도구를 부르는 지시: 부를 도구의 이름을 분명히 쓴다(예: linear_create_issue).
  • Fallback(퇴로): 여기가 요점입니다.MCP는 끊긴다고 보고, 도구를 못 쓸 때 글로 출력하도록 바꾸는 법을 Claude에 미리 일러 둡니다. 흐름이 중간에 멎지 않습니다.

시험하고 확인하는 단계

"먼저 단일 작업에서 Claude가 완벽히 해내는 것을 확인하고, 그 잘된 형태를 뽑아 Skill로 굳힌다."

시험하는 법 전체: 세 가지 관점

관점 확인하려는 것 재는 법 (Metrics)
켜짐 확인 (Triggering) 필요한 자리에서 제대로 읽히고, 관계없는 이야기에서는 나서지 않을 것. 관련된 요청의 90%에서 자동으로 켜진다(손으로 부르지 않아도 된다). 관계없는 지시에는 잠자코 있는다.
동작 확인 (Functional) 절차가 생각한 대로 결과를 내고, 가장자리 경우도 제대로 다룰 것. 처리되지 않은 API 오류가 0. 도구 호출이 모두 성공. 출력 형태가 고르다.
효과 비교 (Performance) Skill을 넣은 뒤의 흐름이, 사람이 손으로 이끌던 때보다 효율이 낫다고 보일 것. 주고받는 횟수가 크게 준다. 쓰는 토큰이 준다. 사용자가 고치러 들어오지 않아도 된다.

한발 더: 다섯 가지 형태

  • 순서대로 늘어놓기 (Sequential Workflow): 단계 1부터 단계 N까지를 엄격히 정합니다. 앞뒤 의존이 있는 일에 어울립니다. 예를 들어 '고객을 등록한다 → 결제를 설정한다 → 환영 메일을 보낸다'.
  • 여러 MCP를 넘나들기 (Multi-MCP): 서비스를 넘나들며 엮습니다. Figma에서 내보내고(MCP 1), Google Drive에 저장하고(MCP 2), Linear에 과제를 세웁니다(MCP 3).
  • 되풀이하며 다듬기 (Iterative Refinement): '초안을 낸다 → 스크립트로 검증한다 → 자동으로 고친다'는 닫힌 고리를 만들어, 질이 닿을 때까지 끝내지 않습니다.
  • 문맥으로 가르기 (Context-aware): Claude에 판단의 나무를 줍니다. "10MB를 넘는 파일이면 클라우드 스토리지 MCP, 코드면 GitHub MCP."
  • 영역 지식 주입 (Domain-specific): API를 부르기 전에 규정 확인이나 리스크 판단을 끼웁니다. 경험 많은 전문가처럼 굴게 하기 위해서입니다.

마지막 걸음: 묶어서 배포

묶는 법과 넣는 법: 시험을 마쳤으면 폴더를 .zip로 묶습니다. 개인은 Claude.ai에서 올릴 수 있습니다. 기업 관리자는 Workspace 전체에 배포할 수 있습니다(자동으로 갱신됩니다).

공개와 API: Skill은 GitHub에 둘 수 있습니다. 설치 절차를 README.md에 알기 쉽게 써 두세요. 앱을 개발한다면 API의 container.skills로 부를 수도 있습니다.

어떻게 보일 것인가: 알릴 때는 기술이 아니라 성과 쪽으로 붙입니다. "이 Skill은 몇 초 만에 프로젝트 초기 설정을 끝냅니다"라고 말할 수 있다면, MCP와 Skill은 그대로 강점이 됩니다.

자기만의 Skill을 만들 준비가 되셨나요

"지식으로 도구를 움직이고, 자동화를 팀의 표준으로"

우선 내장된 skill-creator부터 시작해 보세요.