# 31 · 스킬 정의 (복사용)

**언제 읽나**: 스킬을 만들거나 수정할 때.
**저장 위치**: `.claude/skills/<이름>/SKILL.md` (프로젝트) 또는 `~/.claude/skills/<이름>/SKILL.md` (전역)
**적용**: 저장 후 **세션을 새로 시작**해야 인식된다.

---

## 형식 규칙

- 폴더 구조를 정확히 지킨다: `skills/<이름>/SKILL.md`
  ❌ `skills/<이름>/<이름>/SKILL.md` 처럼 한 겹 더 들어가면 인식되지 않는다.
- frontmatter 필수: `name`, `description`.
- `description`에 **사용자가 실제로 쓸 말**을 넣는다. 이것이 호출 조건이다.
- 본문은 **절차와 규칙**으로 쓴다. 설명문이 아니라 지시문이다.

---

## 검증 스위트 스킬

```markdown
---
name: verify-suite
description: 프로젝트의 설계 규칙마다 검증 스크립트를 1:1로 만들고 전체를 한 번에 돌려 회귀를 잡는다. "검증 스크립트 만들어줘", "회귀 테스트", "규칙 깨졌는지 확인" 요청에 사용한다.
---

# 검증 스위트

## 규칙
1. 설계 규칙 1개당 스크립트 1개. 파일명은 지키는 성질로 짓는다.
2. 각 스크립트 첫 줄 주석에 어떤 규칙을 지키는지 쓴다.
3. 조건을 실제로 만든다. 추정하지 않는다.
4. 결과를 숫자로 출력한다.
5. 마지막에 process.exit(통과 ? 0 : 1) 을 호출한다.
6. Playwright는 의존성으로 설치하지 않는다. 필요할 때만 설치한다.

## 측정으로 끝낸다
- "창 크기와 무관" → 창 3종에서 같은 값임을 출력해 비교한다.
- "성능 괜찮다" → 작은 규모로 재고, 큰 규모도 실제로 돌린다.
- "한도 초과를 처리한다" → 실제로 초과시켜서 표시·생존·예외 0건을 확인한다.

## 가장 흔한 실패
UI를 바꾸면 기존 스크립트의 셀렉터가 어긋나 조용히 통과한다.
UI 변경 커밋에 검증 수정을 포함하고, 스위트는 부분이 아니라 전부 돌린다.
```

---

## CLAUDE.md 작성 스킬

```markdown
---
name: claude-md-contract
description: 프로젝트 CLAUDE.md를 계약서 형식으로 쓰고 유지한다. "CLAUDE.md 정리해줘", "프로젝트 규칙 문서화", "왜 이렇게 했는지 기록" 요청에 사용한다.
---

# CLAUDE.md = 계약서

## 절 구성 (이 순서)
1. 호출 — 어떤 말로 부르면 이 프로젝트인지
2. 실행/배포 — 복사해서 바로 쓰는 명령. 함정도 함께
3. 대상 환경 — 지원 범위를 "사양"으로 선언한다 (미검증은 공백이 아니라 사양)
4. 핵심 아키텍처 (변경 금지) — A-1, A-2... 번호를 붙이고 각 항목에
   무엇을 고정하는가 / 왜 중요한가(깨면 무엇이 연쇄로 무너지는가) / 검증 방법
5. 결정된 제약 — C-1, C-2... 각 항목에
   결정 / 근거(실측·공식문서) / 탈락한 대안과 이유 / 유지할 것
6. 암묵적 계약 — 깨면 에러 없이 틀린 결과가 나오는 전제들
7. 확인된 미해결 문제 — K-1, K-2... 우선순위와 실측 근거. "재발견에 시간 쓰지 말 것"
8. 검증 / 진행 상태 — 체크박스. 완료와 미실시를 섞지 않는다

## 작성 규칙
- 근거 없는 규칙을 쓰지 않는다. 숫자를 쓰면 측정 방법도 쓴다.
- 개선으로 보이지만 이미 탈락한 대안을 명시한다. 가장 비싼 정보다.
- 실패를 지우지 않는다. 해결된 항목은 "어떻게 구조로 막았는지"를 남긴다.
```

---

## 배포 스킬

```markdown
---
name: cf-pages-deploy
description: 정적 사이트를 Cloudflare Pages에 배포한다. "배포해줘", "Pages에 올려줘", "재배포" 요청에 사용한다.
---

# Cloudflare Pages 배포

## 명령
wrangler.toml 이 있으면 루트에서:
  npx wrangler pages deploy --branch=main --commit-dirty=true

빌드가 필요하면:
  npm run build
  npx wrangler pages deploy dist --project-name <proj> --branch main --commit-dirty=true

## 함정
- 최신 wrangler는 pages project create 가 실패한다. 이미 만든 프로젝트는 deploy만 쓴다.
- 특정 페이지를 홈으로: 출력 폴더에 _redirects 파일 → `/ /portfolio.html 200`
  단 Pages가 .html을 확장자 없는 경로로 자동 308 하므로 URL이 바뀐다.
- 개인정보가 담긴 파일을 그대로 올리지 않는다. 마스킹 빌드를 따로 만든다.

## 배포 후 반드시
  curl -sI https://<url>/ | head -1
  curl -sL https://<url>/<page> | grep -o "<title>[^<]*</title>"
파일을 올렸으면 content-type도 확인한다. text/html 이 나오면 그 파일은 없는 것이다.
"Deployment complete" 로그는 서빙 증거가 아니다.
```