번역 파일을 고칠 때마다 검사 순서가 달라지는 팀을 생각해 봅시다. 어떤 날은 빠진 키를 찾았지만 `{name}` 같은 치환 문자를 놓쳤고, 다른 날은 화면만 확인한 채 검사를 끝냈습니다. Claude Code의 기존 `.claude/commands/` 파일은 계속 작동하지만, 이렇게 반복되는 절차는 `.claude/skills/<name>/SKILL.md`로 옮기면 선택 조건과 검사 스크립트를 한곳에서 관리할 수 있습니다.

핵심 Skill은 특정 요청에서 불러 쓰는 작업 설명서입니다. 모든 대화에 적용할 규칙은 프로젝트 지침에 남기고, 번역 검사처럼 입력·판정·중단 조건이 정해진 절차만 Skill로 옮깁니다.

긴 공통 지침은 엉뚱한 작업에도 따라왔습니다

검사 절차를 긴 프로젝트 지침에 넣으면 번역과 무관한 작업도 그 내용을 읽습니다. 담당자마다 확인 항목도 달라집니다. 여기서는 범위를 "번역 파일이 바뀐 뒤, 기준 언어와 키 및 치환 문자를 비교하는 일"로 좁힙니다. 치환 문자는 `{name}`이나 `%s`처럼 실행할 때 실제 값으로 바뀌는 표시입니다.

스킬이 약속할 결과

머리말의 `description`은 Claude가 이 Skill을 언제 선택할지 판단하는 문장입니다. 본문에는 실행 순서와 멈춰야 할 조건을 적습니다.

최소 스킬 명세
---
name: locale-gate
description: 번역 파일 변경 뒤 키·치환 문자·형식을 검사한다.
---

1. 기준 언어와 키를 비교한다.
2. 치환 문자 집합을 검사한다.
3. 실패 파일을 보고한다.
4. 자동 수정하지 않는다.

선택되는 요청과 선택되면 안 되는 요청을 함께 시험합니다

자동 선택 시험은 Skill 이름을 직접 부르지 않고도 필요한 요청에서 선택되는지 보는 검사입니다. "한국어 번역 파일을 바꿨으니 누락을 검사해 줘"에는 선택돼야 합니다. 반면 "버튼 문구 세 개를 추천해 줘"에는 선택되지 않아야 합니다. 정상 파일은 종료 코드 0, `{name}`을 뺀 파일은 종료 코드 1과 파일명·키를 출력하도록 정하면 성공 여부가 분명해집니다.

자동화하지 않는 경계

한 번뿐인 절차와 운영 배포는 스킬로 감싸지 않습니다. 스크립트가 파일을 고치거나 네트워크로 전송하려 하면 읽기 단계에서 중단합니다.

스킬의 발동 조건을 찾는 명령

기존 번역 검사에서 입력 파일, 실패 기준과 파일 수정 여부를 먼저 뽑아냅니다. 이 조사 결과가 있어야 프로젝트 공통 규칙과 Skill 안에 둘 절차를 나눌 수 있습니다.

기존 명령의 입력과 부작용을 찾는 요청
cd ~/projects/storefront
claude --permission-mode plan

첫 프롬프트: 번역 검사 절차를 읽고 스킬에 둘 내용과 프로젝트 지침에 남길 내용을 구분하세요. 파일은 수정하지 마세요.
읽을 대상: i18n/, scripts/, .claude/skills/, CLAUDE.md
허용 도구: Read, Glob, Grep
Edit와 Bash는 검토 전 승인하지 않습니다.
반환 형식: 발동 요청 / 제외 요청 / 검사 스크립트 / 실패 출력 / 수정 파일

스킬의 발동과 제외 조건을 맞춥니다

검토할 산출물은 발동 요청과 제외 요청의 두 목록, 그리고 읽기 전용 검사 결과입니다. 두 목록이 겹치지 않으면 번역 검사 Skill과 로컬 검사만 작성합니다. 정상 입력과 치환 문자가 빠진 고정 입력을 실행하고, 임시 파일은 지우되 번역 본문은 고치지 않는 조건을 작업 범위에 넣습니다.

이전 명령과 새 스킬의 동작을 나란히 확인합니다

번역 검사 결과와 함께 스킬·스크립트 변경만 남았는지 확인합니다.

스킬 이전 뒤 호환성과 파일 범위를 보는 명령
scripts/check-locales.sh
git diff -- .claude/skills scripts/
git status --short

성공과 실패 출력은 이 정도면 충분합니다

정상 입력과 고의로 망가뜨린 입력을 한 번씩 실행합니다. 긴 설명보다 어떤 파일의 무엇이 다른지 바로 알려주는 출력이 쓸모 있습니다.

독자가 확인할 검사 결과 예시
PASS ko/messages.json: 128 keys, placeholders matched
FAIL ja/messages.json: checkout.greeting missing {name}
수정한 번역 파일: 없음

스킬이 자동 수정을 시도하면 중단합니다

검사 스크립트가 번역 파일을 고치거나 네트워크로 내용을 보내면 즉시 중단합니다. 같은 발동 조건과 읽기 전용 판정을 다듬을 때만 재개하고, 배포나 번역 생성까지 요구가 넓어지면 검사 결과와 발견 시험을 남긴 뒤 별도 스킬 작업으로 나눕니다.

스킬은 호출 문구보다 작업 계약에 가깝다

현재 구조에서는 스킬 디렉터리의 `SKILL.md`가 설명, 적용 조건과 절차의 중심입니다. 짧은 명령 하나를 저장하는 데 그치지 않고, 어떤 요청에 쓰며 무엇을 읽고 어떤 검증을 통과해야 하는지 적습니다. 설명이 너무 넓으면 관련 없는 요청에서도 로드되므로 적용 범위를 구체적으로 씁니다.

팀 전체가 함께 써야 하는 스킬은 프로젝트에 두고 검토 기록을 남깁니다. 여러 스킬과 MCP 서버를 묶어 배포할 필요가 생긴 뒤에만 플러그인을 검토합니다. 비밀값이나 개인 경로를 스킬 본문에 넣지 않고, 외부 명령은 최소 권한과 실패 시 중단 조건을 함께 둡니다.

공식 출처