Claude v2.1.3 Update: Skill과 Command의 병합

 

Claude Code를 쓰다 보면 종종 이런 의문이 든다.

# .claude/commands/review.md
/review

# .claude/skills/review/SKILL.md
/review

 

commands/에 둔 것도 /로 부르고, skills/에 둔 것도 /로 부른다.

처음 보면 command와 skill이 별개의 시스템처럼 보인다. 한쪽은 사용자가 직접 부르는 것, 다른 쪽은 모델이 알아서 트리거하는 것. 하지만 v2.1.3부터 이 둘은 하나로 합쳐졌고, 지금은 같은 아티팩트의 두 가지 호출 경로에 가깝다.

 

.claude/commands/에 만든 기존 파일은 그대로 동작한다. 다만 Anthropic은 이제 .claude/skills/(SKILL.md) 방식을 권장하며, skill과 command가 같은 이름이면 skill이 우선한다.

---

1. command와 skill, 원래 뭐가 달랐나

병합 이전 Claude Code는 커스텀 워크플로를 확장하는 두 가지 경로가 있었다.

• Slash command: .claude/commands/*.md 단일 마크다운 파일. 사용자가 /command-name으로 명시적(deterministic) 호출
• Skill: .claude/skills/*/SKILL.md 디렉터리 구조. 모델이 맥락과 description을 보고 자동(non-deterministic) 트리거

둘 다 /로 호출되고 둘 다 커스텀 워크플로를 담는다는 점에서 역할이 겹쳤고, 이 overlap이 개발자들을 오래 헷갈리게 했다.

 

2. v2.1.3 병합 이후

핵심은 두 파일 위치가 같은 /command-name 인터페이스를 만든다는 것이다.

• .claude/commands/와 .claude/skills/ 파일 모두 /로 호출 가능
• 기존 commands/ 파일은 수정 없이 계속 동작
• 같은 이름이면 skill이 precedence를 가짐 (예: commands/review.md와 skills/review/SKILL.md가 둘 다 있으면 skill 버전 사용)

즉 "skill = 자동, command = 수동"이라는 구분 자체가 사라졌다. 이제 모든 skill은 /skill-name으로 명시적 호출도 되고, 동시에 모델이 맥락에 맞을 때 자동으로 발견하기도 한다. 하나의 SKILL.md가 deterministic 호출과 non-deterministic 트리거를 모두 갖는 이중 모드 구조다.

 

3. 호출 모드 제어

두 모드가 한 파일에 통합됐기 때문에, frontmatter로 동작을 끄고 켤 수 있다.

disable-model-invocation: true를 넣으면 모델이 자동으로 실행하지 못하고, 사용자가 직접 /로 트리거할 때만 발동한다. 과거 command의 동작(deterministic 전용)을 그대로 재현하는 셈이다.

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---
Deploy $ARGUMENTS to production:
1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

반대로 이 플래그를 빼면 자동 트리거가 살아난다. Anthropic이 auto-invocation을 포기한 게 아니라, 둘 다 유지하되 사용자가 모드를 선택하게 만든 것이다.

 

4. auto-invocation은 여전히 취약

병합이 "skill을 deterministic하게 만든다"는 신호로 읽힐 수 있지만, 문서를 보면 오히려 반대 신호가 있다.

skill description은 context budget(기본 모델 context window의 1%) 안에 로드된다. skill이 많아지면 description이 잘려나가고, 그러면 매칭에 필요한 키워드가 사라져 auto-invocation 정확도가 떨어진다. budget이 넘치면 가장 덜 쓰는 skill의 description부터 drop된다.

/doctor로 얼마나 잘리는지 확인하고, skillListingBudgetFraction(예: 0.02 = 2%)이나 SLASH_COMMAND_TOOL_CHAR_BUDGET로 budget을 늘릴 수 있다. 이런 관리 장치가 필요하다는 것 자체가, 자동 매칭이 여전히 신뢰를 깨질 수 있는 영역임을 보여준다.

 

5. 병합의 의미

이 변화는 deterministic에 대한 베팅이라기보단 mental model 단순화에 가깝다고 본다. changelog도 두 개념을 합쳐 mental model을 단순화하려는 의도라고 밝혔고, 개발자들이 둘의 차이로 혼란스러워하던 걸 정리한 성격이 크다.

다만 한 가지는 분명하다. 원래 deterministic 전용이던 command를 skill 쪽으로 흡수시키고 skill을 권장 방식으로 못 박았다는 건, Anthropic이 skill을 단순 자동 트리거 도구가 아니라 호출 방식과 무관한 범용 워크플로 단위로 격상시키려 한다는 뜻이다. deterministic 호출이 skill 안에 1급 시민으로 들어온 것이고, non-deterministic 트리거도 그대로 살아있다.

정리하면, deterministic이 이긴 게 아니라 deterministic이 skill 안으로 들어왔고, 두 모드가 한 파일에서 공존하게 됐다.

 

Reference

• Merged slash commands and skills, Claude Code Changelog v2.1.3
• Slash commands, Claude Code Docs
• Extend Claude with skills, Claude Code Docs