Skills(스킬)로 나만의 일하는 방식 주입: 설계·구조·테스트·배포까지
스킬(Skills)은 간단히 말해 Claude에게 '내 작업 절차'를 한 번 가르쳐 두고, 다음부터는 자동으로 불러 쓰게 하는 기능입니다. 매번 같은 설명을 반복하던 일을, "한 번 설치한 규칙"으로 바꾸는 거죠.
앞서 'Cowork로 자동화하기: 스케줄 작업, 커넥터, 플러그인, 팀 워크플로'에서 플러그인 안에 스킬이 들어간다고만 짚고 넘어갔습니다. 이번 장에서는 그 "스킬 자체"를 설계하고, 만들고, 테스트하고, 배포하는 전 과정을 잡아봅니다.
스킬이 진짜로 필요한 순간
스킬은 "대충 잘 대답해 주는 AI"가 아니라, 매번 같은 품질과 같은 형식으로 결과를 내야 할 때 힘을 발휘합니다.
예를 들어 이런 경우입니다.
우리 팀 보고서는 항상 '이번 주 완료/리스크/다음 액션' 구조로 써야 한다
고객 메일은 특정 톤(과장 금지, 확정 표현 금지, 질문 2개로 끝내기)을 지켜야 한다
리서치는 "근거 수집 → 요약 → 검증" 순서를 반드시 지켜야 한다
이건 프롬프트로도 할 수 있지만, 사람이 매번 똑같이 잘 적어야 합니다. 스킬로 만들면 "잘 적는 사람"이 아니라 "구조가 시스템에 들어간 팀"이 됩니다.
스킬의 실체는 '폴더'다
중요한 포인트부터 말하면, 스킬은 문서 한 장이 아니라 폴더(디렉터리) 하나입니다. 최소 구성은 SKILL.md 한 파일이고, 필요하면 자료/템플릿/스크립트를 함께 묶습니다.1
가장 기본 구조는 이렇게 생각하면 됩니다.1
my-skill/
├── SKILL.md
├── scripts/ # 선택: 실행 코드(파이썬/노드/배시)
├── references/ # 선택: 긴 참고 문서
└── assets/ # 선택: 템플릿/이미지/데이터여기서 실수 1위는 "ZIP을 만들긴 했는데 Claude가 스킬로 못 알아보는" 상황인데, 이유는 대개 하나입니다. ZIP 최상단에 폴더가 있어야 합니다. SKILL.md를 ZIP 루트에 바로 넣으면 실패하기 쉽습니다.1
점진적 공개(Progressive disclosure): 토큰을 아끼면서 깊어지는 구조
스킬을 잘 설계한 사람들은 한 가지 감각을 공유합니다.
처음부터 모든 걸 다 넣지 않는다.
스킬에는 보통 세 층이 있습니다.
항상 로딩되는 얇은 층:
SKILL.md의 YAML 메타데이터(특히 description)필요할 때 로딩되는 본문:
SKILL.md의 지시문(절차/규칙/예시)요청할 때만 꺼내는 부록:
references/,assets/같은 외부 파일
이 방식을 보통 점진적 공개(Progressive disclosure)라고 부르겠습니다. 핵심은 "자주 쓰는 규칙은 얇게, 가끔 필요한 디테일은 분리"입니다. 이 감각이 없으면 스킬이 금방 비대해지고(=불러올 때마다 무거워짐), 정작 중요한 규칙이 묻힙니다.
설계: 좋은 스킬은 '범위'가 먼저다
스킬을 만들기 전에 아래 질문 5개를 먼저 적어 보세요. 이게 끝나면 절반은 완성입니다.
이 스킬이 해결하는 반복 업무는 정확히 무엇인가?
결과물이 "성공"인지 "실패"인지 한눈에 판단할 기준은 무엇인가?
이 스킬이 하면 안 되는 일은 무엇인가? (범위 밖)
입력으로 꼭 필요한 정보는 무엇이고, 없으면 무엇을 질문해야 하는가?
산출물은 어떤 형식이어야 하는가? (문서/표/JSON 등)
여기서 "하면 안 되는 일"을 적는 순간, 트리거가 과하게 잡히는 문제를 크게 줄일 수 있습니다. 스킬을 똑똑하게 만드는 건 '능력'이 아니라 경계선인 경우가 많습니다.
작성 규칙: SKILL.md는 '설명'이 아니라 '절차서'로 쓴다
공식 문서 기준으로 SKILL.md는 맨 위에 YAML frontmatter(메타데이터)가 필요하고, 그 아래는 마크다운으로 지시문을 씁니다.1
YAML에서 사실상 가장 중요한 건 description입니다. Claude가 "언제 이 스킬을 써야 하는지"를 판단하는 핵심 단서가 되기 때문입니다.1
YAML frontmatter: 최소는 name + description
필수 필드는 name, description 두 개입니다.1
name은 소문자/숫자/하이픈만 가능하고, 폴더 이름과 일치해야 합니다.1description은 "이 스킬이 언제 쓰이는지"를 문장으로 정확히 적어야 합니다.1
이 장의 요령은 단순합니다.
description은 기능 설명이 아니라 '검색 키워드'라고 생각하세요.
사람이 실제로 하는 말("주간보고", "회의록", "브랜드 가이드 적용", "CSV 분석")을 넣고, 동시에 경계도 적습니다. 예: "단순 요약만 필요하면 이 스킬을 쓰지 말 것."
본문: 절차, 예시, 예외를 순서대로
SKILL.md 본문에는 다음이 들어가면 좋습니다.1
단계별 절차(순서)
입력/출력 예시
템플릿(제목 구조, 섹션 구조)
자주 깨지는 예외 케이스(정보가 부족할 때, 범위 밖 요청일 때)
여기서 앞서 배운 걸 그대로 재활용할 수 있습니다.
결과 형식을 고정하는 건 '출력 제어 마스터: 길이·톤·형식(표/JSON/XML)·불확실성 처리 규칙'에서 다룬 제약 조건(Constraints), 스키마/템플릿(Output format) 방식이 가장 안정적입니다.
근거 기반으로 쓰게 만드는 건 '파일·PDF·대용량 문서 다루기…'의 Quote-first(근거 우선) 패턴을 그대로 가져오면 됩니다.
스킬은 결국 "좋은 프롬프트를 매번 복사해 붙이는 것"을 "제품화"하는 작업입니다.
리소스 확장: references/assets/scripts를 언제 쓰나
SKILL.md만으로도 충분한 스킬이 많습니다. 하지만 다음 상황에서는 분리 파일이 빛납니다.
참고 자료가 길고(브랜드 가이드, 사내 규정), 자주 바뀐다 →
references/템플릿/스키마/샘플 파일이 핵심이다 →
assets/'검증'처럼 반복되는 계산/체크를 확실히 하고 싶다 →
scripts/
공식 문서에서는 스킬에 파이썬/노드/배시 스크립트를 넣을 수 있고, 필요하면 의존성을 frontmatter에 선언할 수 있다고 안내합니다.1
예를 들어 데이터 분석 스킬이라면 파이썬 버전이나 라이브러리를 dependencies로 적는 식입니다.1
다만 스크립트는 강력한 만큼, 팀에서는 보안/권한 합의가 먼저여야 합니다. "외부 서비스 접근"은 다음 장인 'MCP/커넥터로 Claude에 '손발' 달기…'에서 더 안전하게 다루겠습니다.
Claude.ai에서 스킬 올리고 켜는 흐름
claude.ai에서 스킬을 쓰는 흐름은 크게 두 가지입니다.
첫째, 이미 제공되는 스킬을 켜서 쓰기입니다. Anthropic의 공식 예제 스킬들은 유료 플랜에서 claude.ai에 이미 제공된다고 안내합니다.2
둘째, 내 스킬을 업로드해서 쓰기입니다. 공식 문서 기준으로 업로드 전에는 폴더 이름과 name 일치, ZIP 구조를 점검하고, 업로드 후에는 설정에서 스킬을 활성화한 다음 트리거 테스트를 합니다.1
특히 "업로드 후" 단계에서 문서가 콕 찍어 말하는 동작은 이것입니다.
Settings > Capabilities에서 스킬을 활성화한다1
스킬이 걸려야 하는 프롬프트를 던져 보고(트리거 테스트), 필요하면 description을 고친다1
UI는 바뀔 수 있지만, 원리는 고정입니다. (1) 설치/활성화 → (2) 트리거 확인 → (3) description을 조정하며 반복입니다.
테스트: 스킬 품질은 "잘 작동"이 아니라 "일관되게 작동"이다
스킬 테스트는 감으로 하면 끝이 없습니다. 대신 테스트를 세 덩어리로 나누면 빠르게 수렴합니다.
트리거 테스트: 너무 안 걸리거나, 너무 자주 걸리거나
트리거 문제의 대부분은 description 때문입니다.1
너무 안 걸린다: description이 추상적이거나, 사람들이 실제로 쓰는 표현이 없다
너무 자주 걸린다: description 범위가 넓고, "쓰지 말아야 할 경우" 경계가 없다
트리거 테스트는 어렵게 할 필요가 없습니다. "걸려야 하는 문장 10개"와 "걸리면 안 되는 문장 10개"를 만들어서 직접 던져 보면 됩니다.
준수 테스트: 스킬이 로딩됐는데 지시를 무시한다면
이때는 대개 두 가지입니다.
하나는 지시가 길어져서 중요한 규칙이 묻힌 경우입니다. 공식 문서도 SKILL.md가 너무 길어지지 않게 하고(예: 500줄 아래 권장), 긴 내용은 별도 파일로 빼라고 합니다.1
다른 하나는 규칙이 '좋은 말'로만 적힌 경우입니다. 예를 들어 "적절히 검증해라"는 말은 실행으로 바뀌기 어렵습니다. 대신 검증 항목을 구체적으로 써야 합니다.
이 부분은 앞서 '출력 제어 마스터…'에서 다룬 "검증(Verification) / 자기점검(Self-check)"을 스킬 내부 절차로 넣으면 크게 개선됩니다.
품질 테스트: 샘플 입력으로 '채점'할 수 있어야 한다
스킬이 팀에 들어가면, 사람마다 "좋다/별로다"가 갈립니다. 그래서 스킬은 가능하면 샘플 입력과 기대 출력을 함께 두는 게 좋습니다.
입력 예시: 지난주 주간보고 원문(민감정보 제거)
기대 출력: 섹션 구조, 분량, 톤 기준
실패 기준: 과장/추측, 섹션 누락, 액션 아이템이 3개를 넘어감
이렇게 "채점 기준"을 만들어 두면, 스킬을 업데이트할 때도 흔들리지 않습니다.
배포/재사용: 개인용에서 팀 표준으로
스킬은 claude.ai, Claude Code, API에서 같은 개념으로 쓸 수 있도록 설계되어 있습니다.2
배포는 보통 3단계로 커집니다.
개인: ZIP으로 백업해 두고, 필요할 때 내 계정에 업로드
팀: Git 저장소로 관리(버전/리뷰/승인), 릴리스 ZIP을 배포
커뮤니티/조직: 플러그인/마켓플레이스 형태로 제공(Claude Code 쪽은 마켓플레이스를 추가하고 설치하는 흐름을 안내합니다.)2
팀에서 특히 중요한 운영 팁은 하나입니다.
스킬에도 버전이 필요합니다.
최소한 다음 3가지를 습관으로 두면, "어제까지 되던 게 오늘 안 되는" 사고가 줄어듭니다.
SKILL.md상단(본문)에 변경 이력(날짜/변경 요약)트리거 테스트 문장 세트(걸림/안 걸림)
샘플 입력 2~3개(대표 케이스)
실전 예시: '주간 리포트 스킬' 최소 형태
아래는 "바로 만들 수 있는 수준"의 뼈대 예시입니다. 그대로 복사해서 쓰기보다, 당신의 팀 템플릿에 맞게 바꾸는 걸 목표로 보세요.
폴더 구조:
weekly-update/
└── SKILL.mdSKILL.md 예시:
---
name: weekly-update
description: Write a weekly work update in our team format (Done / In progress / Risks / Next actions). Use for Friday weekly report drafting. Do NOT use for meeting minutes or long narrative summaries.
---
# Weekly Update Skill
## Goal
Draft a weekly update that is easy to review and easy to verify.
## Procedure
1) Ask for missing inputs first: reporting period, target audience, and source materials (links/files).
2) Create the report using the exact section structure below.
3) Apply uncertainty rules: if evidence is missing, say '추가 확인 필요' instead of guessing.
4) End with a short self-check: list any missing evidence or unclear items.
## Output format (fixed)
- 제목: [팀명] 주간 업데이트 (YYYY-WW)
- Done: 최대 7개, 항목당 2줄
- In progress: 최대 5개, 블로커가 있으면 1줄 추가
- Risks: 최대 5개, 영향/대응 1줄씩
- Next actions: 딱 3개만
## Examples
### Input example
- Done: ...
- In progress: ...
### Output example
(위 섹션 구조 그대로)이 스킬을 업로드/활성화한 뒤에는, "이번 주 주간보고 써줘" 같은 문장뿐 아니라 "금요일 주간 업데이트 초안 만들어줘"처럼 description에 넣은 표현을 섞어서 트리거가 잘 걸리는지 확인해 보세요.
마지막 정리: 스킬은 '크게 하나'보다 '작게 여러 개'가 낫다
스킬은 욕심내기 쉬운 기능입니다. 하지만 운영 관점에서는 반대가 정답인 경우가 많습니다.
하나의 거대한 스킬: 트리거도 애매해지고, 지시도 길어지고, 디버깅이 어려워집니다.
작고 선명한 스킬 여러 개: 서로 조합되며, 고장 난 부분만 부분 수정(좁혀서 수정)하기 쉽습니다.
스킬을 "내가 잘하는 방식"이 아니라, 내가 매번 반복하는 방식부터 시작해 보세요. 그게 가장 빨리, 가장 확실하게 효율을 올려줍니다.
참고
1Creating custom skills - Claude.ai Documentation
2GitHub - anthropics/skills: Public repository for Agent Skills
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.