Claude Code Skills - AI 코딩 도구에 행동 규칙을 심는 법

스킬이란 무엇인가

Claude Code를 쓰다 보면 한 가지 아쉬운 점이 생깁니다. 분명 똑똑한 도구인데, 매번 같은 맥락을 설명해야 한다는 것입니다. "테스트 먼저 작성해줘", "바로 코드 고치지 말고 원인부터 파악해줘" 같은 말을 세션마다 반복하게 됩니다. 처음엔 대수롭지 않았는데, 이게 쌓이니까 꽤 번거롭다는 생각이 들었습니다.

Skills는 이 문제를 해결합니다. SKILL.md라는 파일 하나를 넣으면, Claude가 매 세션마다 그 지침을 자동으로 따르게 됩니다. CLAUDE.md가 프로젝트의 컨텍스트를 알려주는 파일이라면, SKILL.md는 Claude의 행동 규칙을 정의하는 파일입니다.

두 가지 작동 방식

스킬은 두 가지 방식으로 작동합니다.

자동 로드 스킬은 ~/.claude/skills/ 폴더에 넣으면 세션 시작 시 자동으로 적용됩니다. 별도로 호출할 필요가 없습니다. CLAUDE.md처럼 시스템 프롬프트의 일부가 되는 것입니다.

슬래시 커맨드 스킬은 /blog create, /obsidian view처럼 명시적으로 호출할 때만 활성화됩니다. 평소에는 명령어 목록만 인식해두고, 실제 호출 시점에 지침이 주입됩니다.

처음에는 자동 로드 스킬이 매 요청마다 전체 SKILL.md 내용을 컨텍스트 윈도우에 주입한다고 생각했습니다. 하지만 실제로 확인해보니 2단계 로딩 방식이었습니다. 평소에는 스킬의 name과 description만 프롬프트에 포함되고(한 줄 수준), 스킬이 호출될 때만 전체 내용이 주입됩니다. MCP 도구처럼 풀 스키마가 매 메시지마다 로드되는 것과는 근본적으로 달라서, 스킬을 여러 개 넣어도 토큰 부담은 거의 없습니다.

자동 로드와 슬래시 커맨드의 실질적인 차이는 토큰 소비가 아니라 호출 방식입니다. 자동 로드 스킬은 Claude가 description을 보고 맥락에 맞으면 자동으로 활성화할 수 있고, 슬래시 커맨드 스킬은 사용자가 명시적으로 호출해야만 활성화됩니다. 어느 쪽이든 토큰 비용은 동일합니다.

왜 스킬을 추가하게 되었나

모노레포를 운영하면서 반복되는 패턴이 있었습니다. 버그가 나면 Claude에게 고쳐달라고 하는데, 원인도 파악하지 않고 바로 코드를 수정하는 경우가 많았습니다. 기능을 추가할 때도 테스트 없이 구현부터 작성했습니다. 물론 매번 "테스트 먼저 써줘"라고 말하면 되지만, 그걸 잊는 순간 이전의 패턴으로 돌아갑니다.

돌이켜 생각해보면, 이건 Claude의 문제가 아니라 제 문제였습니다. 매번 지시하는 걸 기억해야 하는 구조 자체가 잘못된 것입니다. 사람이 기억하는 게 아니라, 시스템이 강제해야 한다는 생각이 들었습니다.

그래서 awesome-claude-skills 레포를 분석했습니다. 수십 개의 오픈소스 스킬 중에서 현재 프로젝트에 실제로 도움이 될 것만 골라서, 3개를 설치했습니다.

설치한 스킬 3가지

1. test-driven-development

obra/superpowers에서 가져온 TDD 스킬입니다. 핵심 규칙은 단순합니다. "실패하는 테스트 없이 프로덕션 코드를 작성하지 않는다."

이 스킬이 설치되면 Claude는 기능 구현을 요청받았을 때 RED-GREEN-REFACTOR 사이클을 따릅니다.

RED      → 실패하는 테스트를 먼저 작성
GREEN    → 테스트를 통과시키는 최소한의 코드 작성
REFACTOR → 중복 제거, 네이밍 정리

예를 들어 "하이브리드 검색에 태그 필터 추가해줘"라고 요청하면, 이전에는 바로 embedding.service.ts를 수정하기 시작했습니다. 스킬 적용 후에는 먼저 embedding.service.spec.ts에 실패 테스트를 작성하고, 그 테스트가 실패하는 것을 확인한 뒤에야 구현에 들어갑니다.

사실 CLAUDE.md에 TDD 가이드라인을 이미 적어뒀었습니다. 하지만 가이드라인은 "참고"이고 스킬은 "강제"라는 차이가 있습니다. 스킬에는 "테스트 전에 작성된 코드는 삭제해야 한다"는 규칙까지 들어 있어서, 실수로 순서를 건너뛰는 일 자체를 방지합니다. 이 차이가 생각보다 큽니다.

2. systematic-debugging

같은 superpowers 레포에서 가져온 디버깅 스킬입니다. 핵심 원칙은 "근본 원인을 찾기 전에 코드를 수정하지 않는다"입니다.

4단계 프로세스를 따릅니다.

Phase 1 - 근본 원인 조사
  에러 메시지 읽기, 재현, git diff로 최근 변경 확인,
  컴포넌트 경계마다 데이터 추적

Phase 2 - 패턴 분석
  정상 작동하던 코드와 비교, 의존성 확인

Phase 3 - 가설 검증
  단일 가설 수립 → 단일 변수만 변경해서 테스트

Phase 4 - 구현
  실패 테스트 작성 → 수정 → 검증

이 스킬이 특히 필요하다고 느낀 건 모노레포의 통합 지점 때문입니다. 예를 들어 일일 보고서가 슬랙에 안 오는 문제가 생겼을 때, 이전에는 슬랙 웹훅 URL부터 확인했습니다. 하지만 실제 원인은 GA4 → GSC → Grafana → Gemini → Slack으로 이어지는 파이프라인 중간에 있었을 수도 있습니다. Grafana 서비스가 타임아웃 나면 그 이후 단계는 전부 실행되지 않으니까요. 스킬이 컴포넌트 경계마다 데이터를 추적하라고 안내하기 때문에, 이런 다중 서비스 문제를 놓치지 않게 됩니다.

3번 이상 수정이 실패하면 STOP하라는 규칙도 있습니다. 솔직히 말하면, Claude에게 버그를 맡겼을 때 추측으로 이것저것 고치다가 오히려 문제를 키운 적이 있었습니다. 이 규칙 하나만으로도 설치할 가치가 있다고 생각했습니다.

그리고 이 스킬은 보조 파일 3개를 함께 포함하고 있습니다.

• root-cause-tracing.md - 에러를 콜 체인 역방향으로 추적하는 기법

• defense-in-depth.md - 데이터가 지나는 모든 레이어에서 검증하는 전략

• condition-based-waiting.md - sleep(3000) 대신 조건 기반 대기로 교체하는 방법

1개 설치로 4개 방법론을 얻는 셈입니다.

3. owasp-security

agamm/claude-code-owasp에서 가져온 보안 스킬입니다. OWASP Top 10:2025, ASVS 5.0, 그리고 Agentic AI Security(ASI01-ASI10) 기준으로 코드를 자동 검토합니다.

이 스킬을 추가한 이유는 솔직합니다. 보안 리뷰를 "나중에" 하겠다고 미루는 습관 때문입니다. JWT 인증, Google OAuth, Redis 토큰 관리, XSS 방지 같은 보안 관련 코드가 프로젝트 곳곳에 있는데, 기능 구현에 집중하다 보면 보안은 뒷전이 되기 쉽습니다. "일단 돌아가게 하고, 보안은 나중에 보자"는 식이 되는 것입니다.

스킬이 설치되면 인증 관련 코드를 작성하거나 리뷰할 때 자동으로 보안 관점의 검토가 이뤄집니다.

• A01 Broken Access Control - rate limit 적용 여부

• A07 Authentication Failures - 로그인 실패 횟수 제한

• ASVS 5.0 - 비밀번호 정책, 유출 DB 검사

• ASI (Agentic AI) - MCP 서버 최소 권한 원칙

특히 Agentic AI 보안 가이드라인이 포함되어 있다는 점이 눈에 들어왔습니다. MCP 서버를 운영하고 있는 입장에서, 목표 하이재킹이나 도구 오용 같은 AI 에이전트 특유의 보안 위협은 기존 OWASP만으로는 커버가 안 됩니다. 이 부분까지 체계적으로 점검할 수 있게 된 건 예상치 못한 수확이었습니다.

설치 방법

설치는 단순합니다. SKILL.md 파일을 ~/.claude/skills/ 하위에 넣으면 끝입니다.

# TDD 스킬
mkdir -p ~/.claude/skills/test-driven-development
curl -sL https://raw.githubusercontent.com/obra/superpowers/main/skills/test-driven-development/SKILL.md \
  -o ~/.claude/skills/test-driven-development/SKILL.md

# systematic-debugging (보조 파일 포함)
mkdir -p ~/.claude/skills/systematic-debugging
curl -sL https://raw.githubusercontent.com/obra/superpowers/main/skills/systematic-debugging/SKILL.md \
  -o ~/.claude/skills/systematic-debugging/SKILL.md
curl -sL https://raw.githubusercontent.com/obra/superpowers/main/skills/systematic-debugging/root-cause-tracing.md \
  -o ~/.claude/skills/systematic-debugging/root-cause-tracing.md
curl -sL https://raw.githubusercontent.com/obra/superpowers/main/skills/systematic-debugging/defense-in-depth.md \
  -o ~/.claude/skills/systematic-debugging/defense-in-depth.md
curl -sL https://raw.githubusercontent.com/obra/superpowers/main/skills/systematic-debugging/condition-based-waiting.md \
  -o ~/.claude/skills/systematic-debugging/condition-based-waiting.md

# OWASP 보안
mkdir -p ~/.claude/skills/owasp-security
curl -sL https://raw.githubusercontent.com/agamm/claude-code-owasp/main/.claude/skills/owasp-security/SKILL.md \
  -o ~/.claude/skills/owasp-security/SKILL.md

설치 후 Claude Code를 새로 시작하면 바로 인식됩니다. 별도 설정이나 재시작은 필요 없습니다.

커스텀 스킬 만들기 - webapp-testing

위 3개는 범용적인 스킬입니다. 어떤 프로젝트에서든 유용합니다. 하지만 쓰다 보니 프로젝트 특성에 맞춘 스킬이 더 필요하다는 생각이 들었습니다.

그래서 만든 첫 번째 커스텀 스킬이 webapp-testing입니다. Playwright MCP를 활용해 로컬 웹앱을 실제 브라우저에서 테스트하는 방법론을 담았습니다.

출발점은 Anthropic 공식 레포의 webapp-testing 스킬이었습니다. Playwright로 웹앱을 테스트하는 방법론을 담고 있는데, Python Playwright 기반이라는 문제가 있었습니다. 현재 프로젝트에서는 이미 Node.js Playwright로 E2E 테스트를 하고 있고, Playwright MCP 서버도 설치되어 있어서 Python 의존성을 따로 추가할 이유가 없었습니다.

원본 스킬을 분석해봤습니다.

webapp-testing/ (원본)
├── SKILL.md                    ← 핵심: 테스트 방법론
├── scripts/with_server.py      ← 멀티 서버 관리 (Python)
└── examples/                   ← Python Playwright 예제
    ├── element_discovery.py
    ├── console_logging.py
    └── static_html_automation.py

분석해보니 진짜 가치 있는 건 SKILL.md의 방법론이었습니다. "바로 클릭하지 말고 스크린샷을 먼저 찍어서 페이지 상태를 파악하라", "networkidle 대기 후 DOM을 검사하라" 같은 원칙들입니다. Python 스크립트 자체는 단순한 보일러플레이트에 가까웠습니다.

결국 가져갈 것과 바꿀 것을 나눴습니다.

• 가져간 것: reconnaissance-then-action 패턴, networkidle 대기 원칙, 단계별 스크린샷 검증

• 바꾼 것: Python 스크립트 → Playwright MCP 도구 활용, 범용 포트 → 프로젝트 고정 포트(3000, 3001, 3003, 5173), 서버 관리 → 기존 pnpm dev 스크립트 활용

커스텀 스킬의 핵심 규칙은 이렇습니다.

NEVER INTERACT WITH A PAGE WITHOUT SEEING IT FIRST

모든 인터랙션 전에 스크린샷이나 스냅샷을 먼저 찍는다.
보지 않고 클릭하는 건 시간 낭비다.

테스트 프로세스는 4단계로 구성했습니다.

Phase 1 - 정찰 (Reconnaissance)
  navigate → wait → screenshot → snapshot → console check

Phase 2 - 계획 (Plan)
  스냅샷의 ref 속성으로 정확한 타겟 식별, 성공 조건 정의

Phase 3 - 실행 (Execute)
  screenshot → act → wait → screenshot → verify
  한 번에 하나의 액션만. 검증 없이 다음으로 넘어가지 않는다.

Phase 4 - 보고 (Report)
  테스트 결과, 스크린샷, 콘솔 에러, 네트워크 실패 요약

기존에 설치한 다른 스킬과의 연계도 고려했습니다. UI 버그를 발견하면 systematic-debugging의 Phase 1에서 Playwright로 증거를 수집하고, E2E 테스트를 새로 작성할 때는 test-driven-development의 RED 단계에서 실패하는 Playwright 테스트부터 시작합니다.

이런 식으로 오픈소스 스킬의 방법론은 가져오되, 실행 환경은 프로젝트에 맞게 바꾸는 접근이 효과적이었습니다. 범용 스킬을 그대로 쓰는 것보다, 프로젝트 맥락을 반영한 커스텀 스킬이 실제 작업에서 훨씬 유용합니다.

돌이켜보며

스킬을 설치하고 나서 달라진 건, Claude의 능력이 아니라 Claude가 일하는 방식입니다. 같은 모델인데 행동이 달라집니다. 테스트를 먼저 쓰고, 버그를 체계적으로 추적하고, 보안을 실시간으로 검토합니다.

결국 CLAUDE.md가 "이 프로젝트가 뭔지" 알려주는 거라면, Skills는 "이 프로젝트에서 어떻게 일해야 하는지"를 알려주는 것입니다. 이 구분이 명확해지니까 Claude와의 협업이 한결 편해졌다는 생각이 듭니다.