업무 절차를 스킬로 만들기

반복하는 업무 절차 하나를 Claude Code의 스킬로 만들고, 시험하고, 평가하고, 팀과 나누는 순서다. 원본 공식 문서의 예시와 단계를 따른다.

준비물(필요한 것)#

한눈에 보기#

0. 후보 고르기#

다음 중 하나면 스킬 후보다.

• 같은 지시, 체크리스트, 여러 단계 절차를 채팅에 계속 붙여 넣고 있다. Claude Code 스킬
• CLAUDE.md(용어 사전)의 한 절이 사실이 아니라 절차로 자랐다. Claude Code 스킬
• 같은 플레이북을 세 번째로 붙여 넣고 있다, 또는 같은 프롬프트를 계속 쳐서 작업을 시작한다. Claude Code 확장 기능 개요

그 절차가 참고형(관례·스타일 가이드·도메인 지식처럼 Claude가 작업에 적용할 지식)인지 실행형(배포·커밋처럼 특정 일을 하는 단계별 지시)인지 정한다. 실행형은 대개 직접 부르는 쪽이 낫다. Claude Code 스킬

1. 위치 정하기#

근거: Claude Code 스킬. 전체 위치 표는 스킬.

mkdir -p ~/.claude/skills/summarize-changes

2. SKILL.md 쓰기#

SKILL.md는 두 부분이다. --- 사이의 YAML frontmatter(파일 맨 앞 머리말. 언제 쓸지를 적는다), 그 아래 마크다운 본문(스킬이 돌 때 따를 지시). 디렉터리 이름(또는 name)이 /명령 이름이 되고, description이 자동 로드 판단 근거가 된다. Claude Code 스킬

원본 첫 예시 — 커밋하지 않은 변경을 요약하고 위험을 짚는 스킬:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

!`git diff HEAD` 줄은 동적 컨텍스트 주입이다. Claude가 스킬을 보기 전에 Claude Code가 명령을 실행해 출력으로 바꾼다. 그래서 Claude가 열린 파일로 짐작하지 않고 실제 작업 트리에 근거해 답한다. Claude Code 스킬

쓰는 요령 (원본 권고): Claude Code 스킬

• description에 무엇을 하는지와 언제 쓰는지를 쓰고, 사용자가 자연스럽게 말할 키워드를 넣는다. 핵심 용도를 앞에 둔다. description+when_to_use는 목록에서 1,536자에서 잘린다.
• 본문은 짧게. 불러온 스킬은 대화에 계속 남아 매 턴 비용이 된다. 어떻게·왜를 늘어놓지 말고 무엇을 할지 쓴다.
• 작업 내내 적용할 지침은 상시 지시로 쓴다. "테스트를 돌려라"보다 "편집할 때마다 테스트를 돌려라". Claude Code는 이후 턴에 파일을 다시 읽지 않는다.
• 가장 중요한 지시는 위쪽에. 컴팩션 뒤에는 스킬 앞부분(스킬당 5,000토큰)만 남을 수 있다.
• SKILL.md는 500줄 이하로 두고 세부 자료는 보조 파일로 뺀다.
• frontmatter의 여는 ---는 파일 첫 줄이어야 한다. 아니면 파일 전체가 본문으로 취급된다. 필드 이름은 표와 정확히 같아야 한다(모르는 필드는 오류 없이 무시된다).

보조 파일:

my-skill/
├── SKILL.md      (필수 - 개요와 길잡이)
├── reference.md  (자세한 문서 - 필요할 때 로드)
├── examples.md   (사용 예 - 필요할 때 로드)
└── scripts/
    └── helper.py (실행만 하고 로드하지 않음)

SKILL.md에 "자세한 API는 reference.md" 식으로 각 파일이 무엇이고 언제 볼지 적는다. Claude Code 스킬

인자 받기: /fix-issue 123의 123이 $ARGUMENTS에 들어간다. 위치별로는 $0, $1(또는 $ARGUMENTS[0]). 여러 단어는 따옴표로 묶는다. Claude Code 스킬

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit

번들 스크립트를 권한 확인 없이 돌리기: 본문과 allowed-tools에 같은 ${CLAUDE_SKILL_DIR}를 쓴다. Claude Code 스킬

---
name: render-chart
description: Render a chart from a CSV file
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *)
---

Run `${CLAUDE_SKILL_DIR}/scripts/render.sh <csv-file>` to render the chart.

자주 쓰는 frontmatter (2026-10-18 기준)#

근거: Claude Code 스킬 (원본 Frontmatter reference에서 고른 것. metadata, license, compatibility는 Claude Code가 받기만 하고 쓰지 않는다)

3. 누가 부를지 정하기#

근거: Claude Code 스킬

배포 스킬 예:

---
name: deploy
description: Deploy the application to production
context: fork
disable-model-invocation: true
---

Deploy the application:
1. Run the test suite
2. Build the application
3. Push to the deployment target

context: fork는 스킬을 대화 기록 없는 서브에이전트에서 돌린다. 스킬 지시만으로 일이 끝나야 하고, 할 일 없이 지침만 있는 스킬에는 맞지 않는다. Claude Code 스킬 → 서브에이전트

4. 두 방법으로 시험하기#

git 프로젝트에서 파일 하나를 조금 고치고 claude로 시작한다. Claude Code 스킬

• 자동 호출: 설명과 맞는 말을 한다. What did I change?
• 직접 호출: /summarize-changes

어느 쪽이든 짧은 변경 요약과 위험 목록이 나오면 된다. 세션 중에 SKILL.md를 고치면 재시작 없이 반영된다(세션 시작 때 없던 최상위 스킬 디렉터리는 /reload-skills). Claude Code 스킬

5. 켠 채와 끈 채로 비교 평가하기#

트리거되는 걸 봤다고 의도대로 일한 건 아니다. 부를 프롬프트에서 부르는지, 불렀을 때 결과가 맞는지를 따로 잰다. Claude Code 스킬

1. 현실적인 프롬프트를 몇 개 모은다.
2. 각 프롬프트를 새 세션에서 스킬을 켠 채로 한 번, 끈 채로 한 번 돌린다. 새 세션이어야 스킬을 쓰던 대화의 잔여 맥락이 지시의 빈틈을 가리지 않는다.
3. 끄는 방법: 개인·프로젝트 스킬은 skillOverrides에서 "off", 플러그인 스킬은 claude plugin eval(플러그인 없이 다시 돌림).
4. 결과를 비교하고 description이나 본문을 고쳐 2단계로 돌아간다.

근거: Claude Code 스킬

자동화 도구: Claude Code 스킬

• 플러그인에 든 스킬: claude plugin eval이 프롬프트마다 플러그인 있이·없이 격리 세션에서 돌리고, 정한 채점 기준으로 점수를 매겨 기준 아래면 0이 아닌 코드로 끝나 CI 관문으로 쓸 수 있다.
• 단일 스킬을 대화 안에서 다듬기: skill-creator 플러그인. /plugin install skill-creator@claude-plugins-official로 설치한 뒤 "evaluate my summarize-changes skill with skill-creator"처럼 요청한다. 테스트 케이스(evals/evals.json), 케이스마다 서브에이전트로 격리 실행, 채점(grading.json), 스킬 있음·없음의 통과율·시간·토큰 비교(benchmark.json), 두 버전 블라인드 A/B, 트리거돼야 할·안 돼야 할 프롬프트로 설명 다듬기, HTML 리뷰 화면을 제공한다. 두 도구의 평가 파일 형식은 서로 호환되지 않는다.

6. 공유하기#

• 팀: .claude/skills/를 커밋한다. 이름이 겹치면 Enterprise > Personal > Project 순으로 이긴다. Claude Code 스킬
• 여러 저장소: 플러그인의 skills/ 디렉터리. 스킬 폴더에 .claude-plugin/plugin.json을 더하면 그 폴더가 플러그인으로 로드돼 에이전트·훅·MCP 서버도 묶을 수 있다. Claude Code 스킬
• 조직: managed settings로 배포. Claude Code 스킬
• 직무 단위: Anthropic의 Knowledge Work Plugins는 직무별 스킬·명령·커넥터를 플러그인으로 묶어 공개한다. 이 플러그인을 설치한 뒤 스킬 파일에 회사 용어·조직 구조·프로세스를 넣는 것은 원본이 드는 맞춤화 방법 중 하나다. Knowledge Work Plugins 저장소 → 업무 플러그인 설치·맞춤화
• claude.ai·Skills API로 올릴 때는 frontmatter를 name, description, license, compatibility, metadata, allowed-tools 여섯 개로 제한한다. 다른 필드가 있으면 업로드가 실패한다. 동적 컨텍스트 주입 같은 Claude Code 전용 본문 기능은 claude.ai 채팅이나 API에서 동작하지 않는다. Claude Code 스킬

공유 저장소의 스킬을 쓰는 쪽이라면 실행 전에 allowed-tools를 검토한다. 이 필드는 작업 공간 신뢰(workspace trust)와 상관없이 적용돼, 스킬이 스스로에게 넓은 도구 권한을 줄 수 있다. Claude Code 스킬 → 권한 모드

됐는지 확인하는 법#

• 불리는지: 4절의 두 방법으로 본다. 설명과 맞는 말(What did I change?)로 자동 호출되고, /summarize-changes로 직접 호출돼 짧은 변경 요약과 위험 목록이 나오면 된다. Claude Code 스킬
• 목록에 올라왔는지: What skills are available?로 물어 스킬이 나오는지 본다. 안 나오거나 /이름이 인식되지 않으면 스킬 문제 해결의 1·5절로 간다. Claude Code 스킬
• 의도대로 일하는지: 트리거됐다고 의도대로 일한 것은 아니다. 5절처럼 새 세션에서 스킬을 켠 채·끈 채로 같은 프롬프트를 돌려 결과를 비교한다. 플러그인 스킬이면 claude plugin eval이 기준 점수 아래일 때 0이 아닌 코드로 끝난다. Claude Code 스킬

언제 쓰고 언제 쓰지 않는가#

• 쓴다: 같은 절차를 반복해 붙여 넣을 때, CLAUDE.md의 절차형 내용을 덜어낼 때, 긴 참고 자료를 필요할 때만 싣고 싶을 때, 스크립트로 일을 하고 Claude는 조율만 하게 하고 싶을 때(원본 예: 코드베이스를 HTML 트리로 시각화). Claude Code 스킬
• 쓰지 않는다:
  • 매번 반드시 지켜져야 하는 규칙. 스킬은 Claude가 해석하는 지시라 건너뛸 수 있다. 훅으로 강제하거나 스킬의 hooks frontmatter에 둔다. Claude Code 스킬
  • 모든 세션에서 항상 알아야 하는 짧은 사실. 메모리(CLAUDE.md)가 맞다. Claude Code 확장 기능 개요
  • 작업이 지금까지의 대화 기록에 의존하는데 격리해서 돌리고 싶을 때 context: fork. 이 스킬은 대화 기록을 보지 못하므로, 원본은 이때 대화 자체를 포크하라고 한다. Claude Code 스킬
• 스킬을 늘리면 목록 비용이 매 턴 쌓인다. 쓰지 않는 스킬은 /skill-doctor로 찾아 끈다. Claude Code 스킬 → 컨텍스트 비용

막힐 때: 스킬 문제 해결

관련#

• 개념: 스킬
• 기능 선택: Claude Code 확장 기능 고르기
• 셋업 순서: Claude Code 셋업 점진적으로 키우기