스킬이 뭔가요?
Claude에게 "우리 회사는 이렇게 일해"를 미리 알려주는 업무 매뉴얼
매번 같은 형식, 같은 말투, 같은 구조를 반복 설명하고 계신가요?
스킬은 그 반복을 한 번에 해결합니다.
매번 같은 형식 · 말투를
다시 알려줄 필요 없음
누가 요청해도 동일한
형식의 결과물이 나옴
내가 만든 스킬을
팀원도 바로 활용
스킬 = "내가 원하는 결과물의 레시피"입니다.
한 번 만들어두면, 누구든 같은 품질의 결과물을 뽑아낼 수 있습니다.
→ 좋은 레시피에는 6가지 구성 요소가 있습니다.
잘 만든 스킬의 6가지 구성 요소
이 여섯 가지를 모두 갖춰야 Claude가 정확히 호출하고 일관된 수준으로 응답합니다
역할 (Role) · 누가 수행하는가?
호출되는 순간 Claude가 어떤 정체성 · 관점 · 어조로 응답할지 정의합니다. 기획자, 생성자, 평가자처럼 한 명일 수도, 여러 명일 수도 있습니다.
SKILL.md → ## 역할평가 기준 (Rubric) · 무엇이 합격 기준인가?
결과물이 쓸 만한지 판정하는 잣대를 미리 적어둡니다. 점수표와 합격선, 테스트, 리뷰 루프를 넣으면 기준에 못 미칠 때 스스로 고쳐 씁니다.
SKILL.md → ## 평가 기준맥락 (Context) · 무엇을 알아야 하는가?
언제 호출되는지, 무엇을 참고하는지 적습니다. 호출 조건(description), 프로젝트 지식, 대화 기록, 참고 문서가 여기에 들어갑니다. 맥락이 약하면 스킬이 있어도 호출되지 않습니다.
SKILL.md → description + ## 맥락 + references/도구 (Tools) · 어떤 도구 사용이 가능한가?
작업에 필요한 MCP, 다른 스킬, 플러그인, 파일 접근, 스크립트를 명시합니다. 어떤 도구를 언제 쓰는지 적어두면 손으로 하던 일을 Claude가 직접 처리합니다.
SKILL.md → ## 도구 + scripts/절차 (Workflow) · 어떤 순서로 일해야 하는가?
계획, 실행, 관찰, 수정, 반복의 순서를 단계별로 번호화하고, 결과물의 형식까지 고정합니다. 순서와 형식이 명시될수록 결과가 일관됩니다.
SKILL.md → ## 진행 규칙 + ## 출력 형식가드레일 (Guardrail) · 무엇을 하지 말아야 하는가?
권한, 보안, 승인이 필요한 지점, 금지 사항을 적습니다. 흔한 실패 모드와 스킬 범위 밖 요청을 미리 차단해 엉뚱한 결과를 막습니다.
SKILL.md → ## 하지 말 것스킬을 만들면 스킬 이름의 폴더가 하나 생깁니다. 그 안에 SKILL.md 한 개만 있어도 스킬은 작동합니다. 절차 · 예시 · 템플릿이 많아지면 아래처럼 폴더로 나눠 담습니다.
Claude는 먼저 description만 읽고, 스킬이 호출되면 SKILL.md 본문을 읽고,
필요할 때만 references/ · assets/를 꺼내봅니다.
자주 안 쓰는 내용을 바깥 파일로 빼두면 본문은 가볍게 유지되고, 스킬은 얼마든지 커질 수 있습니다.
→ 이 단계적 로딩 원리는 7번 참고에서 자세히 다룹니다.
AI 뉴스 클리핑 스킬 만들기
3개 역할로 구성된 팀이 최신 AI 뉴스를 수집 · 검증 · 선별해 출처 링크와 함께 5건으로 요약합니다
이번 주 AI 뉴스 정리해줘
- claude.ai 접속 후 좌측 하단 사용자 지정 클릭
- 스킬 탭 → 우측 상단 + 버튼 → 스킬 만들기
- 스킬 지침 작성 선택 후 아래 SKILL.md 전체를 그대로 붙여넣기
- 저장 → 새 채팅에서 웹 검색이 켜져 있는지 확인하고
/ai-news-clipping입력 후 요청 문장 전송
이번 주 AI 뉴스 정리해줘
Claude Code·Codex로 만드는 실전 5단계
업무 하나를 골라 스킬로 만들고, 검증하고, 팀에 공개하기까지
업무 하나를 골라 끝까지 만들어 봅니다. 5단계 내내 하는 일은 두 가지입니다. 준비된 프롬프트를 Claude Code나 Codex에 붙여넣는 것, 그리고 나온 결과를 보고 판단하는 것. 나머지는 AI가 합니다. 두 도구 모두 같은 SKILL.md 형식을 쓰므로 프롬프트도 그대로 통합니다.
스킬로 만들 업무 고르기
무엇을 스킬로 만들지 고르는 일이 절반입니다. 아래 5문항 중 3개 이상 해당하면 후보로 올려도 좋습니다.
이미 만들어진 스킬을 먼저 열어봅니다. 다른 사람의 업무가 스킬이 된 사례를 보면 내 업무의 후보도 찾기 쉬워집니다.
작업 폴더 만들고 Claude Code나 Codex로 열기
스킬 이름으로 폴더를 하나 만듭니다. 위치는 어디든 상관없습니다. 예: ~/Desktop/skills-dev/ai-news-clipping/
클로드 데스크톱 앱에서 Claude Code를 선택하고 방금 만든 폴더를 선택합니다. Codex를 쓴다면 Codex에서 같은 폴더를 엽니다.
아직 스킬 폴더(Claude Code는 .claude/skills/, Codex는 .agents/skills/)에 넣지 않습니다. 그 폴더에 넣는 순간 AI가 스킬로 인식해서 부르기 시작합니다. 반쯤 만든 스킬이 엉뚱한 자리에서 호출되면 결과가 어지러워집니다. 설치는 4단계에서 완성한 뒤에 합니다.
skill-creator로 초안 만들기
skill-creator는 스킬을 만드는 스킬입니다. Anthropic과 OpenAI가 각각 공식으로 제공하므로 Claude Code와 Codex에서 모두 쓸 수 있습니다. Codex에서는 $skill-creator로 부릅니다. 업무를 설명하면 SKILL.md 초안을 쓰고, 실행해서 비교하고, 고치는 일까지 돕기 때문에 SKILL.md를 처음부터 직접 쓰지 않아도 됩니다.
Claude Code나 Codex 대화창에 아래 문장을 붙여넣습니다.
skill-creator를 써서 AI 최신 뉴스를 찾아 요약하는 스킬을 만들어줘.
붙여넣으면 Claude가 바로 만들지 않고 먼저 네 가지를 되묻습니다. 이 스킬로 무엇을 할 수 있게 할지, 어떤 말이 나왔을 때 호출될지, 결과물은 어떤 형식일지, 테스트 케이스를 만들어 검증할지입니다. 꼼꼼히 답할수록 초안이 정확해집니다.
여기서 평가하는 대상은 결과물이 아니라 SKILL.md 문서 그 자체입니다. 지시가 빈틈없는지를 봅니다.
방금 만든 SKILL.md를 4가지 비평 역할로 10점 만점 평가해줘. RED(이성 비평가)는 지시에 논리적 빈틈이 없는지, SILVER(분야 전문가)는 뉴스 클리핑 현장의 디테일과 품질 기준이 반영됐는지, BLUE(공감 비평가)는 읽는 사람 입장에서 지시가 자연스러운지, GOLD(독자)는 이 스킬의 결과물을 실제 장면에서 그대로 쓸 수 있는지 봐줘. 지적사항을 반영해서 10점 수준까지 다시 만들어줘.
실행해 보고 고치기, 그리고 설치
문서가 좋아 보이는 것과 결과물이 좋은 것은 다릅니다. 실제로 실행해서 확인합니다.
이 스킬로 이번 주 AI 뉴스를 정리해서 HTML 페이지로 만들어줘. 그리고 스킬을 쓰지 않았을 때의 결과도 따로 만들어서 둘을 나란히 비교해줘.
같은 요청을 스킬을 쓴 쪽과 쓰지 않은 쪽 양쪽으로 실행해 결과를 비교합니다. Claude Code의 skill-creator는 브라우저에 비교 화면을 열어 주고, 결과물을 하나씩 넘겨 보며 마음에 들지 않는 곳에 코멘트를 남길 수 있습니다. Codex에서는 두 결과물을 나란히 열어 보고 고칠 점을 대화창에 적습니다. 스킬을 쓴 쪽이 눈에 띄게 낫지 않다면, 그 스킬은 아직 제 역할을 못 하고 있습니다.
내가 남긴 코멘트를 반영해서 스킬을 고쳐줘. 그리고 같은 테스트를 다시 돌려줘.
이 두 프롬프트를 두세 번 오가면 대개 쓸 만해집니다. 여기까지가 3단계와 4단계의 반복입니다.
아래 문장 하나로 어느 프로젝트에서든 부를 수 있는 자리에 설치합니다.
이 스킬을 홈 디렉터리의 스킬 폴더(Claude Code는 ~/.claude/skills/, Codex는 ~/.agents/skills/)에 설치해서 어느 프로젝트에서든 쓸 수 있게 해줘.
설치한 뒤에는 새 세션을 열고 트리거 문장을 그대로 입력해 확인합니다. 스킬을 지목하지 않았는데도 호출되면 성공입니다. 호출되지 않으면 description을 더 강하게 고칩니다.
GitHub에 공개하기
다른 사람과 나눌 목적일 때만 합니다. github.com에서 New repository를 눌러 빈 저장소를 하나 만들고, 만들어진 주소를 복사합니다. 안에 넣을 파일은 AI가 만듭니다.
이 스킬을 저장소 주소에 업로드해줘. README와 MIT 라이선스도 함께 만들어줘. README에는 이 스킬이 어떤 업무를 대신하는지, 어떤 말을 하면 호출되는지, 어떻게 설치하는지, 결과물이 어떻게 생겼는지를 넣어줘.
저장소에 반드시 들어가는 두 파일입니다. 둘 다 AI가 작성하지만, 무엇인지 알아야 나온 내용을 검토할 수 있습니다.
스킬이 뜻대로 작동하지 않을 때
자주 마주치는 증상 다섯 가지와, 각각 손봐야 할 구성 요소
스킬은 처음부터 뜻대로 작동하는 경우가 드뭅니다. 다만 증상마다 고칠 구성 요소가 정해져 있어서, 어디를 손볼지 알면 대부분 금방 해결됩니다.
Claude는 스킬을 써야 할 상황에서도 쓰지 않고 넘어가는 경우가 많습니다. description에 적은 조건이 느슨하면 이 요청에 쓸 스킬이라고 판단하지 않습니다.
사용자가 실제로 입력할 문장을 그대로 description에 넣고, 호출 조건을 단정적으로 적습니다. "AI 뉴스, AI 동향, 뉴스 클리핑이라는 말이 나오면 반드시 이 스킬을 쓴다"처럼 씁니다.
무엇이 잘된 결과인지 적혀 있지 않으면 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
성공한 워크플로와 자주 일어나는 실패 모드를 함께 정리해 스킬에 다시 반영합니다. 가정이 아니라 실제 동작을 근거로 다듬어야 스킬이 안정됩니다.
역할 정의가 흔들릴 때 Claude가 어디서 헷갈리는지 관찰
합격선을 숫자로 두면 결과를 근거로 스스로 다시 쓴다
description이 첫 번째 layer, 참고 문서는 필요할 때만 꺼내 읽는다
반복 작업은 scripts/로 빼서 코드가 직접 처리
긴 절차와 출력 템플릿은 별도 파일로 빼서 본문을 가볍게 유지
실제로 마주친 실패 모드를 "하지 말 것"으로 캡처
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
스킬을 만들었다면, 도구 지도를 펼쳐보세요
스킬은 AI에게 붙이는 다섯 가지 도구 중 하나입니다. 내장 도구, MCP, 커넥터, 플러그인과 어떻게 다르고 어떻게 함께 쓰는지 한 장으로 확인하세요.