클로드 코드 스킬 운영법: AI 매뉴얼을 업무 시스템으로 키우는 법

이 글은 4부작 중 4편입니다. 앞선 글에서 스킬을 만들고 개선하는 법을 봤다면, 이번 편에서는 그것을 팀에서 굴러가는 업무 시스템으로 키우는 법을 봅니다.

이 글에서 가져갈 것

1. 매번 말하기 귀찮은 설정은 따로 적어둡니다

어떤 스킬은 실행할 때마다 같은 질문을 반복하게 됩니다.

공식 원문에서는 standup-post라는 스킬을 예로 듭니다. 이름이 조금 낯설 수 있으니 먼저 상황부터 풀어보겠습니다.

회사에서 팀원들이 매일 짧게 업무 상황을 공유하는 경우가 있습니다. 보통 이런 내용을 적습니다.

- 어제 무엇을 했는지
- 오늘 무엇을 할 건지
- 막힌 문제는 무엇인지

이런 짧은 업무 진행 보고를 스탠드업(standup)이라고 부릅니다. 쉽게 말하면 매일 짧게 올리는 업무 공유 글입니다.

그리고 Slack은 회사에서 쓰는 단체 메신저입니다. 카카오톡 단체방처럼 팀별 채널이 있고, 그 채널에 업무 공유 글을 올린다고 생각하면 됩니다.

Slack = 회사용 메신저
Slack 채널 = 팀별 대화방
standup = 매일 짧게 쓰는 업무 진행 보고
standup-post 스킬 = 그 보고를 Slack 채널에 올려주는 스킬

이제 standup-post 스킬이 있다고 해보겠습니다. 이 스킬이 일을 하려면 최소한 두 가지를 알아야 합니다.

1. 어느 Slack 채널에 올릴지
2. 어떤 형식의 스탠드업 보고를 좋아하는지

처음 실행할 때 한 번만 물어보는 건 괜찮습니다. 하지만 이 스킬을 매일 쓴다면, Claude가 사용자에게 매번 같은 질문을 하게 됩니다.

Claude: 어느 Slack 채널에 올릴까요?
사용자: #team-daily-update 채널에 올려주세요.

여기서 #team-daily-update는 예시 Slack 채널 이름입니다. 실제 회사라면 #daily, #team-update, #marketing-team 같은 채널 이름이 될 수 있습니다.

처음에는 별일 아닌 것처럼 보입니다. 그런데 매일 같은 보고를 올린다고 생각하면 금방 불편해집니다.

사용자: 어제도 #team-daily-update라고 말했는데 또 알려줘야 하나?
사용자: 우리 팀은 항상 같은 채널에 올리는데, 이걸 기억해두면 안 되나?

문제는 스킬이 일을 못 한다는 게 아닙니다. 반복해서 같은 정보를 물어보는 것이 문제입니다.

그래서 공식 예시에서는 자주 반복되는 답변을 config.json 파일에 저장하는 흐름을 보여줍니다. 공식 원문에서 standup-post는 티켓 추적기, GitHub 활동, 이전 Slack 내용을 모아 어제와 달라진 내용만 스탠드업 보고로 정리하는 스킬 예시입니다.

공식 이미지의 SKILL.md 구조를 단순화하면 이런 모습입니다.

---
name: standup-post
description: Post your daily standup. Triggers on "standup", "daily".
---

# Standup Post

Read saved config first. If there is no config yet, ask which Slack channel to use.

그리고 설정 파일을 읽을 때는 스킬 폴더 위치를 가리키는 ${CLAUDE_SKILL_DIR}을 사용할 수 있습니다.

!`cat ${CLAUDE_SKILL_DIR}/config.json 2>/dev/null || echo "NOT_CONFIGURED"`

처음 보는 문법이라도 겁먹을 필요는 없습니다. 뜻은 단순합니다. “이 스킬 폴더 안의 config.json을 읽고, 없으면 아직 설정되지 않았다고 알려줘”라는 말입니다.

config.json = 스킬이 매번 다시 묻지 않도록 저장해두는 설정 파일

비개발자용으로 말하면, config.json은 스킬이 기억해두는 기본 설정 메모장입니다.

공식 이미지에는 이런 질문이 나옵니다.

- Which Slack channel?
- Paste a sample standup you liked

- 어느 Slack 채널에 올릴까요?
- 참고할 만한 스탠드업 보고 예시가 있으면 붙여주세요.

{
  "slack_channel": "#team-daily-update",
  "standup_style": "어제 한 일, 오늘 할 일, 막힌 문제를 짧게 정리"
}

더 구조화된 선택지가 필요하다면, 원문에서는 Claude에게 AskUserQuestion 도구를 사용하라고 지시할 수도 있다고 덧붙입니다. 예를 들어 Slack 채널을 고르게 할 때 자유 입력 대신 선택지를 보여주는 식입니다.

2. 지난 작업은 업무일지처럼 남길 수 있습니다

스킬을 계속 쓰다 보면 이런 생각이 듭니다.

지난번에 뭐가 잘됐더라?
어제 하던 일과 오늘 할 일의 차이가 뭐였지?

이걸 매번 사람 머릿속에만 두면 반복 개선이 어렵습니다.

공식 원문에서는 스킬이 append-only text log, JSON 파일, SQLite 같은 방식으로 데이터를 저장할 수 있다고 설명합니다.

공식 이미지에는 standup 로그 예시가 나옵니다.

2024-03-11
- shipped the cache invalidation fix
- started on the onboarding redesign

2024-03-12
- onboarding redesign: first two screens done
- reviewed Sarah's auth PR

2024-03-13
- onboarding redesign: blocked on copy review
- picked up the flaky-test ticket while waiting

콘텐츠 업무라면 이렇게 남길 수 있습니다.

# Run Log: 2026-06-05

## Task

Claude Code Skills 2편 v3 작성

## What worked

- 공식 이미지와 예시를 반영해 설득력이 올라감
- MDX 컴포넌트 후보가 섹션별로 잡힘

## What failed

- v2에서는 공식 이미지 활용이 부족했음
- scripts/libraries 설명이 너무 일반적이었음

## Update needed

- gotchas.md에 “공식 이미지/예시 누락 여부 확인” 추가
- publish-checklist.md에 “MDX 컴포넌트 후보 확인” 추가

공식 원문에서는 ${CLAUDE_PLUGIN_DATA} 환경 변수를 통해 스킬이나 플러그인이 안정적으로 데이터를 저장할 수 있는 위치를 사용할 수 있다고 설명합니다. 초보자는 “다음에도 AI가 읽을 수 있는 메모장을 따로 둘 수 있다” 정도로 이해하면 됩니다.

3. 반복 확인은 자동화 도구로 맡길 수 있습니다

사람이 매번 확인하기 귀찮은 일이 있습니다.

예를 들면:

• 링크가 깨졌는지 확인하기
• 메타 설명이 너무 긴지 확인하기
• 제목 후보가 3개 이상 있는지 확인하기
• 금지 표현이 들어갔는지 확인하기
• 이미지 파일이 빠졌는지 확인하기

이런 일은 매번 눈으로 보면 실수하기 쉽습니다.

공식 원문에서는 스킬 안에 scripts와 libraries를 넣을 수 있다고 설명합니다.

공식 이미지에는 lib/signups.py 같은 helper function 예시가 나옵니다.

함수 안에는 단순 코드가 아니라 실무 기준이 들어 있습니다.

- signup_started가 아니라 signup_completed를 본다.
- user_id는 signup 이후에 생긴다.
- (direct), 빈 문자열, None은 모두 organic으로 본다.
- /, /index, /home은 모두 homepage로 본다.
- UTM query params는 제거한다.

즉, libraries는 “코드 조각”이 아니라 반복되는 판단 기준을 함수 안에 넣어둔 것에 가깝습니다.

그리고 Claude는 이 helper function을 조합해서 즉석 분석 코드를 만들 수 있습니다.

lib/signups.py처럼 기준이 담긴 helper functions

from lib.signups import fetch, by_referrer, by_landing_page

mon, tue = fetch("2024-03-11"), fetch("2024-03-12")

print(by_referrer(tue) - by_referrer(mon))
print(by_landing_page(tue) - by_landing_page(mon))

# -> something broke on / on Tuesday

check_links(): 본문 링크가 열리는지 확인
check_source_quotes(): 원문 인용이 너무 길지 않은지 확인
check_meta_length(): 메타 설명 길이 확인
check_mdx_components(): Tabs/Accordion 후보가 빠지지 않았는지 확인

여기서 작지만 중요한 부분은 마지막 주석입니다.

# -> something broke on / on Tuesday

이 줄은 단순 장식이 아닙니다. Claude가 helper function으로 계산한 결과를 사람이 바로 이해할 수 있게 남긴 해석입니다. 그래서 스킬 안에 scripts나 libraries를 둘 때는 “코드만 실행하라”가 아니라, 결과를 해석하는 짧은 주석이나 요약도 남기게 하는 편이 좋습니다.

콘텐츠 업무로 바꾸면 이런 식입니다.

# -> 3번째 외부 링크가 404입니다.
# -> description이 168자로 schema 제한을 넘었습니다.
# -> 공식 원문 문장이 너무 길게 복사된 문단이 있습니다.

이런 주석은 다음 사람이 결과를 검토할 때 바로 도움이 됩니다.

공식 원문에서는 특히 검증용 스킬이 Claude 출력 품질에 내부적으로 측정 가능한 영향을 줬다고 말합니다.

초보자용으로 바꾸면 이렇게 말할 수 있습니다.

4. 중요한 순간에는 안전장치를 켤 수 있습니다

발행 직전에는 사람이든 AI든 실수하기 쉽습니다.

출처 링크를 빼먹을 수도 있고, 승인 전 파일을 수정할 수도 있고, 원문 문장을 너무 많이 가져올 수도 있습니다.

그래서 특정 순간에 자동으로 확인하는 안전장치를 둘 수 있습니다. Claude Code에서는 이런 장치를 hooks라고 부릅니다.

공식 원문에서는 on-demand hooks를 소개합니다. 항상 켜두는 규칙이 아니라, 특정 스킬이 호출됐을 때만 세션 동안 활성화되는 강한 자동 규칙에 가깝습니다.

원문 예시를 단순화해 쓰면 이런 식입니다.

/careful: rm -rf, DROP TABLE, force-push, kubectl delete 같은 위험한 명령을 막는 용도
/freeze: 특정 디렉터리 밖의 파일 수정을 막는 용도

콘텐츠 업무에서는 이렇게 바꿔볼 수 있습니다.

- 발행 전에 출처 링크가 있는지 확인한다.
- 원문 문장을 너무 많이 복사하지 않았는지 확인한다.
- 승인 없이 publish 폴더를 수정하지 못하게 막는다.
- 특정 폴더 밖의 파일을 수정하지 못하게 막는다.

즉 hooks는 단순 알림벨이라기보다, 위험한 행동 앞에 세우는 가드레일에 가깝습니다.

5. 팀에서 같이 쓰려면 먼저 공유하고 써봐야 합니다

스킬은 혼자만 쓸 수도 있지만, 팀에서 같이 쓰면 기준을 맞추기 쉬워집니다.

공식 원문에서는 스킬을 공유하는 방식을 크게 두 가지로 설명합니다.

첫 번째는 repo 안에 스킬을 넣는 방식입니다.

./.claude/skills

작은 팀이나 적은 프로젝트에서는 이 방식이 단순하고 좋습니다. 팀원이 같은 저장소에서 같은 스킬을 볼 수 있기 때문입니다.

다만 공식 원문은 여기서 중요한 단점도 같이 말합니다. repo에 체크인된 스킬은 모델의 context에 조금씩 부담을 더합니다. 작은 팀에서는 괜찮지만, repo가 많아지고 스킬이 많아지면 “모든 사람이 모든 스킬을 늘 들고 다니는” 문제가 생길 수 있습니다.

그래서 규모가 커지면 두 번째 방식인 plugin marketplace가 더 유리해질 수 있습니다.

쉽게 비유하면, 조직 안에서 필요한 스킬이나 플러그인을 올리고 설치할 수 있는 내부 앱스토어 같은 공간입니다. 다만 원문 표현은 Claude Code Plugin marketplace이며, 일반 소비자용 앱스토어를 뜻하는 것은 아닙니다.

marketplace 방식의 장점은 모든 스킬을 모든 repo에 넣지 않아도 된다는 점입니다. 팀원이 필요한 스킬만 골라 설치할 수 있고, 설치할 때 필요한 설정 흐름도 함께 둘 수 있습니다.

원문에서 소개한 Anthropic의 방식도 흥미롭습니다.

처음부터 중앙 팀이 모든 스킬을 정하는 게 아닙니다. 누군가 만든 스킬을 sandbox 폴더에 올리고, Slack 같은 곳에서 사람들에게 써보라고 공유합니다. 실제로 사람들이 쓰고 반응이 생기면, 그때 marketplace로 옮기는 PR을 낼 수 있습니다.

흐름은 이렇게 볼 수 있습니다.

좋은 스킬을 처음부터 회의실에서 완벽히 정하기보다, 먼저 써보고 실제로 도움이 되는지 보는 방식입니다.

공식 원문에서는 스킬 조합도 다룹니다. 예를 들어 file upload skill과 CSV generation skill을 함께 참조할 수 있습니다.

콘텐츠 업무라면 이런 식입니다.

blog-writing 스킬
→ source-check 스킬 참고
→ seo-check 스킬 참고
→ publish-package 스킬 참고

다만 필요한 스킬이 자동으로 설치되는 것은 아닙니다. 처음에는 “이 작업에서는 이 스킬도 함께 참고하라” 정도로 이해하면 충분합니다.

6. 좋은 스킬은 쓰면서 계속 고칩니다

좋은 스킬은 만든 뒤에 끝나지 않습니다.

실제로 얼마나 자주 쓰이는지, 어디서 잘 안 불리는지 보면서 고쳐야 합니다.

공식 원문에서는 PreToolUse hook으로 스킬 사용량을 기록한다고 설명합니다. 이 기록을 보면 어떤 스킬이 많이 쓰이는지, 기대보다 덜 호출되는 스킬이 있는지 알 수 있습니다.

여기서 말하는 측정은 거창한 성과 분석이 아닙니다.

핵심은 이 정도입니다.

이 스킬이 실제로 쓰이고 있나?
생각보다 덜 호출되는 스킬은 없나?
description이 애매해서 AI가 못 찾는 건 아닌가?
이름이 너무 추상적이지는 않은가?

예를 들어 blog-writing 스킬은 자주 쓰이는데 source-check 스킬은 거의 안 쓰인다고 해봅시다.

그럼 이렇게 점검할 수 있습니다.

• 스킬 이름이 너무 애매한가?
• description에 사용 상황이 제대로 들어갔나?
• blog-writing 작업 흐름에서 source-check를 참고하라고 안내했나?
• 실제로는 별도 스킬이 아니라 blog-writing 안의 references로 두는 게 나은가?

이런 점검을 통해 스킬은 조금씩 좋아집니다.

공식 원문에서도 좋은 스킬은 몇 줄과 하나의 gotcha에서 시작할 수 있다고 말합니다. 그리고 실제 사용 중 발견한 edge case를 계속 추가하면서 좋아집니다.

그러니 처음부터 완벽한 업무 시스템을 만들려고 하지 않아도 됩니다.

4부작을 정리하면

좋은 스킬은 한 번에 완성되는 문서가 아니라, 일을 할수록 더 정확해지는 운영 매뉴얼입니다.