빠른 흐름

~/.claude/skills/summarize-changes/SKILL.md
.claude/skills/release-check/SKILL.md

/summarize-changes
/release-check

구성 방식

skills는 반복 프롬프트를 파일로 옮기는 구조다

Claude Code skill은 SKILL.md에 절차, 기준, 예시, 지원 파일을 묶어 두고 필요할 때 Claude가 불러 쓰는 확장 단위입니다. 같은 체크리스트나 긴 지시를 매번 채팅에 붙여 넣고 있다면 CLAUDE.md에 계속 늘리는 것보다 skill로 분리하는 편이 낫습니다.

---
description: Summarizes uncommitted changes and flags risky edits.
---

Current changes:

!`git diff HEAD`

Instructions:

Summarize the diff and list concrete risks.

CLAUDE.md는 항상 깔리는 프로젝트 규칙에 가깝고, skill은 필요한 순간에 호출되는 작업 절차에 가깝습니다. 길고 특정한 절차일수록 skill이 더 잘 맞습니다.

custom command는 skills 쪽으로 흡수해서 본다

최신 Claude Code 문서 기준으로 기존 .claude/commands/*.md 방식은 계속 동작하지만, custom command 개념은 skills와 같은 방향으로 통합되어 있습니다. 새로 만드는 반복 작업은 .claude/skills/<name>/SKILL.md를 우선 검토하고, 기존 .claude/commands/ 파일은 호환 레거시로 관리하는 편이 좋습니다.

.claude/commands/deploy.md
  -> 기존 command 유지 가능

.claude/skills/deploy/SKILL.md
  -> 새 확장 작성에 더 적합

skill은 지원 파일, frontmatter, 자동 호출 제어, subagent 실행 같은 확장 포인트를 더 자연스럽게 담을 수 있습니다.

호출 제어는 side effect 기준으로 나눈다

skill은 사용자가 /skill-name으로 직접 호출할 수 있고, Claude가 설명을 보고 자동으로 불러올 수도 있습니다. 배포, 커밋, 외부 전송처럼 side effect가 있는 절차는 사용자가 명시적으로 호출하게 제한하는 편이 안전합니다.

---
description: Deploy the application after tests pass.
disable-model-invocation: true
argument-hint: [environment]
---

Deploy $ARGUMENTS after running the required checks.

반대로 코드 스타일 규칙, 도메인 배경, 리뷰 기준처럼 자동으로 참고해도 안전한 내용은 Claude가 필요할 때 불러오게 둘 수 있습니다.

언제 나눌까

주의할 점

skill 설명은 Claude가 자동 호출 여부를 판단하는 신호입니다. 설명이 너무 넓으면 원치 않는 시점에 호출될 수 있으므로, side effect가 있는 작업은 자동 호출을 끄고 사용자가 직접 /skill-name으로 실행하게 해야 합니다.