반복 프로세스의 전역 스킬 전환 — commands에서 skills로
요약
세션 중 수행한 개선 작업을 케이스 스터디 리포트로 정리하는 반복 프로세스를 발견하고, 먼저 프로젝트 스코프의 커맨드(/project:case-study)로 프로토타입을 만들어 유효성을 검증했다. 검증 후 전역 사용 요구가 생겨, 공식 문서를 확인하고 ~/.claude/skills/로 승격하는 점진적 배포를 진행했다.
1. 현상 발견
콘텐츠 품질 개선 사례를 동료에게 공유하기 위해 케이스 스터디 리포트를 작성했다. 이 과정에서 “이슈 발견 → 원인 분석 → 개선 → 검증 → 문서화”라는 패턴이 앞으로도 반복될 것이라 판단했다. 매번 자연어로 리포트 구조를 설명하고 요청하는 것은 비효율적이었다.
“사전에 정의된 커맨드를 입력하면 알아서 리포팅해주는 흐름을 만들고 싶어.”
2. 원인 분석
반복 프로세스를 자동화할 수단이 없었다. 리포트 구조(요약 → 현상 → 원인 → 개선 → 검증 → 레슨런)는 매번 동일한데, 매 세션마다 이 구조를 처음부터 설명해야 했다.
Claude Code에서 이를 해결할 수 있는 공식 메커니즘이 두 가지 있었다:
.claude/commands/— 프롬프트 템플릿 파일.claude/skills/— 프롬프트 + frontmatter + 지원 파일
3. 개선 방향 논의
1단계: 프로젝트 commands로 프로토타입
프로젝트의 .claude/commands/case-study.md에 커맨드 파일을 생성. /project:case-study로 호출하여 실제 리포트 생성까지 검증했다. 리포트 구조, 작성 원칙, 톤이 의도대로 동작하는지 확인하는 단계.
2단계: 전역 사용 요구 → skills로 승격
프로토타입 검증 후 “이 도구를 모든 프로젝트에서 쓰고 싶다”는 요구가 생겼다. 이 시점에서 공식 문서를 확인한 결과:
“Custom commands have been merged into skills. Your existing
.claude/commands/files keep working. Skills add optional features.”
commands와 skills는 동일하게 동작하지만, skills는 추가 기능을 제공한다. 전역 배포에 필요한 기능을 비교한 결과:
| 기준 | 프로젝트 commands | 전역 skills |
|---|---|---|
| 스코프 | 프로젝트 한정 | ~/.claude/skills/ = 전역 |
| 자동 트리거 제어 | frontmatter 지원 | disable-model-invocation: true |
| 디렉토리 구조 | 단일 파일 | scripts/, references/ 등 확장 가능 |
프로젝트 commands에서 검증 → 전역 skills로 승격하는 점진적 배포로 결정.
4. 구현
~/.claude/skills/case-study/SKILL.md 생성. 핵심 설계:
disable-model-invocation: true— 유저가/case-study로 명시적 호출할 때만 실행. Claude가 자동 트리거하지 않음.- 케이스 단위 분리 — 한 세션에 여러 케이스가 있을 수 있으므로, 실행 시 모드 선택(최근/선택) → 케이스 확인 → 개별 리포팅 플로우.
- 숏컷 지원 —
/case-study 최근이면 확인 질문 없이 바로 최근 케이스 플로우. - 개별 파일 생성 — 복수 케이스 선택 시 각각 별도 MD 파일로 생성.
프로젝트의 .claude/commands/case-study.md는 삭제.
5. 검증
스킬 전환 후 실제 /case-study 실행:
- 모드 선택 질문 → 최근 케이스 확인 → 케이스 승인 → 리포트 생성
- 이전 혼합 리포트(여러 케이스가 하나에 섞임) 대비, 단일 케이스만 정확히 추출하여 리포팅
6. 레슨런
반복 패턴을 발견하면 즉시 자동화하라
“두 번째로 같은 일을 하고 있다”는 신호가 오면 자동화 타이밍이다. 리포트 구조가 동일한데 매번 설명하는 건 낭비다.
프로젝트 스코프에서 검증 → 전역으로 승격하는 흐름이 유효하다
처음부터 전역 skills로 만들 수도 있었지만, 프로젝트 commands로 먼저 프로토타입하고 유효성을 확인한 뒤 승격하는 흐름이 리스크가 낮았다. 검증되지 않은 도구를 바로 전역에 배포하면 모든 프로젝트에 영향을 주기 때문이다.
승격 시점에 공식 문서를 확인하라
프로토타입 단계에서는 빠르게 동작하는 것이 중요하고, 승격 단계에서 공식 권장 패턴을 확인하는 것이 자연스러운 타이밍이다. 이번 경우 commands와 skills의 관계, 전역 스코프 지원 여부를 승격 시점에 확인하여 올바른 구조로 전환할 수 있었다.