Claude Code에는 「Skills」라는 메커니즘이 있습니다. 특정 용도의 노하우를 SKILL.md라는 Markdown 파일에 정리해 두고, Claude가 필요할 때만 읽어 들여 동작을 전환하는 기능입니다.

본 기사에서는 실제로 보안 리뷰용 skill(security-review)을 설계한 과정을 소재로, SKILL.md의 문법(지키지 않으면 망가지는 부분)과 베스트 프랙티스(지키지 않아도 동작하지만 질이 떨어지는 부분)를 구분하여 정리합니다.

Skills는 3층 구조로 읽어 들여집니다.

1. 메타데이터 (name + description) … 항상 컨텍스트에 존재
2. SKILL.md 본문 … skill이 발화했을 때만 읽어 들여짐
3. 보조 리소스 (references/ 등) … 본문에서 참조되었을 때만 읽어 들여짐

이 단계적 공개(progressive disclosure) 메커니즘을 이해해 두면, "어떤 정보를 어느 층에 두어야 할지" 판단하기 쉬워집니다.

---
name: skill-name
description: 언제 사용하는지, 무엇을 하는지를 작성
...

name：필수입니다

description：필수입니다. 트리거(trigger) 판정에 사용되는 유일한 정보원이 됩니다. 본문에 아무리 자세하게 "언제 사용하는지"를 써 놓아도, 발화 판정에는 반영되지 않습니다

compatibility：임의 사항입니다. 필요한 툴이나 의존 관계가 있는 경우 작성합니다

이 3가지 항목 이외에는 사양상 정의되어 있지 않습니다. YAML 구문으로서의 기본 규칙(콜론 뒤의 반각 스페이스, 인덴트(indent)의 일관성)을 지키지 않으면 파싱(parsing)에 실패합니다.

여기에는 엄격한 문법이 존재하지 않습니다. 헤딩(heading) 구성도 불렛 포인트도 표도 자유롭게 구성할 수 있습니다. "문법 위반으로 망가지는" 것은 frontmatter의 YAML 부분뿐이며, 본문 측은 다음 장의 베스트 프랙티스 영역이 됩니다.

본문이 비대해지는 경우에는 references/ 하위로 분리하고, SKILL.md에서는 "필요할 때 이 파일을 읽는다"라는 유도선만 작성합니다. 300행을 초과하는 reference 파일에는 목차를 붙입니다.

트리거 조건은 구체적인 파일명·상황으로 작성합니다.

❌ 추상적: 보안에 관한 사항일 때 사용
◯ 구체적: SecurityConfig, AuthController, Filter 계열 클래스를 다룰 때는 반드시 사용

추상적인 조건은 "발화하지 않음/오발화함" 양쪽의 리스크를 낳습니다.

cloud-deploy/
├── SKILL.md # 선택 로직
└── references/
...

Claude는 필요한 reference 파일만 읽어 들이는 설계로 만들 수 있습니다.

여기서부터는 "Spring Boot 애플리케이션을 OWASP Top 10 관점에서 리뷰하는 skill"을 소재로, "왜 이 구성으로 했는지"를 남깁니다.

1. frontmatter (name / description)
2. 선언문 ＋ 스코프(scope) 방침 ＋ 발화 방침
3. 리뷰 대상의 우선순위
...

그대로 복사하여 .claude/skills/security-review/SKILL.md에 배치하면 동작합니다.

---
name: security-review
description: Spring Boot (Java) 애플리케이션의 코드를 OWASP Top 10 관점에서 리뷰하고, 근거를 포함한 지적 리포트를 작성한다. "보안 리뷰해줘", "OWASP 관점에서 체크해줘", "취약점이 없는지 봐줘"와 같은 의뢰, 또는 인증·인가·세션 관리·CORS·로그 출력을 포함하는 코드 (SecurityConfig, AuthController, Filter 계열 클래스 등)를 다룰 때는 반드시 이 스킬을 사용할 것.
...

이 skill은 "보안 리뷰해줘" 등의 명시적인 의뢰, 또는 인증·인가 계열 코드를 직접 편집할 경우에만 발화하도록, 의도적으로 좁게 설계했습니다. 이유는 일반적인 코드 리뷰 전반에 자동 적용하면 리뷰 비용이 증가하고, 불필요한 상황에서의 발화를 초래하기 때문입니다.

OWASP Top 10은 총 10개 항목(A01~A10)을 대상으로 한다고 정했지만, A06(취약하고 오래된 컴포넌트)에 대해서는 실제 의존 관계 스캔까지는 수행하지 않고, "버전 확인의 필요성을 지적하는 것에 그친다"라고 역할의 경계를 명기했습니다.

이는 전용 도구(Dependabot, OWASP Dependency-Check 등)가 담당해야 할 영역과 skill이 담당할 영역을 혼동하지 않기 위한 경계 설정입니다. 경계 설정을 생략하면 나중에 보는 사람이 '왜 A06만 취급이 미흡한지'를 판단하기 어려워집니다.

'무엇을 볼 것인가(관점표)'와 '어떻게 반환할 것인가(출력 포맷)'를 인접하게 배치함으로써, 표의 각 행이 그대로 출력의 각 행에 대응하는 1대1 관계를 시각적으로 보여줍니다. 진행 방식(절차)은 마지막에 독립시키고, '재료와 평가 기준이 갖춰진 후에 어떻게 작동할 것인가'라는 실행 단계를 분리했습니다.

• 문법상 지켜야 할 부분은 frontmatter의 YAML 부분뿐입니다.
  name

과 description

은 필수이며, 특히 description는 트리거 판정의 유일한 정보원입니다. 본문은 자유로운 Markdown이지만, 베스트 프랙티스(500행 기준/단계적 공개/description 작성 팁 등)를 지키면 재현성이 높아집니다.

• 발화 방침·스코프 방침·순서는 작성 이유와 함께 본문에 남김으로써, 나중에 다시 볼 때 검증하고 설명할 수 있는 상태를 유지할 수 있습니다.