Skills 셋업과 기본 조작

앞 글에서 하네스라는 울타리를 세웠다면, 이번에는 그 안에서 반복해서 쓰는 도구를 파일로 굳힙니다. 초급 8주 3주차에 만든 "녹음→회의록 변환기"를 예로 들어 Skill 하나를 폴더 생성부터 팀 배포까지 한 바퀴 돌립니다. 읽고 나면 매번 채팅에 붙여 넣던 지시문을 /회의록 한 단어로 줄일 수 있고, 다음 글 팀 도입 워크플로에서 이 스킬을 팀 공용 자산으로 올리는 순서가 보입니다.

핵심 요약

• Skill은 SKILL.md 하나가 들어 있는 폴더입니다. 폴더 이름이 곧 /명령어가 됩니다.
• 개인용은 ~/.claude/skills/, 팀용은 프로젝트 .claude/skills/에 두고 커밋합니다.
• 본문은 세션 동안 컨텍스트에 남으므로 짧게, 긴 참고 자료는 별도 파일로 뺍니다.
• 부작용 있는 작업은 disable-model-invocation: true로 사람만 호출하게 합니다.

1. 폴더 만들기

Skill이 사는 위치가 곧 적용 범위입니다. 공식 문서 기준으로 개인 ~/.claude/skills/<이름>/SKILL.md는 모든 프로젝트에, 프로젝트 .claude/skills/<이름>/SKILL.md는 그 저장소에만 적용됩니다. 같은 이름이 겹치면 개인이 프로젝트를 덮습니다. 옛 .claude/commands/*.md도 계속 동작하지만 지원 파일을 붙일 수 있는 skills 형식을 권장합니다.

# macOS
mkdir -p ~/.claude/skills/meeting-notes/scripts

Windows PowerShell은 New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\skills\meeting-notes\scripts"입니다. 폴더 이름은 영문 소문자로 짓습니다. 한글 폴더명은 팀 배포 때 터미널마다 달리 보입니다.

2. SKILL.md 작성

frontmatter의 description이 가장 중요합니다. Claude가 이 문장을 보고 자동 호출 여부를 판단하기 때문입니다. 본문은 "무엇을 할지"만 적고 이유 설명은 뺍니다. 5주차 황금 문장(원인 분석→최소 수정→변경 정리) 구조를 그대로 옮기면 됩니다.

---
name: meeting-notes
description: 녹음 전사 텍스트를 회의록으로 정리한다. 사용자가 회의록, 전사본 정리, 액션 아이템 추출을 요청할 때 사용.
argument-hint: "[전사 파일 경로]"
allowed-tools: Read
---

$ARGUMENTS 파일을 읽고 아래 순서로 회의록을 만든다.
1. 참석자·일시·안건 3줄 머리말
2. 안건별 결정 사항(결정 아닌 논의는 "논의"로 표시)
3. 액션 아이템 표: 담당·기한·내용
4. 원문에 없는 내용은 절대 추가하지 않는다. 불명확하면 "확인 필요 항목" 절에 모은다.

$ARGUMENTS는 명령 뒤에 적은 전체 인수, $0·$1은 위치별 인수입니다. allowed-tools에 적은 도구는 스킬이 켜진 동안 승인 없이 쓰입니다.

3. 동작 확인

새 세션에서 두 가지 방식으로 검증합니다. 직접 호출 /meeting-notes recordings/0827.txt와, 자연어 "이 전사본 회의록으로 정리해줘"로 자동 호출이 되는지입니다. 호출된 것과 의도대로 된 것은 다릅니다. 우리 정지 규칙대로 결과 화면이 증거입니다. 결정 사항 두 건만 원문과 대조해도 품질이 드러납니다. --debug로 실행하면 파싱 오류가 보입니다.

4. 개선하기

자동 호출이 안 되면 description에 사용자가 실제로 말하는 단어(회의록·전사본·액션 아이템)를 넣습니다. 너무 자주 끼어들면 설명을 좁히거나 disable-model-invocation: true를 붙입니다. 결과가 길어지면 본문에 "표 밖 서술 금지"처럼 검증 가능한 제약을 한 줄 추가합니다. SKILL.md는 500줄 이하, 참고 자료는 reference.md로 빼고 본문에서 링크합니다. 폴더 수정은 재시작 없이 반영됩니다.

5. 스크립트 붙이기

같은 계산을 매번 모델에게 시키면 느리고 결과가 흔들립니다. 전처리는 스크립트로 내립니다. 우리 변환기는 전사본에서 타임스탬프를 지우는 파이썬 한 줄을 scripts/clean.py에 두고 이렇게 부릅니다.

먼저 `python3 ${CLAUDE_SKILL_DIR}/scripts/clean.py $0`를 실행해 정제본을 얻은 뒤 작업한다.

${CLAUDE_SKILL_DIR}는 스킬 폴더 절대 경로로 치환되므로 개인·프로젝트·플러그인 어디에 설치돼도 같은 코드가 돕니다. 스크립트가 쓰는 도구는 allowed-tools: Bash(python3 *)처럼 미리 허용합니다. !`git diff HEAD` 구문을 쓰면 명령 출력을 본문에 미리 주입할 수도 있습니다.

6. 팀에 배포

프로젝트 .claude/skills/에 옮겨 커밋하면 저장소를 받는 모든 팀원에게 같은 /meeting-notes가 생깁니다. 프로젝트 스킬의 allowed-tools는 폴더 신뢰 대화를 수락한 뒤에만 적용되므로, 팀원은 남이 만든 스킬의 권한부터 읽고 신뢰합니다. 여러 저장소에 같이 쓰려면 플러그인으로, 조직 전체는 관리 설정으로 배포합니다. 우리 CRM 팀은 결제 코드 교차 리뷰를 이 방식으로 공용화했습니다.

운영 요령

스킬이 세 개를 넘으면 /doctor로 컨텍스트 비용을 확인합니다. 설명 목록은 컨텍스트 창의 1% 예산 안에서 잘리므로 자주 안 쓰는 스킬은 skillOverrides에서 "name-only"로 줄입니다. 배포·발송처럼 되돌리기 어려운 스킬은 반드시 사람만 호출하게 두고, 통과 검증은 앞 글의 훅에 맡깁니다. 스킬은 "이렇게 해라"이고 훅은 "이러면 막는다"입니다.

다음 레슨

개인 스킬을 팀 표준으로 올리는 4단계, 팀 도입 워크플로로 이어집니다.

정리

• 폴더 → SKILL.md → 새 세션 검증 → description 다듬기 → 스크립트 → 커밋 순서로 한 바퀴입니다.
• description은 사용자의 말, 본문은 검증 가능한 지시로 씁니다.
• 부작용 작업은 사람만 호출, 강제는 훅으로 분리합니다.

자주 묻는 질문