Claude Code 커뮤니티에서 찾은 커스텀 Skill 세 가지 패턴
반복 절차를 SKILL.md에 담는 세 가지 패턴을 설명합니다. 테스트 중심 개발, 팀 규칙 리뷰, 운영 절차 점검을 구분하고 처음에는 파일을 바꾸지 않는 일정 정리 스킬로 연습합니다.
목차
세 줄로 먼저 읽기
이번 방문에서 한 편은 바로 볼 수 있습니다.
반복해서 붙여 넣는 지시부터 스킬로 만듭니다
Claude Code에 같은 검토 기준을 계속 설명하고 있다면 스킬로 묶을 수 있습니다. 스킬은 반복해서 사용할 지시와 참고 자료를 담는 폴더이고, 중심 파일 이름은 SKILL.md입니다. 마크다운은 제목과 목록 등을 기호로 적는 문서 형식입니다. 예를 들어 “회의 메모에서 정해진 일정만 뽑고 빠진 정보는 미정으로 표시한다”는 절차를 저장합니다.
이 글은 커뮤니티 프로젝트에서 볼 수 있는 세 가지 활용 패턴을 설명합니다. 모든 팀에서 효과가 입증된 순위나 그대로 설치할 추천 목록은 아닙니다. 처음에는 작은 스킬을 직접 읽고 결과를 확인한 뒤, 개발과 운영 업무에서 어떻게 확장하는지 보겠습니다. 문법은 2026년 10월 4일 공식 문서를 기준으로 했습니다.
첫 연습: 일정 정리 스킬 하나 만들기
설치와 로그인을 마친 Claude Code, 편집기, 중요 자료가 없는 연습 폴더를 준비합니다. 아직 설치하지 않았다면 윈도우 설치나 맥 설치의 첫 실행까지 진행합니다.
편집기로 연습 폴더를 열고 다음 구조대로 폴더와 파일을 만듭니다. .claude는 이름 앞에 점이 있는 폴더입니다. 같은 파일이 이미 있다면 덮어쓰지 말고 새 연습 폴더를 사용합니다.
연습 폴더/
└── .claude/
└── skills/
└── meeting-check/
└── SKILL.mdSKILL.md에 아래 내용을 저장합니다. 맨 위 두 --- 사이가 이름과 용도를 정하는 YAML 프론트매터입니다. 이 부분을 포함해 전부 저장해야 합니다.
---
name: meeting-check
description: 사용자가 준 짧은 모임 메모에서 날짜와 장소를 정리한다.
disable-model-invocation: true
---
사용자가 함께 준 메모만 읽는다.
날짜와 장소를 각각 한 줄로 쓴다.
메모에 없는 정보는 미정이라고 쓴다.
파일을 읽거나 수정하지 않고 답변만 한다.연습 폴더의 터미널에서 claude --permission-mode default로 Claude Code를 실행한 뒤 대화 입력칸에 아래 요청을 넣습니다. 터미널 셸에 직접 넣는 명령이 아닙니다.
/meeting-check 연습용 독서 모임은 2026년 10월 12일이야. 장소는 아직 안 정했어.확인할 결과는 날짜가 2026년 10월 12일이고 장소가 미정이라는 두 줄입니다. “도서관”처럼 입력에 없는 장소를 만들면 실패입니다. 스킬이 목록에 없다면 파일 이름이 SKILL.md.txt는 아닌지, 현재 작업 폴더 아래 경로가 맞는지 확인합니다. Claude Code 안에서 /exit로 나온 뒤 같은 폴더에서 claude --permission-mode default로 새 세션을 엽니다. 동일 이름의 다른 스킬이 표시되면 목록의 출처 경로도 확인합니다.
다음에는 아래처럼 두 번째 요청을 완전히 새로 보냅니다.
/meeting-check 연습용 독서 모임은 2026년 10월 12일이야. 장소는 도서관 2층이야.이제 장소가 도서관 2층으로 바뀌는지 봅니다. 그래도 미정이라고 하면 스킬 문장을 “메모에 장소가 있으면 그대로 쓰고, 없을 때만 미정이라고 쓴다”로 고쳐 저장한 뒤 같은 스킬을 다시 호출합니다. 수정이 반영되지 않으면 새 세션에서 같은 입력으로 확인합니다. 스킬은 파일을 만드는 데서 끝나지 않고 입력과 결과를 대조하며 개선합니다.
이 예시의 disable-model-invocation: true는 Claude가 알아서 호출하지 않고 사용자가 직접 호출하도록 하는 Claude Code 전용 설정입니다. 파일 수정 자체를 기술적으로 차단하는 권한 설정은 아닙니다. Claude Code 스킬 문서
패턴 1. 테스트 중심 개발 절차를 나누기
TDD는 구현 전에 원하는 동작을 테스트로 적고, 실패를 확인한 뒤 구현하는 개발 방식입니다. 예를 들어 “음수 금액은 거부한다”라는 요구가 있으면, 음수를 넣었을 때 오류가 나야 한다는 검사를 먼저 만듭니다.
흐름은 Red, Green, Refactor입니다. Red는 아직 기능이 없어 검사에 실패하는 단계, Green은 필요한 구현을 넣어 통과하는 단계, Refactor는 동작을 유지하며 코드 구조를 정리하는 단계입니다. 명령을 잘못 쓰거나 프로그램 설치가 안 돼 실패한 것은 원하는 Red가 아닙니다.
AI가 구현 결과에 맞춰 테스트를 쓰면 요구사항을 놓칠 수 있습니다. 그렇다고 모든 AI가 반드시 TDD를 위반한다고 단정할 수는 없습니다. 테스트가 요구를 확인하는지, 실패 원인이 맞는지와 구현 뒤 통과하는지를 실제 실행으로 확인해야 합니다.
커뮤니티의 superpowers에는 테스트 중심 개발과 검토 절차를 담은 스킬이 있습니다. tdd-guard는 훅과 테스트 결과를 이용해 개발 순서를 검사하는 별도 프로젝트입니다. 이름을 복사하는 것만으로 설치되거나 모든 언어에서 바로 작동하지는 않습니다. 테스트 실행기와 결과 수집 설정을 맞춰야 합니다.
별도 대화로 맡기는 것과 파일을 나누는 것은 다릅니다
context: fork는 스킬을 별도 서브에이전트, 즉 특정 작업을 맡는 보조 AI에서 실행하는 설정입니다. 메인 대화 전체를 그대로 전달하지 않으므로 요구사항을 스킬과 입력에 충분히 적어야 합니다.
---
name: requirement-check
description: 전달받은 요구사항에서 누락된 테스트 조건을 찾는다.
context: fork
agent: Explore
---위 코드는 설정 부분만 보여 주는 예시입니다. 이것만 저장하면 테스트 담당, 구현 담당, 정리 담당 세 명이 자동으로 생기는 것은 아닙니다. 실제로 쓸 때는 검토할 요구사항과 결과 형식을 본문에 추가해야 합니다.
대화가 분리되어도 작업 폴더에 있는 구현 코드를 읽을 가능성은 남습니다. 파일 접근까지 분리하려면 도구 권한과 작업 환경을 별도로 설계해야 합니다. 테스트 작성자에게 필요한 파일만 주었는지도 확인합니다. 이 글의 첫 연습에는 서브에이전트가 필요하지 않습니다. 별도 에이전트 실행 조건
훅은 구현과 적용 범위를 확인합니다
훅은 지원하는 이벤트에 연결해 실행하는 명령이나 검사입니다. 예를 들어 PreToolUse는 도구 실행 전에 동작합니다. 차단 결과를 반환하도록 만든 훅이면 해당 도구 실행을 막을 수 있지만, 단순 알림용 훅도 있어 모든 훅이 규칙을 강제하는 것은 아닙니다.
“파일을 저장할 때마다 검사한다”는 설명도 범위를 확인해야 합니다. Claude의 편집 도구에 연결한 검사와 편집기에서 직접 저장한 동작은 같지 않습니다. 셸 명령 등 다른 수정 경로까지 검사하는지 검증해야 합니다. 공식 훅 참조
검사 프로그램이 없는 경로를 설정에 적으면 검사가 완성되지 않습니다. tdd-guard를 도입한다면 해당 프로젝트의 설치 안내와 지원 환경, 훅이 쓰는 권한을 먼저 검토합니다. 여기서는 실제 프로젝트에 설치하지 않고 역할만 구분합니다.
패턴 2. 팀 규칙을 필요한 때만 읽는 리뷰
코드 리뷰는 바뀐 코드가 요구사항과 팀 기준에 맞는지 살피는 일입니다. 린터는 미리 정한 규칙으로 코드를 검사하는 도구입니다. 일부 팀 규칙도 린터로 구현할 수 있지만, 변경 목적이나 업무 조건을 함께 봐야 하는 판단은 따로 검토합니다.
예를 들어 “새 입력 항목에는 빈 값 처리 기준이 있어야 한다”라는 규칙이 있다면 리뷰 결과에 파일 위치, 해당 규칙, 빠진 처리와 확인 방법이 나와야 합니다. 단순히 “품질이 좋아 보인다”는 답변만으로는 수정할 대상을 알 수 없습니다.
Progressive Disclosure는 필요한 내용을 단계적으로 읽는 방식입니다. 스킬 본문에는 작업 순서와 참고 파일을 언제 읽을지 적고, 상세 기준은 분리합니다.
.claude/skills/team-check/
├── SKILL.md
└── references/
├── input-rules.md
└── api-rules.md아래는 본문에 넣을 수 있는 조건부 참조 예시입니다. 완성 스킬이 아니라 본문 조각이므로 직접 만들 때는 첫 실습처럼 이름과 설명도 함께 작성합니다. 참고 파일에는 팀이 실제로 합의한 규칙을 적어야 합니다.
- 사용자 입력 화면이 바뀌면 [입력 규칙](references/input-rules.md)을 읽는다.
- 서버 API가 바뀌면 [API 규칙](references/api-rules.md)을 읽는다.
- 해당하지 않는 참고 파일은 읽지 않는다.
- 결과는 파일 위치, 관련 규칙, 문제와 확인 방법 순서로 쓴다.
- 파일은 수정하지 않고 검토 결과만 답한다.@reference/...라고 쓰기만 하면 확장자를 판단해 필요한 파일만 자동으로 고르는 것은 아닙니다. 조건과 경로를 함께 적고 실제로 어떤 자료를 읽었는지 확인합니다. 스킬 본문 200줄은 보편적인 강제 제한도 아닙니다. Agent Skills 명세는 본문을 500줄 미만으로 유지하고 상세 자료를 분리하도록 권장합니다. Agent Skills 명세
처음 리뷰 예시에는 광범위한 allowed-tools: Bash(gh *)를 넣을 필요가 없습니다. gh는 GitHub 작업을 문자 명령으로 처리하는 도구이고 조회뿐 아니라 게시와 변경 명령도 있으므로, 전체를 허용하는 설정을 읽기 전용이라고 설명해서는 안 됩니다. 이미 가진 코드 조각이나 변경 파일부터 범위를 정해 검토합니다.
결과를 확인할 때는 의도적으로 빈 값 처리를 빠뜨린 작은 예제를 줍니다. 이를 지적하는지 보고, 수정된 예제에는 같은 문제를 다시 지적하지 않는지도 확인합니다. 규칙이 많다는 사실보다 실제 오류를 구분하는지가 중요합니다.
패턴 3. 운영 절차를 읽고 점검하는 런북
런북은 배포나 장애 대응처럼 반복되는 운영 절차를 적은 문서입니다. 배포는 변경한 프로그램을 실제 서비스에 반영하는 작업이고, 롤백은 이전 버전으로 되돌리는 조치입니다. 이런 업무를 스킬로 만들면 사람이 읽을 절차와 AI가 참고할 절차를 함께 관리할 수 있습니다.
다만 문서가 스킬이 되었다고 서비스 설정이나 실행 코드와 영원히 일치하는 것은 아닙니다. 주소, 권한, 테스트 명령이 바뀌면 스킬도 고쳐야 합니다. 스킬은 고정된 프로그램처럼 매번 같은 실행을 보장하지 않으므로 완료 기준이 필요합니다.
처음에는 배포 실행 대신 절차에 빠진 항목을 찾는 데 사용합니다. 아래는 기존 운영 문서를 검토할 때 쓸 수 있는 지시 예시입니다.
제공한 런북에서 대상 서비스, 실행 환경, 테스트 명령,
실패 시 중단 조건, 복구 담당자와 복구 절차가 있는지 확인해 줘.
없는 정보는 추측하지 말고 확인 필요로 적어 줘.
명령 실행, 파일 수정, 배포나 메시지 발송은 하지 마.가상의 런북에 “테스트 후 배포한다”만 적어 요청해 보면 여러 항목이 빠져 있습니다. 결과에 실제 운영 주소나 담당자를 만들어 넣지 않았는지 확인합니다. 다음에는 담당자와 중단 조건을 추가해 빠진 항목 목록이 줄어드는지 봅니다.
disable-model-invocation: true는 자동 호출을 막는 데 유용하지만 사용자가 호출한 뒤 모든 외부 작업을 승인했다는 뜻은 아닙니다. 실제 배포용 스킬에서는 현재 요청의 대상과 허용 범위, 실패 시 대응을 별도로 확인해야 합니다. “배포 명령이 끝남”과 “서비스가 정상 작동함”도 따로 검증합니다.
실행 전에 셸 명령을 넣는 기능은 나중에 사용합니다
다음은 스킬에 현재 Git 상태를 넣는 고급 문법 예시입니다. Git은 파일의 변경 기록을 관리하는 도구입니다.
## 현재 상태
- Git 상태: !`git status --short`
- 변경 내역: !`git diff --stat`느낌표와 백틱 안의 명령은 스킬 내용이 전달되기 전에 실행될 수 있습니다. 단순 인용문으로 생각하면 안 됩니다. 해당 폴더가 Git 저장소인지, 명령과 권한이 맞는지 확인해야 하고 출력된 내용도 모델이 읽는 문맥에 포함됩니다. 토큰 사용이 사라지는 기능은 아닙니다. 동적 컨텍스트 주입
따라서 처음 만든 일정 정리 스킬에는 이 문법을 넣지 않았습니다. 먼저 입력만으로 원하는 두 줄을 만드는지 확인한 다음 실제 파일이나 도구가 필요한 절차로 넓힙니다.
세 패턴에서 확인할 결과
| 패턴 | 확인할 결과 |
|---|---|
| 테스트 중심 개발 | 요구사항에 맞는 실패를 확인하고 구현 뒤 같은 검사가 통과함 |
| 팀 규칙 리뷰 | 파일 위치와 규칙 근거가 있는 문제를 찾고 수정 뒤 다시 확인함 |
| 런북 점검 | 누락된 운영 정보를 구분하고 실행과 결과 확인 조건을 명시함 |
스킬은 Claude Code만의 독점 형식이 아닙니다. Agent Skills를 지원하는 다른 도구에서도 기본 구조를 사용할 수 있지만 context: fork 같은 Claude Code 확장 옵션까지 그대로 작동한다고 가정하지 않습니다.
스킬 파일을 Git에 저장하면 변경 이력을 남기고 동료와 검토할 수 있습니다. 공유했다고 모두가 자동으로 실행하는 것은 아니므로 각 환경의 지원 여부와 로딩 상태도 확인합니다. 처음에는 반복해서 설명하던 작은 절차 하나를 저장하고, 정상 입력과 정보가 빠진 입력 두 가지를 비교하는 것으로 시작하면 됩니다.
참고 자료
3줄 요약
-
스킬은 반복 절차를 담은 지침이며 호출했다고 모든 단계의 성공이나 규칙 준수가 보장되지는 않습니다.
-
테스트 중심 개발, 팀 규칙 리뷰, 운영 절차 점검은 목적에 맞는 입력과 확인 기준이 필요합니다.
-
처음에는 작은 일정 정리 스킬을 저장하고 빠진 정보가 있는 입력으로 결과를 확인하며 수정합니다.
제대로 이해했는지 한 문제로 확인해 볼까요?
답을 고르면 바로 풀이가 나와요.
context: fork로 실행한 스킬을 정확히 설명한 것은 무엇인가요?
이 글이 도움이 되었나요?
설치 다음 단계인 명령어, 플랜 모드, 메모리, 한도를 차례로 익힙니다
- 1Claude Code 이해하기: 파일을 읽고 수정하는 AI 도구
- 2클로드 코드(Claude Code) 설치 따라하기: 터미널 입문 포함
- 3클로드 코드 슬래시 명령어(Slash Commands) 알아보기
새 글과 AI 소식을 메일로 받아 보세요
AI가 바꾸는 일과 도구, 측정 실무 이야기를 매주 한 번 보내 드려요.