이 문서는 OMC(oh-my-claudecode)의 built-in agents / skills / hooks를 개발자 관점에서 상세 정리한 레퍼런스입니다.
각 항목마다 무엇을 하는지(역할), 왜 만들어졌는지(존재 이유), 언제 쓰면 좋은지(권장 상황), **언제 피해야 하는지(비권장)**를 포함합니다.
- 역할: 실제로 수행하는 일
- 존재 이유: 왜 분리/도입했는지
- 권장 상황: 이 항목을 선택해야 할 대표 상황
- 비권장: 이 항목을 쓰면 오히려 비효율/오판 가능성이 큰 상황
OMC는 README와 REFERENCE의 설명 시점 차이로 일부 카운트가 다를 수 있습니다. 실행 동작 판단은 코드 기준(src/*, skills/*)이 우선입니다.
| Agent |
역할(무엇을 함) |
존재 이유(왜 만듦) |
권장 상황 |
비권장 |
explore |
코드/패턴/파일 빠른 탐색 |
저비용 고속 탐색 |
“어디에 뭐가 있지?” |
복잡 설계 판단 |
analyst |
요구사항 갭/숨은 제약 분석 |
구현 전 누락 방지 |
범위 불명확, 조건 충돌 |
코드 수정 작업 |
planner |
실행 계획 수립/순서화 |
즉흥 구현으로 인한 재작업 방지 |
다단계 기능 작업 착수 전 |
단순 1파일 수정 |
architect |
구조 분석/근본 원인 진단(읽기 전용) |
근거 없는 추측성 디버깅 방지 |
아키텍처/복잡 버그 |
직접 구현 |
debugger |
회귀/오류 원인 격리 |
장애 원인 좁히기 |
특정 오류 재발 원인 추적 |
제품 전략 논의 |
executor |
기능 구현/수정(최소 diff) |
계획을 실제 코드로 안전 반영 |
일반 구현 태스크 |
요구사항 정의/리뷰 |
deep-executor |
복잡한 자율 목표 수행 |
다중 파일·고난도 작업 처리 |
난해한 리팩토링/대규모 구현 |
사소한 수정 |
verifier |
완료 증거 검증/테스트 적정성 검사 |
"될 것 같다"식 완료 선언 차단 |
완료 직전 품질 검증 |
초기 설계 단계 |
| Agent |
역할(무엇을 함) |
존재 이유 |
권장 상황 |
비권장 |
style-reviewer |
포맷/네이밍/컨벤션 점검 |
스타일 이슈를 저비용 분리 처리 |
빠른 스타일 검토 |
로직 결함 찾기 |
quality-reviewer |
로직 결함/유지보수성 점검 |
동작은 되지만 나쁜 코드 탐지 |
안티패턴/복잡도 점검 |
단순 포맷 수정 |
api-reviewer |
API 계약/호환성 리뷰 |
인터페이스 파손 방지 |
공개 API 변경 전 |
내부 변수명 변경 |
security-reviewer |
취약점/신뢰 경계 점검 |
보안 결함 사전 차단 |
인증/인가/비밀정보 처리 |
UI 문구 수정 |
performance-reviewer |
성능 병목/복잡도 리뷰 |
늦은 성능 이슈 예방 |
고부하 경로/지연 민감 기능 |
초기 아이데이션 |
code-reviewer |
종합 코드 리뷰 |
리뷰 포인트 통합 판단 |
머지 전 최종 점검 |
단일 초점 검사 |
¶ 2.3 Domain Specialists
| Agent |
역할 |
존재 이유 |
권장 상황 |
비권장 |
dependency-expert |
외부 SDK/API/패키지 평가 |
의존성 선택 실패 방지 |
라이브러리 도입/교체 |
내부 코드 리팩토링 |
test-engineer |
테스트 전략/커버리지 설계 |
검증 공백 최소화 |
테스트 체계 구축 |
기능 구현 자체 |
quality-strategist |
릴리즈 품질 게이트 전략 |
출시 기준 명확화 |
배포 전 Go/No-Go 판단 |
단일 버그 수정 |
build-fixer |
빌드/컴파일/타입 오류 해결 |
빌드 파손 빠른 복구 |
CI 붕괴/타입 에러 폭발 |
대규모 아키텍처 변경 |
designer |
UI/UX 구현 및 구조 |
인터랙션/가독성 품질 확보 |
UI 컴포넌트/화면 작업 |
백엔드 알고리즘 |
writer |
문서/README/가이드 작성 |
변경사항 전달력 확보 |
릴리즈 노트/기술 문서 |
코드 성능 튜닝 |
qa-tester |
tmux 기반 상호작용 검증 |
정적 검증으로 못 잡는 런타임 확인 |
CLI/서비스 실제 동작 시험 |
단순 정적 분석 |
scientist |
데이터/통계 분석 |
수치 기반 의사결정 |
실험 결과 해석/추세 분석 |
기능 구현 |
git-master |
커밋/리베이스/히스토리 관리 |
변경 이력 품질 유지 |
커밋 전략/정리 |
비Git 로직 구현 |
| Agent |
역할 |
존재 이유 |
권장 상황 |
비권장 |
product-manager |
문제정의/JTBD/PRD |
만들 것보다 왜 만드는지 정렬 |
기능 우선순위/문제 정의 |
코드 핫픽스 |
ux-researcher |
사용성/접근성 관점 분석 |
사용자 관점 결함 조기 발견 |
UX 리스크 점검 |
빌드 에러 해결 |
information-architect |
정보 구조/내비게이션 설계 |
탐색성/명명 일관성 확보 |
메뉴/정보구조 개편 |
단순 텍스트 수정 |
product-analyst |
퍼널/지표/실험 설계 |
결과 측정 가능성 확보 |
KPI/이벤트 설계 |
코드 구현 |
critic |
계획/가정에 대한 비판적 검토 |
계획 허점 제거 |
구현 전 계획 검토 |
구현 실행 |
vision |
이미지/PDF/다이어그램 해석 |
시각 자료 기반 의사결정 보조 |
스크린샷/도식 분석 |
텍스트 코드 탐색 |
| Alias |
실제 매핑 |
권장 |
researcher |
document-specialist |
신규 사용 지양 |
tdd-guide |
test-engineer |
신규 사용 지양 |
아래는 skills/*/SKILL.md 기준입니다.
| Skill |
역할 |
존재 이유 |
권장 상황 |
비권장 |
autopilot |
아이디어→설계→구현→검증 자율 실행 |
엔드투엔드 자동화 |
"끝까지 알아서" |
작은 단일 수정 |
ultrawork |
고병렬 실행 엔진 |
처리량 극대화 |
독립 작업 다수 |
순차 의존 작업 |
ralph |
완료까지 지속 루프 |
조기 중단 방지 |
절대 미완료 금지 작업 |
탐색/브레인스토밍 |
team |
네이티브 팀 기반 협업 실행 |
팀 파이프라인 표준화 |
다역할 병렬 협업 |
아주 단순 작업 |
swarm |
공유 태스크풀 협업(호환 퍼사드) |
기존 swarm 흐름 유지 |
레거시 워크플로 유지 |
신규 표준 선택(Team 권장) |
ultrapilot |
병렬 autopilot(소유권 분할) |
속도 극대화 |
대규모 병렬 빌드 |
매우 작은 작업 |
pipeline |
단계형 체인 실행 |
순서·책임 분리 |
분석→수정→검증 체인 |
즉시 1회 수정 |
ultraqa |
테스트/검증/수정 반복 |
품질 게이트 자동 순환 |
QA 반복 루프 |
스펙 탐색 단계 |
| Skill |
역할 |
존재 이유 |
권장 상황 |
비권장 |
plan |
인터뷰 기반 실행 계획 |
요구사항 누락 방지 |
구현 전 합의 필요 |
이미 계획 확정 |
ralplan |
합의형 계획(alias) |
planner+architect+critic 조합 단축 |
고위험 계획 검토 |
사소한 작업 |
review |
계획 리뷰(alias) |
계획 품질 점검 단순화 |
기존 plan 검토 |
구현 자체 |
analyze |
심층 분석 |
근본 원인 파악 |
복잡 문제 분석 |
즉시 코딩 태스크 |
deepsearch |
코드베이스 광범위 탐색 |
누락 없는 탐색 |
큰 레포 패턴 파악 |
파일 위치 명확할 때 |
deepinit |
계층형 AGENTS 문서화 |
코드베이스 인덱싱 |
온보딩/리포 이해 |
단기 핫픽스 |
sciomc |
병렬 scientist 분석 |
다각도 연구 자동화 |
비교/가설 분석 |
단순 구현 |
| Skill |
역할 |
존재 이유 |
권장 상황 |
비권장 |
tdd |
테스트 우선 개발 강제 |
회귀/사양 누락 방지 |
품질 민감 기능 |
급한 임시 스크립트 |
build-fix |
빌드/타입 오류 최소 변경 복구 |
CI 복구 속도 |
깨진 빌드 수습 |
설계 개편 |
code-review |
종합 코드 리뷰 실행 |
배포 전 품질 체크 |
머지 전 리뷰 |
구현 시작 단계 |
security-review |
보안 리뷰 실행 |
취약점 사전 탐지 |
인증/비밀정보/권한 처리 |
스타일 정리 |
git-master |
Git 워크플로 전문 처리 |
커밋 품질 관리 |
커밋/리베이스/히스토리 정리 |
코드 구현 |
frontend-ui-ux |
UI/UX 품질 보강 |
밋밋한 UI/UX 방지 |
화면/컴포넌트 작업 |
서버 로직 전용 작업 |
| Skill |
역할 |
존재 이유 |
권장 상황 |
비권장 |
cancel |
활성 OMC 모드 안전 종료 |
상태 파일 정리 일관화 |
모드 종료/정리 필요 |
실행 중 계속 진행해야 할 때 |
omc-setup |
OMC 초기 설정 |
초기 진입 장벽 제거 |
설치 직후 |
이미 설정 완료 |
omc-doctor |
설치/설정 진단 |
환경 문제 자동 점검 |
동작 이상/업데이트 후 이슈 |
기능 구현 |
omc-help |
사용 가이드 제공 |
학습/복습 |
명령/모드 기억 안 날 때 |
자동 실행 엔진 대체 |
mcp-setup |
MCP 서버 구성 |
외부 모델/도구 연동 |
Codex/Gemini 등 연결 |
MCP 불필요한 로컬 작업 |
hud |
HUD 표시 구성 |
상태 가시성 강화 |
진행률/모드 모니터링 |
순수 구현 태스크 |
trace |
에이전트 플로우 추적 |
실행 경로 가시화 |
왜 이렇게 동작했는지 추적 |
단순 문서 작성 |
note |
notepad 메모 저장 |
컨텍스트 압축 내성 확보 |
재사용할 결정/학습 기록 |
일회성 잡담 |
learner |
세션에서 재사용 스킬 추출 |
반복 작업 자동화 |
반복 패턴 발견 시 |
단발성 작업 |
skill |
로컬 스킬 관리 |
스킬 수명주기 관리 |
list/add/remove/edit |
일반 코드 구현 |
release |
릴리즈 자동화 |
배포 절차 일관화 |
버전 릴리즈 |
개발 초기 탐색 |
project-session-manager |
worktree+tmux 세션 관리 |
격리된 작업공간 운영 |
다중 브랜치 병행 |
단일 브랜치 소규모 작업 |
psm |
project-session-manager 별칭 |
사용성 단축 |
동일 |
동일 |
writer-memory |
작성용 메모리 운영 |
긴 글/연속 문서 맥락 유지 |
문서 작업 연속성 |
코드 빌드 수정 |
external-context |
외부 문서/검색 컨텍스트 수집 |
내부 정보만으로 부족할 때 보강 |
외부 API/라이브러리 조사 |
내부 코드만으로 충분 |
learn-about-omc |
OMC 사용 패턴 학습 |
자기 사용 방식 개선 |
사용 습관 개선 |
즉시 구현 요구 |
configure-discord |
Discord 알림 설정 |
세션 결과/종료 알림 자동화 |
팀/개인 알림 |
알림 채널 미사용 |
configure-telegram |
Telegram 알림 설정 |
동일 |
동일 |
동일 |
| Skill |
역할 |
존재 이유 |
권장 상황 |
비권장 |
ralph-init |
ralph용 PRD 초기화 |
구조화된 지속 실행 보조 |
ralph 장기 작업 시작 전 |
단기 단발 작업 |
훅은 "자동 개입 레이어"입니다. 사용자가 직접 호출하기보다 라이프사이클 이벤트에서 동작합니다.
| Hook |
역할 |
존재 이유 |
권장 상황(유효한 경우) |
비권장/주의 |
autopilot |
autopilot 상태/흐름 관리 |
자율 실행 안정화 |
엔드투엔드 자동 실행 |
단일 짧은 수정 |
ultrawork |
병렬 실행 상태 관리 |
처리량 극대화 |
독립 태스크 다수 |
강한 순차 의존성 |
ralph |
지속 루프 상태 관리 |
미완료 종료 방지 |
완료 강제 과제 |
탐색성 대화 |
ultrapilot |
병렬 autopilot 조정 |
작업 분할/속도 |
대규모 병렬 작업 |
작은 패치 |
ultraqa |
QA 사이클 상태 |
품질 루프 보장 |
반복 검증 필요 |
사양 미확정 |
team-pipeline |
team 단계 상태/전이 |
Team 표준 런타임 |
team-plan~fix 파이프라인 |
Team 미사용 |
mode-registry |
모드 활성 상태 판별 |
충돌/중복 모드 방지 |
모든 모드 조정 공통 |
- |
persistent-mode |
Stop 시 지속 강제/우선순위 관리 |
조기 중단 방지 |
ralph/autopilot 중 실수 종료 방지 |
강제 종료 필요시 /cancel 없이 중단 시도 |
| Hook |
역할 |
존재 이유 |
권장 상황 |
비권장/주의 |
thinking-block-validator |
thinking 블록 검증 |
형식 불량 응답 방지 |
고난도 추론 세션 |
- |
empty-message-sanitizer |
빈 메시지 정리 |
파이프라인 오류 예방 |
입력/출력 이상 상황 |
- |
comment-checker |
코멘트 품질 점검 |
저품질/잡음 코멘트 억제 |
코드 코멘트 생성/수정 흐름 |
문서 전용 작업 |
permission-handler |
권한 요청 처리 |
위험 작업 제어 |
파일시스템/시스템 명령 전 |
무조건 자동 승인 기대 |
think-mode |
확장 추론 모드 감지 |
복잡 문제에 추론 증폭 |
난해한 분석/디버깅 |
사소한 작업에 과도한 비용 |
| Hook |
역할 |
존재 이유 |
권장 상황 |
비권장/주의 |
recovery |
편집/세션/컨텍스트 복구 |
실패 상태 자동 회복 |
툴 실패/컨텍스트 이슈 |
복구 루프 반복 시 원인 분석 없이 재시도 |
preemptive-compaction |
컨텍스트 임계 전 선제 대응 |
컨텍스트 초과 방지 |
장시간 세션 |
컨텍스트 상태 무시 |
pre-compact |
압축 직전 처리 |
상태 손실 최소화 |
compaction 직전 |
- |
project-memory |
프로젝트 환경 자동 요약 주입 |
매번 동일 탐색 반복 방지 |
세션 시작/프로젝트 전환 |
오래된 메모리 신뢰(재스캔 필요) |
beads-context |
taskTool별 지시 주입 |
task 도구 변형 대응 |
beads/beads-rust 사용 시 |
설정 불일치 상태 |
| Hook |
역할 |
존재 이유 |
권장 상황 |
비권장/주의 |
omc-orchestrator |
오케스트레이터 행동 강제(직접수정 억제 등) |
위임 중심 품질 유지 |
멀티에이전트 실행 |
단독 즉시수정 워크플로와 충돌 가능 |
todo-continuation |
미완료 todo 지속 유도 |
중도 종료 방지 |
다단계 작업 |
todo 갱신 안 하면 과잉 지속 가능 |
subagent-tracker |
서브에이전트 추적 |
진행 가시성/감사 |
병렬 서브에이전트 운용 |
- |
background-notification |
백그라운드 완료 알림 |
병렬 작업 관찰성 |
긴 백그라운드 태스크 |
- |
session-end |
세션 종료 처리 |
정리/후처리 일관화 |
세션 종료 |
- |
notepad |
compaction 내성 메모 유지 |
맥락 유지 |
장기/복합 세션 |
메모 과적재 |
learner |
대화에서 스킬 추출 |
반복 지식 재사용 |
반복 패턴 발견 시 |
근거 부족 패턴을 스킬화 |
| Hook |
역할 |
존재 이유 |
권장 상황 |
비권장/주의 |
keyword-detector |
매직 키워드 감지 |
명령성 입력 자동 모드 전환 |
autopilot, ralph, team 등 |
코드블록 내 키워드 오인식 주의(정규화 처리 존재) |
auto-slash-command |
slash command 자동 해석 |
명령 UX 개선 |
커맨드 중심 워크플로 |
커맨드 파일 미구성 상태 |
rules-injector |
규칙 파일 주입 |
정책 일관성 유지 |
팀 규칙 강제 적용 |
과도한 규칙 주입 |
directory-readme-injector |
디렉토리 README 주입 |
국소 컨텍스트 보강 |
모듈별 컨텍스트 필요 |
README 과다/노이즈 |
plugin-patterns |
플러그인 패턴 감지 |
사용 패턴 인식 |
플러그인 워크플로 |
- |
agent-usage-reminder |
적절한 에이전트 사용 유도 |
단일 모델 과용 방지 |
위임 누락 시 |
너무 잦은 리마인드 |
non-interactive-env |
CI/비대화 환경 대응 |
환경 차이 흡수 |
CI/자동화 실행 |
대화형 기대 |
setup |
초기화/유지보수 |
.omc 구조/환경 준비 |
설치 직후/유지보수 |
설정 생략 |
| 상황 |
우선 선택 |
| 아이디어만 있고 끝까지 자동 구현 |
autopilot |
| 절대 중간에 멈추면 안 됨 |
ralph |
| 속도가 최우선(병렬) |
ultrawork 또는 team |
| 단계형 협업/검증 루프 |
team |
| 순차 파이프라인 |
pipeline |
| 테스트/검증 반복 |
ultraqa |
| 빌드/타입 에러 폭발 |
build-fix + build-fixer |
| API/보안/성능 리뷰 |
api-reviewer / security-reviewer / performance-reviewer |
| 외부 라이브러리 판단 |
dependency-expert + external-context |
- 구현과 검증을 분리:
executor 후 verifier
- 계획 불명확하면 먼저
plan/analyst
- 장기 세션은
notepad/project-memory 기반으로 맥락 유지
- 모드 종료는 항상
/oh-my-claudecode:cancel 우선
| 구분 |
1차 신뢰 소스 |
| Agents |
src/agents/definitions.ts, agents/*.md |
| Skills |
skills/*/SKILL.md |
| Hooks |
src/hooks/*, src/hooks/index.ts |
| Plugin/MCP |
.claude-plugin/plugin.json, .mcp.json |
| 사용자 문서 |
docs/REFERENCE.md, README.md |