Quick Reference

Claude Code의 built-in command는 CLI가 구현한 세션 제어이고, skill은 SKILL.md에 저장하는 재사용 가능한 작업 절차입니다. 반복 프롬프트·체크리스트는 skill로, 모든 세션에 항상 필요한 짧은 규칙은 CLAUDE.md로 둡니다. 배포·커밋·외부 전송처럼 부작용이 있는 skill은 자동 호출을 막고 사용자 호출과 권한 검토를 남깁니다.

.claude/skills/release-check/SKILL.md
  -> /release-check

CLAUDE.md
  -> "커밋 전 npm test를 실행한다."

skill을 만드는 법

skill directory 이름이 slash command 이름이 되고, frontmatter의 description은 Claude가 자동으로 불러도 되는 상황을 판단하는 신호입니다. 설명에는 대상 작업, 사용할 때, 사용하지 말아야 할 때를 적습니다. 긴 일반론보다 입력·검증·산출물·실패 시 보고를 명시하면 같은 workflow가 반복될 때 흔들림이 줄어듭니다.

---
name: review-diff
description: "현재 Git diff에서 correctness 위험을 찾을 때 사용합니다. 파일을 수정하거나 커밋하지 않습니다."
allowed-tools: Bash(git diff *), Read, Grep
---

1. git diff와 관련 테스트 결과를 읽습니다.
2. 파일 위치와 근거가 있는 위험만 보고합니다.
3. 수정·커밋·외부 요청은 하지 않습니다.

user-invocable은 slash 메뉴 노출을 제어할 뿐, 모델이 Skill tool로 호출하는 것까지 막지는 않습니다. 모델 자동 호출을 막으려면 disable-model-invocation: true를 사용합니다. 특정 skill만 허용·차단하려면 permission rule의 Skill(name) 또는 Skill(name *) 패턴을 사용합니다.

shell 전처리와 부작용

skill 안의 ! command 구문은 Claude가 나중에 실행할 명령이 아닙니다. skill 내용이 Claude에게 전달되기 전에 shell에서 실행되고, 출력이 prompt에 삽입됩니다. 따라서 ! command는 PR diff를 읽는 것처럼 현재 데이터를 가져오는 데는 편리하지만, 권한·secret·network·실행 시간 위험을 일반 skill 본문보다 먼저 만들 수 있습니다.

## 현재 변경
!`git diff --stat`

## 검사
- 변경 파일만 기준으로 위험을 보고합니다.

조직이나 프로젝트에서 user·project skill의 shell 전처리를 금지하려면 disableSkillShellExecution 설정을 씁니다. 이 설정이 켜지면 명령 출력 대신 정책상 비활성화되었다는 표시가 삽입됩니다. 이 정책은 bundled·managed skill에 같은 방식으로 적용되지 않을 수 있으므로, 설치한 skill의 출처와 전처리 명령을 별도로 검토합니다.

자주 틀리는 부분

피해야 할 구조
- 모든 긴 절차를 CLAUDE.md에 넣어 시작 context를 부풀린다.
- deploy skill을 모델이 자동 호출해도 되게 둔다.
- !`command`가 Claude의 일반 도구 승인 뒤에 실행된다고 가정한다.

권장 구조
1. 항상 필요한 규칙만 CLAUDE.md에 둔다.
2. 재사용 절차는 skill로 분리한다.
3. 부작용과 전처리 명령은 자동 호출·권한·출처를 함께 검토한다.