Claude Code는 범용 AI 어시스턴트와 함께 제공됩니다. Skills(스킬)을 사용하면 이를 전문화할 수 있습니다. 스킬은 Kubernetes 배포, 데이터베이스 마이그레이션 작성, pull request 리뷰 또는 팀의 코딩 컨벤션 준수와 같은 특정 유형의 작업을 처리하는 방법을 Claude Code에게 가르치는 markdown 파일입니다.
"React 컴포넌트 작성해줘"와 "우리 디자인 시스템을 따르고, 커스텀 hook을 사용하며, 적절한 error boundaries와 접근성 속성을 갖춘 React 컴포넌트를 작성해줘"의 차이가 바로 스킬입니다.
공식 Claude Code 문서에서는 이제 한 가지를 명확히 하고 있습니다. 바로 커스텀 커맨드가 스킬로 통합되었다는 점입니다. .claude/commands/에 있는 기존 파일들도 여전히 작동하지만, 더 풍부한 메타데이터, 지원 파일 및 자동 로딩을 지원하는 스킬이 권장되는 추상화 방식입니다. 현재 팀 워크플로우를 표준화하고 있다면, 먼저 스킬로 구축하고 레거시 커맨드는 호환성 경로로 취급하세요.
스킬의 실제 구조
스킬은 SKILL.md 엔트리포인트가 있는 디렉토리에 위치합니다. 설명이 현재 작업과 일치할 때 Claude가 자동으로 로드하거나, /skill-name으로 직접 호출할 수 있습니다.
.claude/
skills/
deploy/
SKILL.md # /deploy
review-pr/
SKILL.md # /review-pr
write-test/
SKILL.md # /write-test
Claude는 여전히 .claude/commands/deploy.md를 지원하며, 슬래시 커맨드도 계속 작동합니다. 하지만 현대적인 버전은 .claude/skills/deploy/SKILL.md입니다.
단순한 이름 변경처럼 들릴 수 있지만, 이는 중요합니다. 스킬은 지원 파일, frontmatter, 호출 제어 및 서브 에이전트 힌트를 포함할 수 있기 때문입니다. 단순한 커맨드 파일은 Claude에게 무엇을 할지 알려주지만, 스킬은 팀이 작업이 어떻게 완료되기를 기대하는지 Claude에게 알려줍니다.
첫 번째 스킬 작성하기
실용적인 예시로, 팀의 커밋 메시지 컨벤션을 강제하는 스킬을 만들어 보겠습니다.
.claude/skills/commit/SKILL.md 파일을 생성합니다.
---
name: commit
description: Generate and validate conventional commits for this repo.
---
# Commit Workflow
## Steps
1. Run `git diff --staged` to see what's being committed
2. Analyze the changes and categorize: feat, fix, refactor, docs, test, chore
3. Write a commit message following our convention:
- Format: `type(scope): description`
- Scope is the package or module name
- Description is imperative mood, lowercase, no period
- Body explains WHY, not WHAT
4. If changes touch multiple scopes, create separate commits
5. Run `git commit -m "message"` with the generated message
## Rules
- Never use `--no-verify` to skip hooks
- Never amend published commits
- If tests fail in pre-commit, fix the issue first
## Examples
- `feat(billing): add stripe webhook handler`
- `fix(auth): handle expired refresh tokens`
- `refactor(api): extract rate limiter to shared package`
이제 /commit을 사용하면 Claude Code는 막연한 "변경 사항 커밋해줘"라는 지침 대신 구조화된 워크플로우를 갖게 됩니다.
레거시 커맨드 파일이 이미 있다면 마이그레이션하는 동안 계속 작동하도록 유지하되, 이전 레이아웃에 더 이상 투자하지 마세요. 공식 문서는 스킬이 앞으로 나아갈 방향임을 명확히 하고 있습니다.
스킬의 위치
Claude Code는 현재 네 곳에서 스킬을 찾습니다.
- 개인 스킬:
~/.claude/skills/<skill-name>/SKILL.md - 프로젝트 스킬:
.claude/skills/<skill-name>/SKILL.md - 모노레포 내 중첩된 프로젝트 스킬
- 플러그인 제공 스킬
이를 통해 다음과 같이 깔끔하게 구분할 수 있습니다.
- 개인적인 작업 스타일을 위한 개인 스킬
- 저장소 컨벤션을 위한 프로젝트 스킬
- 재사용 가능한 패키지 워크플로우를 위한 플러그인 스킬
팀 도입을 위해서는 프로젝트 스킬을 저장소에 커밋하세요. 이것이 "내 노트북에 좋은 프롬프트가 있다"와 "팀이 이제 반복 가능한 워크플로우를 갖게 되었다"의 차이입니다.
스킬 디자인 패턴
체크리스트 패턴
여러 검증 단계가 있는 작업에 가장 적합합니다.
# Pre-Deploy Checklist
Before deploying, verify each item:
- [ ] `pnpm typecheck` passes
- [ ] `pnpm test` passes
- [ ] No console.log statements in production code
- [ ] Environment variables documented in .env.example
- [ ] Database migrations are reversible
- [ ] API changes are backward compatible
If any check fails, stop and report the issue. Do not proceed with deployment.
의사 결정 트리 패턴
상황에 따라 접근 방식이 달라지는 작업에 가장 적합합니다.
# Bug Fix Workflow
1. Reproduce the bug (find or write a failing test)
2. Identify the root cause:
- If it's a type error → fix the type definition at the source
- If it's a race condition → add proper locking/sequencing
- If it's a missing validation → add schema validation at the boundary
- If it's a logic error → fix and add regression test
3. Verify the fix doesn't break existing tests
4. Write a test that would have caught this bug
템플릿 패턴
일관된 결과물을 생성하는 데 가장 적합합니다.
# New API Endpoint
Create a new API endpoint following our conventions:
## File Structure
- Route handler: `apps/api/src/routes/{resource}/{action}.ts`
- Schema: `apps/api/src/schemas/{resource}.ts`
- Test: `apps/api/src/routes/{resource}/__tests__/{action}.test.ts`
## Required Elements
- Zod schema for request validation
- Authentication middleware
- Rate limiting
- Structured error responses using errorResponse()
- Success responses using successResponse()
- OpenAPI documentation comments
커뮤니티 스킬 설치하기
Claude Code 생태계에는 성장하는 커뮤니티 스킬 라이브러리가 있습니다. 다음 명령어로 설치할 수 있습니다.
npx add-skill username/repo-name -y
인기 있는 스킬 컬렉션:
coreyhaines31/marketingskills(29개의 마케팅/SEO 스킬)hedging8563/lemondata-api-skill(LemonData API 연동)
설치된 스킬은 ~/.claude/commands/에 나타나며 모든 프로젝트에서 작동합니다.
설치된 스킬 팩은 단순한 슬래시 커맨드 markdown이 아니라 점차 적절한 스킬의 형태를 갖추고 있습니다. 자체 저장소를 유지 관리하는 경우, OpenCode + LemonData의 패턴이 여기에도 적용됩니다. 스킬을 임의의 프롬프트 파일에 숨기지 말고 워크플로우와 가깝게 유지하세요.
프로젝트 스킬 vs 글로벌 스킬
| 위치 | 범위 | 사용 사례 |
|---|---|---|
.claude/skills/ |
해당 프로젝트 전용 | 프로젝트 컨벤션, 배포 워크플로우 |
~/.claude/skills/ |
모든 프로젝트 | 개인적 선호도, 재사용 가능한 습관 |
.claude/commands/ |
레거시 호환성 | 여전히 작동하는 이전 슬래시 커맨드 파일 |
프로젝트 스킬은 팀 전체가 혜택을 볼 수 있도록 저장소에 커밋해야 합니다. 글로벌 스킬은 개인적인 워크플로우 선호도를 위한 것입니다.
고급: Hook이 포함된 스킬
스킬은 자동화된 강제를 위해 hook(특정 이벤트에서 실행되는 쉘 커맨드)을 참조할 수 있습니다.
# Pre-Commit Check
Before any commit, the following hooks run automatically:
- `pre-commit`: runs typecheck + lint
- `post-commit`: updates changelog
If a hook fails, investigate the error output and fix the issue.
Do not use --no-verify to bypass hooks.
Hook 자체는 .claude/settings.json에서 설정합니다.
{
"hooks": {
"pre-commit": "pnpm typecheck && pnpm lint-staged"
}
}
여기서 스킬은 단순한 프롬프트 스니펫 이상의 의미를 갖게 됩니다. 유용한 팀 설정은 종종 세 가지 레이어로 구성됩니다.
- Claude에게 워크플로우를 알려주는 스킬
- 워크플로우를 강제하는 hook
- 사람에게 워크플로우를 설명하는 저장소 문서
이 레이어 중 하나라도 누락되면 시스템이 취약해집니다. hook 없는 스킬은 권고 사항에 불과하게 됩니다. 스킬 없는 hook은 불투명해집니다. 둘 다 없는 문서는 아무도 따르지 않는 낡은 정책이 됩니다.
지원 파일이 진짜 업그레이드인 이유
이전 커맨드 markdown보다 스킬을 선호해야 하는 가장 중요한 이유는 지원 파일 때문입니다.
커맨드 파일에서는 모든 것이 하나의 덩어리로 있어야 합니다. 하지만 스킬 디렉토리에서는 다음과 같은 것들을 별도로 유지할 수 있습니다.
- 템플릿
- 예시
- 쉘 헬퍼
- 긴 참조 노트
- 검증 스크립트
이를 통해 SKILL.md를 짧고 명확하게 유지하면서도, 필요한 경우 Claude가 구조화된 자료를 가져올 수 있도록 할 수 있습니다.
이는 특히 다음과 같은 경우에 유용합니다.
- 배포 워크플로우
- 스키마 마이그레이션 체크리스트
- 다단계 코드 리뷰 프로세스
- 제품별 통합 플레이북
팀에서 여러 모델이나 여러 코딩 도구를 사용하고 있다면, 이 페이지를 코딩 모델 비교 및 Cursor / Cline / Windsurf 설정 가이드와 함께 살펴보세요. 기본 모델이나 에디터가 변경될 때 좋은 스킬의 중요성은 더욱 커집니다.
효과적인 스킬을 위한 팁
파일 경로와 명명 규칙을 구체적으로 명시하세요. "컴포넌트 생성"은 모호합니다. "PascalCase 명명 규칙을 사용하여
src/components/ui/에 컴포넌트 생성"은 실행 가능합니다.올바른 출력 예시를 포함하세요. Claude Code는 추상적인 규칙보다 예시를 통해 더 잘 배웁니다.
하지 말아야 할 것을 정의하세요. "적절한 타입을 사용하세요"보다 "
any타입을 절대 사용하지 마세요"가 더 강제하기 쉽습니다.스킬을 집중적으로 유지하세요. 워크플로우당 하나의 스킬이 적당합니다. 모든 것을 다루는 200줄짜리 스킬보다 각 작업을 잘 처리하는 40줄짜리 스킬 5개가 더 유용합니다.
스킬의 버전을 관리하세요. 컨벤션이 발전함에 따라 스킬도 업데이트하세요. 오래된 스킬은 낡은 패턴을 강요하기 때문에 스킬이 없는 것보다 나쁩니다.
스킬을 자동으로 로드할지 아니면 수동으로만 실행할지 결정하세요. 많은 팀이 이를 잊어버리고 왜 Claude가 관련 없는 대화에서 배포 스킬을 호출하는지 궁금해하곤 합니다.
실제 효과
스킬을 도입한 팀들은 다음과 같은 지속적인 개선을 보고하고 있습니다.
- 리뷰 전에 컨벤션이 준수되므로 코드 리뷰 주기가 단축됩니다.
- 신입 개발자도 숙련된 개발자와 동일한 가이드를 받으므로 온보딩 시간이 감소합니다.
- AI가 프로젝트 표준에 대한 명시적인 컨텍스트를 갖게 되므로 AI 생성 코드의 품질이 향상됩니다.
투자는 적지만(처음 몇 개의 스킬을 작성하는 데 30분), 그 보상은 모든 상호작용에서 복리로 돌아옵니다.
가장 유용한 사고 모델은 이것입니다. 스킬은 Claude를 위한 지름길이 아니라, 팀을 위한 버전 관리된 워크플로우 아티팩트입니다.
단 하나의 스킬만 작성해야 한다면, 코드베이스에서 가장 비용이 많이 드는 반복적인 의사 결정을 인코딩하는 스킬을 만드세요.
여러분만의 규칙에 따라 AI와 함께 구축하세요. LemonData는 여러 제공업체의 코딩 모델을 위한 하나의 API 키를 제공하므로, 워크플로우가 스킬로 인코딩되면 전체 툴체인을 재구축하지 않고도 모델을 전환할 수 있습니다.