"Automating Playwright with Claude Code" 시리즈의 5부입니다. 4부에서는 단일 playwright-form-tester 스킬 (Skill)을 구축했습니다. 이 포스트에서는 모든 세션을 비대하게 만들지 않고도 그와 유사한 수십 개의 스킬을 설치할 수 있게 해주는 메커니즘을 설명하며, 이를 실제로 활용하기 위해 스킬을 어떻게 구조화해야 하는지 보여줍니다.

만약 여러분이 "잠깐, 내가 10개의 스킬을 설치하면 Claude가 매 요청마다 10개를 모두 컨텍스트 (Context)에 로드하나?"라고 궁금해한 적이 있다면 — 정답은 '아니오'입니다. 그 이유는 Claude Code 스킬 (Skill) 설계의 가장 우아한 부분 중 하나인 점진적 공개 (Progressive Disclosure) 때문입니다. 이를 이해하면 단순히 얼마나 많은 스킬을 설치하느냐가 아니라, 스킬을 어떻게 _작성_하느냐가 달라집니다.

점진적 공개 (Progressive Disclosure)가 중요한 이유

• 스킬 라이브러리는 비용 없이 확장됩니다. 현재 사용하지 않는 스킬에 대해 토큰 세금 (Token tax)을 지불하지 않고도 전체 테스트 라이프사이클을 아우르는 30개 이상의 스킬을 설치할 수 있습니다.

• 스킬을 작성하는 방식이 바뀝니다. 프론트매터 (Frontmatter)만 항상 로드된다는 것을 알게 되면, 더 간결한 설명을 작성하고 무거운 세부 사항은 Claude가 필요할 때만 여는 파일로 밀어 넣게 됩니다.

• 스킬의 실행 여부 동작을 설명해 줍니다. 스킬이 전혀 트리거 (Trigger)되지 않거나, 트리거되지 않아야 할 때 트리거된다면, 그 해결책은 거의 항상 이 로딩 모델 — 대개 설명 (Description) 부분에 있습니다.

• 스킬과 비대한 CLAUDE.md의 차이점입니다. CLAUDE.md 파일은 항상 컨텍스트 (Context)에 완전히 포함됩니다. 하지만 스킬은 그렇지 않으며, 그것이 바로 핵심입니다.

  사전 요구 사항

• playwright-form-tester 스킬 (Skill)이 설치된 이 시리즈의 4부를 완료했을 것.

• SKILL.md 파일을 편집하고 그와 함께 하위 폴더를 생성하는 데 익숙할 것.

  목차

1. 스킬의 세 가지 레이어 (The Three Layers of a Skill)
2. 1단계: 항상 컨텍스트에 포함되는 것 (Layer 1)
3. 2단계: 매칭 시 로드되는 것 (Layer 2)
4. 3단계: 요청 시에만 로드되는 것 (Layer 3)
5. 단계별 가이드: Form-Tester 스킬 리팩토링하기
6. 설명(Description) 필드가 당신이 작성할 가장 중요한 문장인 이유
7. 결론

스킬의 세 가지 레이어 (The Three Layers of a Skill)

설치된 모든 스킬(Skill)은 필요할 때만 다음의 세 단계에 걸쳐 로드됩니다:

이것이 바로 30개의 스킬을 설치했다고 해서 매 요청마다 30개 스킬 분량의 컨텍스트 비용을 지불하지 않는 이유입니다. 당신은 모든 스킬에 대해 레이어 1(Layer 1) 비용만 지불하며, 여기에 당신이 질문한 내용과 실제로 관련이 있는 한두 개의 스킬에 대해서만 레이어 2(Layer 2)와 레이어 3(Layer 3) 비용을 추가로 지불하게 됩니다.

1단계: 항상 컨텍스트에 포함되는 것 (Layer 1)

모든 Claude Code 세션이 시작될 때, 설치된 각 스킬에서는 오직 이 정도의 정보만 로드됩니다:

---
name: playwright-form-tester
description: Test HTML forms using Playwright CLI. Use this whenever the user
...

• 그게 전부입니다. 워크플로우 단계(workflow steps)도, 코드 블록(code blocks)도, 그 외 다른 것도 없습니다.
• 이 양을 설치된 스킬의 개수만큼 곱해보면, 왜 30개의 스킬이 (30 × 전체 SKILL.md 길이)가 아니라 대략 (30 × ~100 토큰) 정도의 비용만 발생하는지 알 수 있습니다.

2단계: 매칭 시 로드되는 것 (Layer 2)

당신이 _"결제 양식을 테스트해줘(test the checkout form)"_와 같이 말하는 순간, Claude는 이를 위의 description 필드와 매칭하며, 그제서야 전체 본문을 가져옵니다:

## Process
1. `playwright-cli navigate <url>`를 사용하여 대상 페이지로 이동합니다.
2. `playwright-cli snapshot`을 실행하여 요소 참조(예: `e12`)를 가져옵니다.
...

• 매칭되지 않은 다른 모든 설치된 스킬은 레이어 1(Layer 1) 상태로 유지됩니다. 즉, 해당 요청을 위해 그 본문은 절대 로드되지 않습니다.
• 이 지점이 스킬이 실제 토큰 비용을 발생시키기 시작하는 단계이지만, 오직 해당 스킬이 관련 있는 단 하나의 요청에 대해서만 발생합니다.

3단계: 요청 시에만 로드되는 것 (Layer 3)

이것은 대부분의 사람들이 활용하지 못하는 계층이며, 스킬 (Skill)이 복잡해질수록 가장 중요해지는 계층입니다. 만약 여러분의 바디 (body) 내 단계가 파일(스크립트, 긴 참조 문서, 템플릿 등)을 참조하고 있다면, 해당 파일은 그 특정 단계가 실제로 실행될 때만 열립니다.

.claude/skills/playwright-form-tester/
├── SKILL.md
├── scripts/
...

• 스크립트의 _실행 결과 (execution output)_가 컨텍스트 (context)에 들어가는 것이지, 소스 코드 (source code)가 들어가는 것이 아닙니다. Claude는 check-known-selectors.sh를 실행하고 그 결과만을 볼 뿐, 스크립트 전체를 보지는 않습니다.
• references/negative-test-checklist.md는 워크플로 (workflow) 단계에서 "부정 테스트 체크리스트를 참조하라"고 명시된 경우에만 읽힙니다. 그렇지 않으면 디스크에 그대로 머물러 있으며, 비용을 전혀 발생시키지 않습니다.

단계별 가이드: Form-Tester 스킬 리팩터링 (Refactoring)

Part 4에서 다룬 스킬에 이를 적용해 보겠습니다. 현재 우리의 부정 테스트 (negative-testing) 가이드는 바디 (body) 내에 직접 포함되어 있습니다:

## Notes
- 항상 양식(form)당 하나의 유효한 케이스와 최소 하나의 유효하지 않은 케이스를 테스트하세요.
- 양식에 CAPTCHA 또는 OTP 단계가 있는 경우, 중단하고 사용자에게 어떻게 할지...

이 정도 길이는 인라인 (inline)으로 두어도 괜찮지만, SQL 인젝션 (SQL injection) 페이로드 (payload), 유니코드 (Unicode) 에지 케이스 (edge cases), 필드 길이 경계값 등을 다루는 40줄짜리 체크리스트로 늘어난다고 상상해 보십시오. 그 정도 규모라면 인라인 방식 대신 참조 파일 (reference file)로 분리하는 것이 적절합니다.

1. 파일을 생성합니다:

mkdir -p .claude/skills/playwright-form-tester/references

2. 상세 체크리스트를 references/negative-test-checklist.md로 이동합니다.
3. 바디 (body)에 직접 넣는 대신 해당 파일을 참조하도록 지정합니다:

## Notes
- 항상 양식(form)당 하나의 유효한 케이스와 최소 하나의 유효하지 않은 케이스를 테스트하세요.
- 전체 부정 테스트 체크리스트(인젝션 페이로드, 경계값 등)를 확인하려면...

이제 이 체크리스트는 모든 양식 테스트마다 들어가는 것이 아니라, Claude가 실제로 그것을 필요로 하는 요청에서만 컨텍스트 (context)에 포함됩니다.

설명 (Description) 필드가 여러분이 작성할 문장 중 가장 중요한 이유

만약 스킬 (Skill)이 예상대로 작동하지 않는다면, 그 이유는 거의 항상 설명 (description) 때문입니다. 왜냐하면 설명은 Claude가 나머지 부분을 로드할지 결정하기 전에 의존할 수 있는 유일한 정보이기 때문입니다.

결론

점진적 공개(Progressive disclosure) 덕분에 Skills는 거대한 CLAUDE.md 파일로는 불가능한 방식으로 확장할 수 있습니다. 이는 마치 크고 잘 정리된 라이브러리의 이점을 누리면서도, 현재 수행하는 작업과 관련된 작은 부분에 대해서만 비용을 지불하게 해줍니다. 다음 게시물에서는 바로 이 구조를 활용하여 단일 폼 테스터(form-tester) Skill을 페이지 객체(page objects), 불안정한 테스트 디버깅(flaky-test debugging), 그리고 로케이터 전략(locator strategy)을 다루는 작은 패키지로 확장할 예정입니다. 이는 프레임워크가 더 넓은 QA-skills 생태계를 구축하기 시작한 방식과 매우 유사합니다.

혹시 references/ 또는 scripts/를 사용하여 Skill을 재구성해 보신 적이 있나요? 댓글로 경험을 알려주세요!