OMC (oh-my-claudecode) · 스킬과 슬래시 커맨드 (SKILL.md 워크플로우 + 얇은 디스패처)
OMC (oh-my-claudecode) · 스킬과 슬래시 커맨드 (SKILL.md 워크플로우 + 얇은 디스패처)
한 줄 요약
OMC는 재사용 작업 절차를 두꺼운 레시피(스킬) 와 얇은 포인터(커맨드) 로 나눠, 필요할 때만 절차서를 불러오는 “지연 로딩” 구조다. 이 설계를 알면 긴 절차서 수십 개를 매 세션 메모리에 띄우지 않고도 슬래시 한 줄로 호출해, 내 작업 절차를 토큰 낭비 없이 자산화할 수 있다.
그림
flowchart TD
A["세션 시작: commands/*.md<br/>메타데이터만 스캔"] --> B["커맨드 목록 등록<br/>(description='' → 토큰 절약)"]
B --> C["사용자 입력:<br/>/oh-my-claudecode:trace '인자'"]
C --> D["디스패처 본문 주입<br/>'SKILL.md 읽고 따르라 + $ARGUMENTS'"]
D --> E["모델이 Read로 두꺼운<br/>SKILL.md 로드 (지연 로딩)"]
E --> F["argument-hint 따라<br/>$ARGUMENTS 슬롯 파싱"]
F --> G["워크플로우 실행 → 결과 보고"]
쉽게 풀기
비유: 요리책과 포스트잇. 큰 요리책(스킬)에는 레시피 전문이 빼곡하지만, 요리 때마다 책 전체를 식탁에 펼치면 자리만 차지한다. 그래서 냉장고엔 포스트잇(커맨드)만 붙인다 — “오늘은 32쪽을 펴서 그대로 해.” 실제 요리를 시작할 때만 그 32쪽을 펼친다. OMC도 똑같다.
flowchart LR
subgraph 평소["세션 내내 떠 있음"]
P["포스트잇=커맨드<br/>(얇음, 설명 비움)"]
end
subgraph 호출시["호출 순간만 펼침"]
R["요리책 32쪽=SKILL.md<br/>(두꺼운 절차 전문)"]
end
P -- "/명령 입력 시 Read" --> R
- 스킬 = 두꺼운 절차서.
skills/<이름>/SKILL.md하나가 작업 절차 하나. 위쪽 frontmatter(이름·설명·인자 힌트) + 아래 본문(Usage → Architecture → Examples → Workflow). - 커맨드 = 얇은 길잡이.
commands/<이름>.md는 일부러 얇은 포인터. “짝 SKILL.md를 읽고 그대로 따르되 사용자 인자($ARGUMENTS)를 넘겨라”만 지시. - 왜 설명을 비우나(
description: ""). Claude Code는 세션 시작 시 모든 커맨드 설명을 통째로 읽는다. 여기 긴 절차를 적으면 호출하지도 않은 수십 개 설명이 매번 컨텍스트를 잡아먹으므로 빈 문자열로 비운다. - 지연 로딩. 두꺼운 SKILL.md 본문은 세션 시작 때 로드되지 않고, 사용자가 실제로 명령을 부른 순간 모델이 Read로 펼친다.
- 인자 전달. 슬래시 뒤 값은
$ARGUMENTS자리표시자로 전달되고,argument-hint(예:[N:agent-type] [ralph] <task>)가 어떤 슬롯에 끼울지 안내한다.
핵심 정리
스킬 frontmatter 주요 필드 (실측 40개 SKILL.md 집계)
| 필드 | 필수 여부 | 설명 |
|---|---|---|
name | 필수 40/40 | 식별자. /oh-my-claudecode:<name>로 호출 |
description | 필수 40/40 | 한 줄 설명. 스킬은 채우고 짝 커맨드는 비움 |
level | 권장 32/40 | 작업 무게/권한 단계 (team=4, trace=2) |
argument-hint | 선택 18/40 | 슬롯 형식 (<>=필수, []=선택) |
[!note]- 펼쳐보기: 전체 선택 필드 + level 분포
aliases(5/40): 대체 호출명. 실측값[psm],[learner],[cancel-ralph], 빈[]agent(1/40): 기본 위임 서브에이전트. trace는agent: tracertriggers(3/40): 자동 활성화 키워드 (AGENTS.md 템플릿 기준)model: 모델 티어 오버라이드 (sonnet등, AGENTS.md 템플릿)pipeline(3/40): 다단계 흐름. 있으면 “Skill Pipeline” 핸드오프 블록 자동 추가next-skill/next-skill-args/handoff(각 1·1·3): 명시적 다음 스킬·인자·인계 산출물handoff-policy/user-invocable/scope/role(각 2·1·1·1): 드문 제어 필드level실측 분포: 1×1, 2×10, 3×6, 4×12, 5×1, 7×2
커맨드(디스패처) 구성
| 구성 | 내용 |
|---|---|
description | 의도적 "" — 세션 시작 시 전부 로드되므로 토큰 절약 |
| 본문 | ”SKILL.md 읽어라 → 그대로 따르라 → $ARGUMENTS 전달” + 파일 못 찾을 때 폴백 탐색 |
[!warning] 비대칭 주의 — 모든 스킬에 짝 커맨드가 있는 건 아니다
commands/엔 28개 파일.commands/team.md는 없다 (team은/oh-my-claudecode:team로 직접 호출). 반면trace·skill은 디스패처가 있고,psm은project-session-manager의 별칭 디스패처다.
세 가지 커맨드 형태의 관계:
flowchart TD
T["/team"] -->|디스패처 없음| TS["skills/team/SKILL.md"]
TR["/trace"] -->|얇은 디스패처| TRS["skills/trace/SKILL.md"]
PSM["/psm"] -->|별칭 디스패처| PSMS["skills/project-session-manager/SKILL.md"]
[!note]- 펼쳐보기: 본문 작성 관례 + 자동 활성화 트리거 본문 관례 (필수 아님):
# <스킬>제목 →## Usage(호출 형식) →### Parameters→### Examples→## Architecture(ASCII) → 그 외 절차. AGENTS.md 권장 최소 골격:## Purpose / ## Workflow / ## Usage / ## Configuration.자동 활성화 트리거 (선택)
- 키워드 기반: “autopilot”, “ralph”, “ulw”, “ouroboros” 등 감지 시 자동 트리거
- hook 기반:
[MAGIC KEYWORD: ...]system-reminder로 자동 활성화
실제 예시
핵심만: 스킬(두꺼움) ↔ 커맨드(얇음) 의 짝 구조다. 전문은 접이식에 보존.
[!note]- 펼쳐보기: 예시 1 — 두꺼운 스킬 (team/SKILL.md, 1-43행)
--- name: team description: N coordinated agents on shared task list using Claude Code native teams argument-hint: "[N:agent-type] [ralph] <task description>" aliases: [] level: 4 --- # Team Skill ... ## Usage/oh-my-claudecode:team N:agent-type “task description” /oh-my-claudecode:team “task description” /oh-my-claudecode:team ralph “task description”
### Parameters - **N** - Number of teammate agents (1-20). Optional; defaults to auto-sizing... - **agent-type** - OMC agent to spawn for the `team-exec` stage... - **task** - High-level task to decompose and distribute among teammates - **ralph** - Optional modifier. Wraps the team pipeline in Ralph's persistence loop... ### Examples ```bash /team 5:executor "fix all TypeScript errors across the project" /team 3:debugger "fix build errors in src/" /team ralph "build a complete REST API for user management"
[!note]- 펼쳐보기: 예시 2 — 얇은 디스패처 (commands/trace.md 전문)
--- description: "" --- # OMC trace This compatibility command keeps `/oh-my-claudecode:trace` available without loading the full `trace` skill description in every Claude Code session. ## Dispatch 1. Read the full bundled skill instructions: `skills/trace/SKILL.md`. 2. Follow that SKILL.md exactly, treating the user's arguments as: ```text $ARGUMENTSIf the file is not readable from the current working directory, locate it under the active
CLAUDE_PLUGIN_ROOT/OMC_PLUGIN_ROOT, package root, or installed OMC plugin directory, then continue.
[!note]- 펼쳐보기: 예시 3 — 별칭 디스패처 (commands/psm.md 전문)
--- description: "" --- # OMC psm `/oh-my-claudecode:psm` is a compatibility alias for `/oh-my-claudecode:project-session-manager`. Read `skills/project-session-manager/SKILL.md`, follow its full instructions, and pass through the user's arguments: ```text $ARGUMENTS
[!note]- 펼쳐보기: 직접 만들 때 — 새 스킬 + 디스패처 템플릿
// skills/myskill/SKILL.md (두꺼운 절차) --- name: myskill description: One-line summary of what this skill does argument-hint: "[--flag] <required-target>" aliases: [] level: 2 --- # Myskill Skill (이 스킬이 무엇을 왜 하는지 한두 문단.) ## Usage/oh-my-claudecode:myskill
/oh-my-claudecode:myskill —flag ### Parameters - **required-target** - 처리 대상. - **--flag** - 선택 동작 변경자. ### Examples ```bash /myskill src/auth /myskill --flag "refactor the parser"Architecture
User: "/myskill src/auth" | v [ORCHESTRATOR] +-- step 1 ... +-- step 2 ...Workflow
- 입력 파싱 (argument-hint 슬롯대로).
- 작업 수행.
- 검증 후 결과 보고.
```markdown // commands/myskill.md (얇은 디스패처) --- description: "" --- # OMC myskill This compatibility command keeps `/oh-my-claudecode:myskill` available without loading the full `myskill` skill description in every Claude Code session. ## Dispatch 1. Read the full bundled skill instructions: `skills/myskill/SKILL.md`. 2. Follow that SKILL.md exactly, treating the user's arguments as: ```text $ARGUMENTSIf the file is not readable from the current working directory, locate it under the active
CLAUDE_PLUGIN_ROOT/OMC_PLUGIN_ROOT, package root, or installed OMC plugin directory, then continue.
만들 때 체크리스트
-
skills/<name>/SKILL.md생성, frontmattername·description필수. - 인자 받으면
argument-hint로 슬롯 명시(<>=필수,[]=선택). - 작업 무게에 맞는
level(가벼움 1~2, 무거운 오케스트레이션 4+). - 본문에 Usage/Parameters/Examples + 실제 절차(Workflow/Architecture).
- 토큰 절약 필요 시
commands/<name>.md디스패처 생성,description: "". - 디스패처 본문은 SKILL.md 읽기 지시 +
$ARGUMENTS+ 폴백 경로만. - 별칭은 SKILL.md
aliases:에 추가, 별도 호출명 원하면 별칭 디스패처(psm.md형)도. - 자동 활성화 필요 시
triggers:추가,docs/REFERENCE.md스킬 수 갱신. - 주의: 디스패처가 모든 스킬에 필수는 아님(team은 직접 호출).
요약 & 셀프체크
3줄 요약
- 스킬(
skills/<이름>/SKILL.md)은 두꺼운 절차서, 커맨드(commands/<이름>.md)는 그걸 가리키는 얇은 포인터다. - 커맨드 설명을
""로 비우는 건 세션 시작 시 모든 커맨드 설명이 로드되기 때문 — 두꺼운 절차는 호출 순간 Read로 지연 로딩한다. - 사용자 인자는
$ARGUMENTS로 SKILL.md에 전달되고,argument-hint가 슬롯 파싱을 안내한다.
스스로 답해 보기
- Q1. 커맨드
description을 일부러 비우는 이유는? (힌트: 세션 시작 로드 / 토큰) - Q2. SKILL.md 본문은 언제 컨텍스트에 들어오나 — 세션 시작 때인가, 호출 순간인가?
- Q3. team 스킬엔 왜
commands/team.md디스패처가 없어도 되는가?
연결
OMC_개요 · OMC_30_subagents · _분석축_루브릭
[!tip]- Codex 교차검증 보존
- 실측:
commands/28개,commands/team.md부재,level분포(1×1·2×10·3×6·4×12·5×1·7×2),aliases값 4종.- 근거 파일:
- /home/seunghyeong/harness-work/oh-my-claudecode/skills/team/SKILL.md (level:4, argument-hint, Usage/Parameters/Examples/Architecture)
- /home/seunghyeong/harness-work/oh-my-claudecode/skills/trace/SKILL.md (level:2, agent:tracer, 워크플로우 본문)
- /home/seunghyeong/harness-work/oh-my-claudecode/commands/trace.md (얇은 디스패처 전문, description:"")
- /home/seunghyeong/harness-work/oh-my-claudecode/commands/skill.md (디스패처)
- /home/seunghyeong/harness-work/oh-my-claudecode/commands/psm.md (별칭 디스패처)
- /home/seunghyeong/harness-work/oh-my-claudecode/skills/AGENTS.md (스킬 템플릿·생성 절차·자동 활성화 표)
- /home/seunghyeong/harness-work/oh-my-claudecode/skills/project-session-manager/SKILL.md (aliases:[psm] 실측)
- /home/seunghyeong/harness-work/oh-my-claudecode/scripts/build-skill-bridge.mjs (learner 브리지 — 본 컴포넌트와 무관 확인)