스킬 — 일 잘하는 법을 저장하는 업무 지침서

스킬은 한 번 갈고닦은 일하는 방식을 저장해 두는 업무 지침서 파일입니다. 오늘 잘 해낸 일의 순서와 기준을 적어 두면, 다음부터는 처음부터 헤매지 않고 그 수준에서 시작합니다. 잘된 방식을 저장해 회사의 기본기로 삼는 일이며, 그 경영 원리는 책 11장 “세계 최고의 방식”이 다룹니다. 같은 요령을 매번 처음부터 다시 일러 주게 되는 것도 AI가 세션마다 기억을 잃는 탓입니다. 이 약점이 왜 생기는지는 「AI는 왜 어제 일을 잊을까요」 페이지에서 설명합니다.

스킬이란 — 지침서 한 장, 쓰는 방법은 둘

실체는 단순합니다. “이럴 때 이렇게 하라”를 적어 둔 SKILL.md라는 지침서 파일 하나입니다. 쓰는 방법은 두 가지입니다. 하나는 명령어처럼 /스킬이름을 입력해 내가 직접 부르는 방법입니다. “이번 주 회의록을 /weekly-report 형식으로 정리해 줘”처럼 지시 문장 중간에 섞어 써도 클로드는 그것이 스킬 이름인 줄 압니다. 다른 하나는 맞는 일이 들어왔을 때 클로드가 알아서 꺼내 쓰는 방법입니다. 잘 만든 스킬일수록 부르지 않아도 제때 나옵니다.

중요한 장점이 하나 있습니다. 스킬의 본문은 실제로 쓸 때만 읽힙니다. 두꺼운 설명서를 책장에 꽂아 두고 필요한 장만 펴 보는 것과 같아서, 긴 참고 자료를 담아 두어도 평소 기억 그릇(클로드가 한 번에 기억할 수 있는 양)을 거의 차지하지 않습니다.

이름이 바뀐 일이 두 번 있습니다. 먼저 옛 자료에서 “커스텀 명령어”(.claude/commands/)라 부르던 것이 지금은 스킬로 합쳐졌습니다. 옛 방식으로 만든 파일도 그대로 작동하고, 스킬은 거기에 보조 파일과 저절로 켜지는 기능 등을 더한 것입니다. 또 “슬래시 명령어”가 “명령어”로 바뀌었습니다. 이쪽은 기능이 합쳐진 것이 아니라 제품 문구에서 “슬래시”라는 단어만 뺀 이름 변경입니다.

기본으로 들어 있는 스킬

설치하지 않아도 처음부터 들어 있어 모든 세션에서 바로 쓰는 스킬이 있습니다. 대표적인 것은 다음과 같습니다.

기본 스킬도 다른 스킬과 똑같이 / 뒤에 이름을 입력해 부릅니다. 무언가 이상할 때는 /doctor를, 코드가 바뀐 뒤에는 /code-review를 한 번씩 쓰십시오. 이 둘만 알아 두어도 충분히 쓸모가 있습니다.

지금 쓸 수 있는 스킬을 전부 보려면 /skills를 칩니다. 작업 도중에 스킬 파일을 새로 만들거나 고쳤다면 /reload-skills를 입력해 그 자리에서 다시 읽게 합니다.

검사를 빠뜨리지 않게 하는 방법이 하나 있습니다. 프로젝트나 개인 스킬 폴더에 이름이 verify나 simplify인 스킬을 두면, 커밋(바뀐 내용을 한 묶음으로 저장하는 일)할 때마다 그 직전에 스킬을 먼저 실행하라는 지시가 클로드에게 들어갑니다. 훅처럼 기계가 반드시 실행하는 장치는 아닙니다. 문서나 테스트만 바꾼 커밋은 건너뜁니다. 기본으로 들어 있는 /verify, 플러그인이나 claude.ai 계정에서 온 스킬, “나만 실행”으로 잠근 스킬은 이 지시의 대상이 아닙니다. 반면 /verify를 직접 부르면 클로드가 앱 실행 방법을 프로젝트 스킬(.claude/skills/verify/)로 적어 둡니다. 이 프로젝트 스킬은 그 지시의 대상이므로, 다음 세션부터 커밋 직전마다 실행됩니다.

어디에 둘까요 — 네 곳과 우선순위

스킬 하나가 폴더 하나이고, 그 안에 설명 문서와 필요한 자료가 함께 들어갑니다. 어느 폴더에 두느냐에 따라 누가 쓸 수 있는지가 정해집니다.

같은 이름의 스킬이 여러 곳에 있으면 정해진 우선순위를 따릅니다. 조직 설정이 개인을 이기고, 개인이 프로젝트를 이깁니다. 이 순서는 스킬에만 해당합니다. 워크플로(정해진 순서로 도는 자동 라인)는 반대로 프로젝트 쪽이 먼저입니다. 그리고 내가 만든 스킬은 같은 이름의 기본 제공 스킬보다 앞섭니다. 프로젝트 폴더에 code-review 스킬을 두면 기본 /code-review 대신 그것이 실행됩니다. 우리 회사 일하는 방식대로 코드 검토를 시키고 싶을 때 쓰는 방법입니다.

스킬은 하위 폴더에도 둘 수 있습니다. 프로젝트 안 어느 하위 폴더에든 자기 .claude/skills/를 두면, 그 스킬은 그 영역을 다룰 때만 불려 옵니다. 다른 일을 하는 동안에는 그릇을 차지하지 않습니다. 우리 회사도 사업부 작업 폴더마다 프로젝트 스킬을 따로 두어, 출판 일의 스킬이 다른 부서 일에 끼어들지 않게 합니다.

claude.ai 계정에서 켜 둔 스킬도 같은 계정으로 로그인한 터미널 클로드 코드에 저절로 내려옵니다. 내 컴퓨터의 ~/.claude/skills/synced/에 받아 둡니다. 그 뒤로는 일하는 동안 약 10분, 쉬는 동안 약 40분마다 claude.ai에서 바뀐 것이 있는지 확인하고, 다시 시작하지 않아도 그 자리에서 반영합니다. /skills에서는 claude.ai sync 아래에 따로 모여 보입니다. 이 폴더의 파일은 내 컴퓨터에서 고쳐도 계정에 저장되지 않고, 다음에 받아 올 때 덮어써질 수 있습니다. 클로드가 이 폴더 파일을 고칠 때도 그렇게 알려 주니, 계정 스킬은 claude.ai에서 고치십시오. 받아 오지 않게 하려면 내 설정 파일(~/.claude/settings.json)에 "syncClaudeAiSkills": false를 넣습니다.

저절로 켜지는 원리 — 서랍 겉 라벨

클로드 코드는 세션을 시작할 때 쓸 수 있는 스킬들의 이름과 설명(description)만 먼저 훑어 둡니다. 서랍마다 겉에 붙은 라벨만 읽어 두는 셈입니다. 그러다 대화 내용이 어떤 스킬의 설명과 맞아떨어지면, 그때 비로소 서랍을 열어 본문 전체를 읽습니다.

• 설명(짧은 한 줄) — 세션을 시작할 때마다 읽혀서 클로드가 “이런 스킬이 있구나”를 압니다.
• 본문(긴 지시) — 실제로 쓸 때만 읽힙니다.

그래서 스킬이 저절로 켜지게 하는 열쇠는 설명 한 줄입니다. 설명에는 “무엇을 하는지”와 “언제 쓰는지”를 함께 담되, 내가 실제로 말할 법한 표현(“뭐가 바뀌었지”, “커밋 메시지 만들어 줘”)을 앞쪽에 둡니다. 그래야 클로드가 제때 찾아냅니다.

스킬이 쌓이면 /skill-doctor를 쳐 봅니다. 목록에 오른 스킬은 쓰지 않아도 설명 한 줄만큼 매번 그릇을 차지합니다. 이 명령은 스킬마다 그릇을 얼마나 차지하는지와 얼마나 자주 쓰였는지 보여 주고, 한 번도 쓰이지 않은 스킬과 그 스킬을 끄는 곳을 짚어 줍니다. 그릇을 많이 차지하는 것부터 끄면 됩니다.

SKILL.md 구조 — 설정 칸과 본문

직접 쓸 일은 드뭅니다. 만들기는 아래에서 보듯 말로 시키면 됩니다. 다만 클로드가 만들어 온 것을 확인하려면 구조는 알아야 합니다. SKILL.md는 두 부분으로 되어 있습니다. 맨 위 --- 두 줄 사이에 들어가는 설정 칸(frontmatter)과, 클로드가 따를 지시를 보통 문장으로 적는 본문입니다. 언제 쓰는지 알리는 설명은 설정 칸에 적습니다. 그리고 폴더 이름이 그대로 명령어가 됩니다. summarize-changes 폴더에 두면 /summarize-changes로 부릅니다.

my-skill/
├── SKILL.md      # 중심 지시 (필수)
├── reference.md  # 자세한 참고 문서 — 필요할 때만 읽음
├── examples.md   # 사용 예시 — 필요할 때만 읽음
└── scripts/
    └── helper.py # 클로드가 실행하는 스크립트 — 읽지 않고 실행만

보조 파일로 나누는 이유가 있습니다. 스킬이 한 번 켜지면 본문은 세션 내내 그릇에 남습니다. 그래서 SKILL.md 본문은 뼈대만 짧게(500줄 이하) 유지하고, 두꺼운 자료는 보조 파일로 빼서 정말 필요할 때만 읽히게 합니다. 대신 본문 안에 “자세한 사용법은 reference.md 참고”처럼 어떤 파일이 무엇을 담았는지 한 줄씩 안내해 둡니다.

만들기 — 말로 시킵니다

스킬을 만들려고 문법을 배울 필요는 없습니다. 방금 함께 끝낸 일이 마음에 들었다면, 그 자리에서 이렇게 말하면 됩니다.

# 클로드 코드 입력창에
우리가 방금 한 이 일을 스킬로 만들어 줘

공식 스킬 제작 도구(스킬 크리에이터)를 쓰면 초안을 만들어 주고, 시험 삼아 돌려 보며 고치는 과정까지 이끌어 줍니다. 우리가 할 일은 “이 일을 저장할 가치가 있다”고 판단하고, 나온 결과를 확인하는 것입니다.

만든 뒤에는 잘 만들어졌는지 확인합니다. 같은 요청을 각각 새 세션에서 스킬을 켠 채로 한 번, 끈 채로 한 번 돌려 결과를 비교합니다. 공식 마켓플레이스(플러그인을 골라 받는 목록)의 스킬 크리에이터가 이 비교를 자동으로 해 줍니다. 비교하는 것은 통과율과 걸린 시간, 쓴 토큰(AI가 글을 세는 단위)입니다.

누가 실행할 수 있을까요 — “나만 실행”으로 잠그기

기본으로는 나와 클로드 둘 다 스킬을 켤 수 있습니다. 그런데 배포·발행처럼 시점을 사람이 정해야 하는 일은 다릅니다. 코드가 완성돼 보인다고 클로드가 알아서 배포해 버리면 곤란합니다. 이럴 때는 설정 칸에 한 줄을 더해 나만 실행하게 잠급니다.

# 말로 시키기
배포 스킬은 나만 실행할 수 있게 잠가 줘
# 클로드가 SKILL.md 설정 칸에 더하는 한 줄
disable-model-invocation: true

반대 방향 잠금도 있습니다. user-invocable: false를 적으면 클로드만 쓰는 배경지식 스킬이 되어, /를 쳤을 때 나오는 목록에는 나타나지 않습니다.

값 넘기기 — 이름 뒤에 붙인 값이 스킬 안으로

값 넘기기도 한 줄만 알아 두면 됩니다. 값 넘기기란 명령어 뒤에 붙인 값을 스킬 안으로 전달하는 것입니다. 본문에 $ARGUMENTS라고 써 두면, /fix-issue 123처럼 이름 뒤에 붙인 값(123)이 그 자리에 채워집니다. 값을 여러 개 넘기고 싶으면 $0·$1처럼 순서대로 번호를 붙여 받습니다.

안 켜질 때·너무 자주 켜질 때

스킬이 뜻대로 움직이지 않으면 대부분 설명 한 줄을 손보면 해결됩니다. 기대한 순간에 안 켜지면 이 순서로 짚습니다.

1. 내가 실제로 쓰는 표현(키워드)이 설명에 들어 있는지 봅니다.
2. “사용 가능한 스킬이 뭐야?”라고 물어 목록에 그 스킬이 보이는지 확인합니다.
3. 요청 문장을 설명과 더 비슷하게 바꿔 말해 봅니다.
4. 그래도 안 되면 /스킬이름으로 직접 부릅니다.

반대로 원치 않는데 너무 자주 켜지면 설명을 더 구체적으로 좁힙니다. 내가 직접 부를 때만 쓰고 싶다면 위의 disable-model-invocation: true를 더하면 됩니다.

남의 스킬 찾기 — 스킬을 찾아 주는 스킬

웬만한 일에는 누군가 먼저 만들어 공개해 둔 스킬이 있습니다. 어려운 것은 그 많은 것 가운데 우리에게 맞는 하나를 고르는 일입니다. 이 일을 대신 해 주는 스킬이 따로 있습니다. 책이 인쇄소로 가던 무렵의 이름은 find-skills입니다(책 11장). 이름이 달라졌다면 클로드에게 “스킬을 찾아 주는 스킬”이 있는지 물으면 됩니다.

설치도 말로 시킵니다. 클로드 코드에 “find-skills 스킬을 찾아서 설치해 줘”라고 적으면, 공개 스킬 목록(skills.sh)에서 찾아 설치까지 진행합니다. 도중에 허락을 물으면 무엇을 설치하는지 보고 답하면 됩니다. 깔아 둔 뒤에는 “우리 회사에 필요한 스킬을 찾아 줘”라고 하면 우리 일에 맞는 후보를 골라 옵니다. 고를 때는 설치 수와 만든 곳을 함께 봅니다. 많이 쓰이고 이름난 곳에서 만든 것일수록 믿을 만합니다.

남의 스킬 — 열어 보고 씁니다

스킬은 결국 “클로드가 따를 지시”입니다. 출처를 모르는 스킬을 설치하면, 모르는 사람이 쓴 지시를 클로드가 그대로 따르게 됩니다.