Skill 패턴과 모범 사례
흔한 패턴, 안티패턴, 그리고 뛰어난 skill 빌더의 습관
⏱ 예상 ~8분
01 · 읽기
이제 skill 이 어떻게 동작하는지 알았으니, 개발자들이 매일 실제로 쓰는 패턴을 봐요.
가장 인기 있는 skill 은 몇 가지 카테고리에 속해요: - 코드 스타일 - 네이밍 컨벤션, 형식 규칙, 구조 패턴 강제 - 코드 리뷰 - PR 과 코드 변경에 대한 일관된 체크리스트 - 커밋 메시지 - Conventional Commits 같은 형식 강제 - 테스팅 - 프로젝트의 테스트 프레임워크와 패턴 맞추기 - 문서화 - 문서, 주석, README 작성 방식 표준화
각 패턴은 같은 구조를 따라요: 명확한 규칙, 구체적인 예시, 명시적인 출력 형식. 가장 유용한 두 가지를 봐요.
핵심 정리
- 코드 스타일 skill 은 네이밍, 형식, 구조 컨벤션을 강제해요
- 리뷰 skill 은 일관된 코드 리뷰 체크리스트를 제공해요
- 커밋 메시지 skill 은 Conventional Commits 같은 형식을 강제해요
- 테스팅 skill 은 프로젝트의 기존 테스트 패턴을 따라요
- 문서화 skill 은 문서 작성 방식을 표준화해요
02 · 코드 예제
아래는 모든 커밋 메시지가 Conventional Commits 형식을 쓰도록 강제하는 skill 이에요.
commit-style/SKILL.md
---
name: Commit Message Style
description: Enforces Conventional Commits format
instructions: Use when creating git commits
---
## Format
All commits must follow Conventional Commits:
```
<type>(<scope>): <description>
[optional body]
```
## Types
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation only
- `refactor`: Code change that neither fixes nor adds
- `test`: Adding or updating tests
- `chore`: Maintenance (dependencies, CI, build)
## Rules
- Description must be lowercase, no period at the end
- Scope is optional but encouraged
- Body should explain WHY, not WHAT (the diff shows what)
- Max 72 characters for the first line
## Examples
Good: `feat(auth): add password reset flow`
Good: `fix(api): handle null response from payment gateway`
Bad: `Fixed stuff`
Bad: `Update code`
얼마나 명시적인지 보세요 - 정확한 형식, 열거된 타입, 글자 수 제한, 좋은 예시와 나쁜 예시. 규칙이 명시적일수록 Claude 의 커밋이 더 일관돼요. "좋은 커밋 메시지를 써" 같은 모호한 지시는 쓸모없어요.
03 · 코드 예제
아래는 Claude에게 프로젝트의 기존 테스트 컨벤션을 맞추라고 하는 skill 이에요.
test-writer/SKILL.md
---
name: Test Writer
description: Writes tests matching project conventions
instructions: Use when writing or updating tests
---
## Conventions
- Use `describe` / `it` blocks (not `test`)
- Test file goes next to source: `Foo.ts` → `Foo.test.ts`
- Use `vi.fn()` for mocks (Vitest, not Jest)
- Arrange-Act-Assert pattern in every test
## What To Test
- Happy path first
- Error cases and edge cases
- Boundary values (0, 1, -1, empty string, null)
- Never test implementation details — test behavior
## Naming
`it('should return 404 when user not found')`
Not: `it('test user')`
이 skill 은 프로젝트의 특정 테스트 프레임워크 (Vitest) 와 패턴 (describe/it, vi.fn) 을 참조해요. 일반적인 "좋은 테스트를 써" 지시는 쓸모없어요 - Claude 는 이미 좋은 테스트를 쓰려고 해요. 이 skill 은 나의 특정 컨벤션을 알려줘요.
04 · 퀴즈
기억해 두세요: skill 은 Claude가 스스로는 알 수 없는 규칙을 추가해야 해요. 다음 중 어느 지시가 충분히 명시적이라 Claude 의 행동을 실제로 바꿀까요?
- 좋은 코드를 쓰는 데 도움이 되는 어시스턴트가 되어줘
- API endpoint 를 쓸 때 camelCase key 의 JSON 을 반환하고, kebab-case URL 을 쓰고, error-codes.ts 파일의 에러 코드를 써
- 코드를 쓸 때 항상 모범 사례를 따라줘
- 시니어 엔지니어처럼 코드를 써줘
05 · 분류 드래그
Skill 품질에 가장 큰 차이를 만드는 게 뭔지 생각해 봐요. 예시가 없는 모호한 skill 은 구체적인 것보다 못해요 - 이 사례들을 영향이 큰 것부터 작은 것 순으로 놓아 봐요.
(이 섹션은 인터랙티브해요 — JavaScript를 켜 주세요.)
06 · 읽기
어떤 skill 은 오히려 Claude를 더 나쁘게 만들어요. 아래는 피해야 할 것들이에요: 너무 모호함: "좋고 깨끗한 코드를 써." Claude 는 이미 그렇게 하려고 해요. Skill 은 Claude가 스스로 알 수 없는 구체적인 규칙을 추가해야 해요.
너무 김: 모든 가능한 시나리오에 대한 규칙을 가진 500 줄짜리 skill 은 Claude 의 컨텍스트를 압도해요. Skill 을 하나의 작업 흐름에 집중시켜요. 여러 개의 집중된 skill 이 거대한 하나보다 나아요.
내장 동작 중복: Claude 는 이미 코드를 형식화하고, 마크다운을 쓰고, git 을 사용해요. Claude가 기본적으로 잘 하는 일에 skill 공간을 낭비하지 마세요.
상충하는 규칙: "항상 주석을 추가해" + "코드를 최소화해" 는 혼란을 만들어요. 테스트 전에 규칙들이 내부적으로 충돌하지 않는지 확인해요.
핵심 정리
- 모호한 skill 은 쓰지 말아요 - 명시적이지 않으면 아예 쓰지 말아요
- 거대한 skill 은 쓰지 말아요 - skill 하나에 집중된 작업 흐름 하나
- Claude가 기본적으로 잘 하는 일을 중복시키지 말아요
- skill 안에 상충하는 규칙이 있는지 확인해요
07 · 읽기
이제 대부분의 Claude Code 사용자가 모르는 초능력을 가졌어요: Claude에게 내가 정확히 어떻게 일하는지 가르치는 능력.
모든 팀에는 컨벤션이 있어요. 모든 개발자에게는 선호가 있어요. Skill 은 말로 하지 않은 그런 규칙을 영구적이고, 공유 가능하고, 버전 관리되는 지시문으로 바꿔줘요.
작게 시작해요. 내가 Claude에게 가장 자주 말하는 한 가지를 골라서 skill 로 만들어요. 테스트하고, 다듬고, 커밋해요. 그리고 하나 더 추가해요. 시간이 지나면서 skill 컬렉션은 힘의 증폭기가 돼요 - skill 을 하나씩 쓸 때마다 Claude가 내 특정 작업에 더 능숙해져요.
범용 AI 어시스턴트와 개인화된 AI 워크플로우의 차이는요? Skill 이에요.
핵심 정리
- 가장 자주 반복하는 지시 하나에 대한 skill 로 시작해요
- 반복: 테스트, 다듬기, 커밋
- 프로젝트 skill 을 git 으로 공유해서 팀 전체가 혜택을 봐요
- 시간이 지나면서 컬렉션이 쌓여요 - 각 skill 은 Claude를 내 작업에 더 똑똑하게 만들어요
- Skill 이 범용 AI 어시스턴트와 개인화된 AI 워크플로우의 차이예요
08 · 퀴즈
"좋고 깨끗한 코드를 써" 라고 적힌 skill 을 만들었어요. 테스트해 봤더니 Claude 출력이 별로 달라지지 않은 것 같아요. 왜 그럴까요?
- SKILL.md 파일에 문법 에러가 있어요
- Skill 은 Opus 모델에서만 작동해요
- 지시가 너무 모호해요 - Claude 는 이미 좋은 코드를 쓰려고 해요
- skill 을 추가한 뒤에 Claude Code를 재시작해야 해요
09 · 빈칸 채우기
모든 가능한 시나리오를 다루는 500 줄짜리 skill 은 안티패턴이에요. 각각이 하나의 작업 흐름을 다루는 여러 _____ skill 을 쓰는 게 좋아요.
⚠ 전체 인터랙티브 경험에는 JavaScript가 필요해요. JavaScript를 켜고 새로 고침해 주세요.
※ 이 사이트는 독립 운영되는 교육 프로젝트로, Anthropic의 공식 제품이 아니에요. Claude™ 는 Anthropic, PBC 의 상표예요.