Skills
opt-ui 설치, 환경 진단, 컴포넌트 생성, repo 동기화, release 워크플로우를 정리합니다.
reopt designUpdated
1. opt-ui Skills는 무엇인가
opt-ui-skills 는 @reopt-ai/opt-ui 의 runtime
패키지가 아니라, Claude Code / Codex 같은 에이전트가 opt-ui 설계 규칙과
소비자 프로젝트 도입 흐름, 컴포넌트 생성, repo 운영 작업을 일관되게 처리할
수 있도록 만든 action guide 모음입니다.
이 페이지는 opt-ui 전용 스킬만 다룹니다.
opt-datagrid 와 opt-editor 전용 스킬은 각각
/docs/opt-datagrid/skills, /docs/opt-editor/skills
에 분리되어 있습니다.
2. 설치
소비자 프로젝트용 통합 스킬은 /opt-ui-install 입니다. 설치,
업그레이드, Surface 추가, 환경 진단(26 checks)이 하나의 스킬에서 자동
분기됩니다. 컴포넌트/Surface 레퍼런스 조회는 설치 후
node_modules/@reopt-ai/opt-ui/dist/docs/ 를 직접 참조합니다.
curl -fsSL https://opt-ui.dev/install | bash -s opt-ui-install- Claude Code, Cursor, OpenCode, Codex 경로를 자동 감지합니다.
설치 후에는 관련 요청에서 자동 발견되거나
/opt-ui로 직접 호출할 수 있습니다.
3. 주요 Skills
| Skill | 실행 위치 | 용도 |
|---|---|---|
/opt-ui-install | 소비자 프로젝트 | opt-ui 설치 / 업그레이드 / Surface 추가 / 환경 진단 통합 (auto-detect → init/upgrade/surface 분기) |
/opt-editor-install | 소비자 프로젝트 | opt-editor 설치 / 업그레이드 / 환경 진단 통합 (auto-detect → init/upgrade 분기, 18 doctor checks) |
/opt-datagrid-install | 소비자 프로젝트 | opt-datagrid 설치 / 업그레이드 / grid 마이그레이션 통합 (glide-data-grid, ag-grid, react-data-grid, MUI DataGrid) |
/opt-chat-install | 소비자 프로젝트 | opt-chat 설치 / 업그레이드 (AI SDK, Conversation, 25 message parts) |
/opt-editor-migrate | 소비자 프로젝트 | Plate (platejs) → opt-editor 마이그레이션 |
/opt-ui-create | opt-ui repo | 새 Core / Shell / Surface 컴포넌트 scaffold 생성 |
/opt-ui-guide | opt-ui repo | 접근성, 토큰, 레이어 규칙 기준으로 guideline review |
/opt-ui-sync | opt-ui repo | 타겟 프로젝트를 읽어 분석→개선→검증을 한 번에 처리 |
/design-publish | opt-ui repo | opt-ui / opt-editor / opt-datagrid 통합 배포 preflight 와 release runbook |
/opt-e2e-loop | apps/web 또는 opt-ui repo | 컴포넌트 E2E 시나리오 생성, 실행, 개선 루프 자동화 |
4. 대표 워크플로우
소비자 프로젝트에 opt-ui 도입
consumer project: /opt-ui-install
→ auto-detect: init / upgrade / surface
→ Step 9: doctor validation (26 checks)
node_modules/@reopt-ai/opt-ui/dist/docs//opt-ui-install 은 소비자 프로젝트의 단일 진입점입니다. 설치
여부와 버전을 자동 감지하여 init(초기 설정), upgrade(버전 업그레이드),
surface(템플릿 추가) 모드를 분기합니다. 환경 진단(26 checks)은 모든 모드 완료
시 자동 실행됩니다.
새 opt-ui 컴포넌트 개발
/opt-ui-create로 scaffold를 만든다.구현 후
/opt-ui-guide로 guideline review를 수행한다.registry, demo, 문서 누락은 구현 직후 직접 점검하고 테스트로 확인한다.
소비자 프로젝트 UI 개선
opt-ui repo: /opt-ui-sync ../target-project
(Scan → Plan → Implement, 단일 커맨드)
opt-ui repo: /design-publish patch
consumer: /opt-ui-install/opt-ui-sync 는 타겟 프로젝트를 파일시스템으로 직접 읽어 페이지별
Surface 매칭, 갭 분석, 컴포넌트 개선까지 한 번에 처리합니다. 프로젝트 전환
없이 opt-ui repo에서만 작업합니다.
컴포넌트 E2E 루프
apps/web: /opt-e2e-loop
next-browser snapshot -> Playwright scenario -> improve/opt-e2e-loop 는 접근성 트리 확인, 전용 테스트 라우트 검증,
Playwright 테스트 생성과 개선 루프를 연결합니다. opt-ui 컴포넌트 문서와 데모를
빠르게 검증할 때 유용합니다.
사설 배포
직접 bun run release* 를 실행하는 대신
/design-publish 를 공식 경로로 사용합니다. publish-safe
manifest 변환, registry freshness, CLI 동반 배포 규칙이 모두 여기서
관리됩니다.
5. 설치와 동기화
스킬 정의는 packages/opt-ui-skills 에 있고, 배포용 tarball은
docs 앱의 public/skills 에 생성됩니다. 로컬 에이전트용 링크와
사이트 배포용 산출물은 별도로 갱신합니다.
# opt-ui repo root
bun run skills:build
bun run skills:syncskills:build는 docs 사이트에서 내려받는 tar.gz 스킬 파일을 생성합니다.변경 후
.claude/skills와.codex/skills링크를 같이 갱신합니다.
6. 어떤 repo에서 실행해야 하나
Skills는 실행 위치가 중요합니다. /opt-ui-create,
/opt-ui-guide, /opt-ui-sync,
/opt-datagrid-sync, /opt-datagrid-backend,
/design-publish, /opt-e2e-loop 는 opt-ui
monorepo에서 실행해야 하고, /opt-ui-install,
/opt-editor-install, /opt-datagrid-install,
/opt-chat-install, /opt-editor-migrate 는 실제
소비자 프로젝트에서 실행해야 합니다.
읽기 전용 레퍼런스는 설치된 패키지의 dist/docs 경로를 직접 보면
됩니다. 반면 action skill은 실행 위치가 다르면 경로 해석, reports 저장 위치,
registry 참조 방식이 달라집니다. 패키지별 경계는 문서도 동일하게
분리했습니다.
7. 언제 Skills를 먼저 봐야 하나
- 신규 소비자 프로젝트에 opt-ui를 설치하고 연결하려는 경우
- 어떤 Core/Shell/Surface를 골라야 할지 애매한 경우
- Surface copy workflow와 로컬 수정 전략이 필요한 경우
- 새 컴포넌트나 Surface를 추가하려는 경우
- 리포트 기반으로 UI 개선 루프를 반복 수행하는 경우
- 컴포넌트 문서/데모의 E2E 시나리오를 자동화하려는 경우
- private release 절차를 안전하게 실행해야 하는 경우
반대로 단순한 usage 예제, props, import 정보만 필요하면 component docs와 Surface registry 문서만 봐도 충분합니다. Skills 문서는 “무엇을 렌더링하나” 보다 “어떻게 운영 작업을 수행하나”에 더 가깝습니다.