Agent SDK 슬래시 명령
공식 기준: https://code.claude.com/docs/en/agent-sdk/slash-commands
기준일: 2026-07-26 · CLI 기준 2.1.220
개요
슬래시 명령은 /로 시작하는 세션 제어·워크플로 진입점입니다. SDK 프롬프트로 보내 context compact, 컨텍스트 리셋, 커스텀 리뷰 체크리스트 등을 실행할 수 있습니다. 지원되는 명령만 SDK 세션에서 동작하며, 일부 대화형 CLI 전용 명령은 제외될 수 있습니다.
핵심 개념
- 발견: system init의
slash_commands/ skills 목록 - 전송: user prompt 문자열에
/command args - 커스텀:
.claude/commands/*.md(레거시) 또는skills/(권장, 동일/name호출) - 네임스페이스: 하위 디렉터리·플러그인 prefix로 충돌 방지
상세
사용 가능 명령 발견
세션 시작 후 system init 메시지에서 slash_commands 배열을 읽습니다. 플러그인 명령은 plugin:command 형태일 수 있습니다.
명령 전송
일반 query({ prompt: "/compact" })처럼 문자열로 보냅니다. 인자가 있으면 /command arg1 arg2 형식을 유지합니다.
공통 내장
/compact
대화 히스토리를 요약·압축해 context window를 확보합니다. 장기 세션에서 토큰 비용과 한도를 관리할 때 사용합니다. compact 전후로 결과에 영향을 줄 수 있으므로 앱이 의존하는 상세 tool transcript는 별도 저장하세요.
/clear
대화 컨텍스트를 리셋합니다. 새 작업 단위를 같은 프로세스에서 시작할 때 유용하지만, 이전 턴 상태는 사라집니다.
커스텀 슬래시 명령 작성
파일 위치
- 프로젝트:
.claude/commands/또는.claude/skills/<name>/ - 사용자:
~/.claude/commands/또는~/.claude/skills/
파일 형식
마크다운 + YAML frontmatter(설명, 인자 힌트 등). 본문에 체크리스트·리뷰 템플릿·변경 파일 안내를 넣습니다. SDK는 settingSources에 해당 소스가 있을 때 로드합니다.
SDK에서 사용
for await (const message of query({
prompt: "/review-pr 123",
options: {
settingSources: ["project"],
allowedTools: ["Read", "Grep", "Glob", "Skill"]
}
})) {
// ...
}
고급·실무 패턴
- 인자 치환으로 PR 번호·경로 전달
- Changed Files / Detailed Changes / Review Checklist 섹션 템플릿
- 디렉터리 네임스페이스로 팀 명령 충돌 방지
- 팀 공유는 project skills, 개인 실험은 user skills
Context / Task
일부 명령·스킬은 context 보고나 task 목록과 연동됩니다. Task 도구 전환(v2.1.142+) 이후 UI 모니터링 코드는 TodoWrite와 Task*를 함께 고려하세요.
체크리스트
- init에서 명령 목록 확인
- 커스텀 파일이 settingSources 경로에 있다
- Skill vs legacy commands 정책을 통일했다
- compact/clear의 세션 부작용을 앱 상태에 반영했다
- 플러그인 prefix 명령을 테스트했다