스킬이 뭔가요?
Claude에게 "우리 회사는 이렇게 일해"를 미리 알려주는 업무 매뉴얼
매번 같은 형식, 같은 말투, 같은 구조를 반복 설명하고 계신가요?
스킬은 그 반복을 한 번에 해결합니다.
매번 같은 형식 · 말투를
다시 알려줄 필요 없음
누가 요청해도 동일한
형식의 결과물이 나옴
내가 만든 스킬을
팀원도 바로 활용
스킬 = "내가 원하는 결과물의 레시피"입니다.
한 번 만들어두면, 누구든 같은 품질의 결과물을 뽑아낼 수 있습니다.
→ 좋은 레시피에는 6가지 구성 요소가 있습니다.
잘 만든 스킬의 6가지 구성 요소
이 여섯 가지를 모두 갖춰야 Claude가 정확히 호출하고 일관된 수준으로 응답합니다
트리거 · 언제 호출되는가?
사용자의 어떤 발화 · 키워드 · 입력 형태에 자동 호출될지 description에 명시합니다. 트리거가 약하면 스킬이 있어도 Claude가 호출하지 않습니다.
SKILL.md → description + ## 호출 조건역할 · 누가 수행하는가?
호출되는 순간 Claude가 어떤 정체성 · 관점 · 어조로 응답할지 페르소나를 분명히 정의합니다. 한 명일 수도, 여러 명일 수도 있습니다.
SKILL.md → ## 페르소나평가 기준 · 어떤 기준으로 평가할 것인가?
결과물이 쓸 만한지 판정하는 잣대를 미리 적어둡니다. 기준이 없으면 Claude가 스스로 점검하지 못해 매번 다른 수준이 나옵니다. 점수표와 합격선을 넣으면 스스로 고쳐 씁니다.
SKILL.md → ## 평가 기준절차 · 어떤 순서로 수행해야 하는가?
입력을 받은 뒤의 작업 순서를 단계별로 번호화합니다. 무엇을 먼저 하고 무엇을 마지막에 하는지가 명시될수록 결과가 일관됩니다.
SKILL.md → ## 진행 규칙형식 · 결과는 어떻게 생성할 것인가?
응답의 구조, 필수 섹션, 길이를 템플릿으로 고정합니다. 형식을 잡으면 매번 같은 모양의 답변을 받습니다.
SKILL.md → ## 출력 형식가드레일 · 무엇을 하지 말아야 하는가?
흔한 실패 모드와 스킬 범위 밖 요청을 미리 차단합니다. 하지 말 것을 적어두면 엉뚱한 결과를 막습니다.
SKILL.md → ## 하지 말 것스킬을 만들면 스킬 이름의 폴더가 하나 생깁니다. 그 안에 SKILL.md 한 개만 있어도 스킬은 작동합니다. 절차 · 예시 · 템플릿이 많아지면 아래처럼 폴더로 나눠 담습니다.
Claude는 먼저 description만 읽고, 스킬이 호출되면 SKILL.md 본문을 읽고,
필요할 때만 references/ · assets/를 꺼내봅니다.
자주 안 쓰는 내용을 바깥 파일로 빼두면 본문은 가볍게 유지되고, 스킬은 얼마든지 커질 수 있습니다.
→ 이 단계적 로딩 원리는 7번 참고에서 자세히 다룹니다.
시 쓰기 스킬 만들기
5인 페르소나 팀이 시 한 편을 다각도로 비평하고 4가지 개선 방향을 합의문으로 정리합니다
노을이 붉게 타오르고
낙엽은 바람에 흩날린다
나는 홀로 길을 걷는다
쓸쓸함이 마음에 스며든다
- claude.ai 접속 후 좌측 하단 사용자 지정 클릭
- 스킬 탭 → 우측 상단 + 버튼 → 스킬 만들기
- 스킬 지침 작성 선택 후 아래 SKILL.md 전체를 그대로 붙여넣기
- 저장 → 새 채팅에서
/poem-critique-team입력 후 시 초고 전송
노을이 붉게 타오르고 / 낙엽은 바람에 흩날린다 / 나는 홀로 길을 걷는다 / 쓸쓸함이 마음에 스며든다
Claude Code로 만드는 실전 5단계
업무 하나를 골라 스킬로 만들고, 검증하고, 팀에 공개하기까지
업무 하나를 골라 끝까지 만들어 봅니다. 5단계 내내 하는 일은 두 가지입니다. 준비된 프롬프트를 Claude Code에 붙여넣는 것, 그리고 나온 결과를 보고 판단하는 것. 나머지는 Claude가 합니다.
스킬로 만들 업무 고르기
무엇을 스킬로 만들지 고르는 일이 절반입니다. 아래 5문항 중 3개 이상 해당하면 후보로 올려도 좋습니다.
이미 만들어진 스킬을 먼저 열어봅니다. 다른 사람의 업무가 스킬이 된 사례를 보면 내 업무의 후보도 찾기 쉬워집니다.
작업 폴더 만들고 Claude Code 열기
스킬 이름으로 폴더를 하나 만듭니다. 위치는 어디든 상관없습니다. 예: ~/Desktop/skills-dev/meeting-notes/
클로드 데스크톱 앱에서 Claude Code를 선택하고 방금 만든 폴더를 선택합니다.
아직 .claude/skills/에 넣지 않습니다. 그 폴더에 넣는 순간 Claude가 스킬로 인식해서 부르기 시작합니다. 반쯤 만든 스킬이 엉뚱한 자리에서 호출되면 결과가 어지러워집니다. 설치는 4단계에서 완성한 뒤에 합니다.
skill-creator로 초안 만들기
Claude Code 대화창에 아래 문장을 붙여넣습니다.
skill-creator를 써서 고객 회의록을 표준 형식으로 정리하는 스킬을 만들어줘.
붙여넣으면 Claude가 바로 만들지 않고 먼저 네 가지를 되묻습니다. 이 스킬로 무엇을 할 수 있게 할지, 어떤 말이 나왔을 때 호출될지, 결과물은 어떤 형식일지, 테스트 케이스를 만들어 검증할지입니다. 꼼꼼히 답할수록 초안이 정확해집니다.
여기서 평가하는 대상은 결과물이 아니라 SKILL.md 문서 그 자체입니다. 지시가 빈틈없는지를 봅니다.
방금 만든 SKILL.md를 4인 페르소나로 10점 만점 평가해줘. RED(이성 비평가)는 지시에 논리적 빈틈이 없는지, SILVER(분야 전문가)는 회의록 정리 현장의 디테일과 품질 기준이 반영됐는지, BLUE(공감 비평가)는 읽는 사람 입장에서 지시가 자연스러운지, GOLD(독자)는 이 스킬의 결과물을 실제 장면에서 그대로 쓸 수 있는지 봐줘. 지적사항을 반영해서 10점 수준까지 다시 만들어줘.
실행해 보고 고치기, 그리고 설치
문서가 좋아 보이는 것과 결과물이 좋은 것은 다릅니다. 실제로 실행해서 확인합니다.
이 스킬로 지난주 팀 회의록을 정리해서 HTML 페이지로 만들어줘. 그리고 스킬을 쓰지 않았을 때의 결과도 따로 만들어서 둘을 나란히 비교해줘.
skill-creator는 같은 요청을 스킬을 쓴 쪽과 쓰지 않은 쪽 양쪽으로 실행해 결과를 비교해 줍니다. 브라우저에 비교 화면이 열리고, 결과물을 하나씩 넘겨 보며 마음에 들지 않는 곳에 코멘트를 남길 수 있습니다. 스킬을 쓴 쪽이 눈에 띄게 낫지 않다면, 그 스킬은 아직 제 역할을 못 하고 있습니다.
내가 남긴 코멘트를 반영해서 스킬을 고쳐줘. 그리고 같은 테스트를 다시 돌려줘.
이 두 프롬프트를 두세 번 오가면 대개 쓸 만해집니다. 여기까지가 3단계와 4단계의 반복입니다.
아래 문장 하나로 어느 프로젝트에서든 부를 수 있는 자리에 설치합니다.
이 스킬을 홈 디렉터리의 ~/.claude/skills/ 에 설치해서 어느 프로젝트에서든 쓸 수 있게 해줘.
설치한 뒤에는 새 세션을 열고 트리거 문장을 그대로 입력해 확인합니다. 스킬을 지목하지 않았는데도 호출되면 성공입니다. 호출되지 않으면 description을 더 강하게 고칩니다.
GitHub에 공개하기
다른 사람과 나눌 목적일 때만 합니다. github.com에서 New repository를 눌러 빈 저장소를 하나 만들고, 만들어진 주소를 복사합니다. 안에 넣을 파일은 Claude가 만듭니다.
이 스킬을 저장소 주소에 업로드해줘. README와 MIT 라이선스도 함께 만들어줘. README에는 이 스킬이 어떤 업무를 대신하는지, 어떤 말을 하면 호출되는지, 어떻게 설치하는지, 결과물이 어떻게 생겼는지를 넣어줘.
저장소에 반드시 들어가는 두 파일입니다. 둘 다 Claude가 작성하지만, 무엇인지 알아야 나온 내용을 검토할 수 있습니다.
스킬이 뜻대로 작동하지 않을 때
자주 마주치는 증상 다섯 가지와, 각각 손봐야 할 구성 요소
스킬은 처음부터 뜻대로 작동하는 경우가 드뭅니다. 다만 증상마다 고칠 구성 요소가 정해져 있어서, 어디를 손볼지 알면 대부분 금방 해결됩니다.
Claude는 스킬을 써야 할 상황에서도 쓰지 않고 넘어가는 경우가 많습니다. description에 적은 조건이 느슨하면 이 요청에 쓸 스킬이라고 판단하지 않습니다.
사용자가 실제로 입력할 문장을 그대로 description에 넣고, 호출 조건을 단정적으로 적습니다. "회의록, 미팅 노트, 녹취록이라는 말이 나오면 반드시 이 스킬을 쓴다"처럼 씁니다.
무엇이 잘된 결과인지 적혀 있지 않으면 Claude가 자기 결과물을 점검하지 못합니다. 매번 그때의 판단만으로 작업을 끝냅니다.
채점 항목 서너 개와 합격선을 숫자로 적습니다. "평균 9.5점 미만이면 다시 쓴다"가 있으면 기준에 못 미칠 때 스스로 고쳐 씁니다.
호출 조건만 적고 적용하지 않을 경우를 적지 않으면, 조금이라도 비슷한 요청에서 모두 호출됩니다.
제외할 입력을 직접 적습니다. "산문, 일기, 메모에는 이 스킬을 적용하지 않는다"처럼 적용하지 않을 대상을 명시합니다.
SKILL.md 본문이 길어지면 뒤쪽에 적은 지시일수록 지켜지지 않습니다. Anthropic은 본문을 500줄 안쪽으로 유지하라고 권합니다.
자주 쓰지 않는 절차와 예시를 references/ 폴더로 옮기고, 본문에는 그 파일을 언제 읽을지만 남깁니다. 본문이 짧아야 남은 지시가 끝까지 지켜집니다.
스킬을 쓴 결과만 확인하기 때문입니다. 비교 대상이 없으면 나아졌는지 판단할 근거가 생기지 않습니다.
같은 요청을 스킬 없이 한 번 더 실행해 두 결과를 나란히 놓습니다. 차이가 분명하지 않으면 그 스킬은 아직 제 역할을 하지 못합니다.
Anthropic 스킬 설계 원칙 4가지
이 페이지의 6가지 구성 요소는 Anthropic 엔지니어링 블로그가 제시한 스킬 설계 원칙 4가지를 입문자가 SKILL.md에 바로 적용할 수 있도록 풀어 쓴 것입니다
점진적 정보 공개 · Progressive disclosure
메타데이터 → SKILL.md 본문 → 추가 링크 파일 순으로 Claude가 필요한 만큼만 정보를 단계적으로 불러오게 합니다. 컨텍스트 토큰을 아끼면서도 필요한 맥락은 모두 닿도록 구조화하는 핵심 원리입니다.
확장 가능한 구조 · Structure for scale
SKILL.md 본문이 비대해지면 절차·형식·예시를 별도 파일로 분리합니다. 자주 쓰지 않는 맥락을 따로 두면, 핵심 본문은 가볍게 유지되고 스킬은 무한히 커질 수 있습니다.
Claude 관점에서 생각 · Think from Claude's perspective
이름과 description이 호출 결정을 좌우합니다. 실제 사용 패턴을 관찰하면서 Claude가 호출을 망설이는 지점, 페르소나가 흔들리는 지점을 찾아 다듬습니다.
Claude와 반복 개선 · Iterate with Claude
성공한 워크플로와 자주 일어나는 실패 모드를 함께 정리해 스킬에 다시 반영합니다. 가정이 아니라 실제 동작을 근거로 다듬어야 스킬이 안정됩니다.
description은 첫 번째 layer이자 호출 판단의 근거
페르소나 정의가 흔들릴 때 Claude가 어디서 헷갈리는지 관찰
합격선을 숫자로 두면 결과를 근거로 스스로 다시 쓴다
긴 절차는 별도 파일로 빼서 본문을 가볍게 유지
출력 템플릿이 길어지면 reference 파일로 분리
실제로 마주친 실패 모드를 "하지 말 것"으로 캡처
Anthropic Engineering, Equipping agents for the real-world with Agent Skills
https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
스킬을 만들었다면, 플러그인으로 묶어보세요
스킬 하나는 한 가지 일을 합니다. 자주 쓰는 스킬과 MCP를 한 플러그인으로 묶으면, 팀 전체가 같은 도구를 한 번에 설치해서 씁니다.