appsok/agent-ops/skills/common/create-agent-ui/SKILL.md

name	version	description
create-agent-ui	1.1.0	프로젝트 코드 또는 문서 근거를 분석해 agent-ui 기본 스캐폴드와 동기화된 UI 정의 초안을 생성하는 스킬

create-agent-ui

목적

프로젝트의 기존 UI 코드나 컨셉 문서를 근거로 agent-ui/ 기본 구조와 UI 정의 초안을 생성한다. ops/dev UI를 1차 대상으로 하며, 구현 근거와 문서 근거를 구분해 AI와 사람이 UI 의도를 동기화할 수 있게 만든다.

언제 호출할지

• 사용자가 agent-ui 생성, UI 스캐폴드 생성, 화면 정의 구조 생성을 요청할 때
• 프로젝트에 agent-ui/가 없고 기존 코드 또는 문서에서 UI 정의 문맥을 추출할 때
• UI 코드가 있으면 구현 상태와 동기화된 view/component/frame 초안이 필요할 때
• UI 코드가 아직 부족하면 README, roadmap, SDD, docs 같은 컨셉 문서 기반 최소 view tree가 필요할 때

입력

• surface-type: ops-dev 또는 product. 기본값은 ops-dev (선택)
• source-mode: auto, code-first, concept-first, blank 중 하나. 기본값은 auto (선택)
• views: 초기 생성할 view id 목록, kebab-case (선택)
• components: 초기 생성할 component id 목록, kebab-case 또는 path id (선택)

먼저 확인할 것

• agent-ops/rules/common/rules-agent-ui.md를 읽는다.
• 생성 대상 agent-ui/ 존재 여부를 확인한다.
• 기존 agent-ui/가 있으면 덮어쓰지 않고 update-agent-ui 또는 validate-agent-ui 대상인지 보고한다.
• 템플릿 경로 agent-ops/skills/common/_templates/agent-ui/ 하위 파일을 확인한다.
• source-mode=auto이면 UI 코드 후보와 컨셉 문서 후보를 모두 가볍게 확인한다.

실행 절차

1. 생성 대상 확정

   • 생성 루트는 agent-ui/로 고정한다.
   • surface-type이 없으면 ops-dev로 둔다.
   • source-mode가 없으면 auto로 둔다.
   • product UI가 명시되어도 기본 구조는 유지하고 product 전용 레이어는 요청된 경우에만 추가 후보로 보고한다.

2. 근거 수집

   • code-first 또는 auto에서는 UI 구현 후보를 찾는다.
     • 예: apps/**/lib/**, packages/**/lib/**, src/**, app/**, pages/**, screens/**, views/**, components/**, widgets/**, route/navigation/shell 파일
     • 프로젝트 규칙에 dedicated UI domain rule이 있으면 먼저 따른다.
     • 코드가 많으면 전체 정독하지 말고 route, shell, page/view, widget/component 이름 중심으로 후보를 좁힌다.
   • concept-first 또는 auto에서는 컨셉 문서 후보를 찾는다.
     • 예: README.md, docs/**, agent-roadmap/current.md, 활성 Phase/Milestone, 승인된 SDD, agent-ops/rules/project/rules.md
     • roadmap 문서는 agent-ops/rules/common/rules-roadmap.md의 loading/archive 접근 규칙을 따른다.
     • archive 문서는 사용자가 과거 근거를 명시하지 않는 한 읽지 않는다.
   • 근거가 없거나 사용자가 빈 구조를 요청하면 blank로 처리한다.

3. source-mode 결정

   • auto에서 route, shell, page/view, widget/component 후보 중 하나 이상이 실제 파일 경로로 확인되면 code-first로 생성한다.
   • UI 구현 후보가 부족하고 컨셉 문서 후보가 있으면 concept-first로 생성한다.
   • 코드와 문서 근거가 모두 부족하면 blank로 생성하고 부족한 근거를 결과에 보고한다.
   • 명시된 views 또는 components는 선택된 mode와 함께 생성 후보로 반영한다.

4. 기본 구조 생성

   • 다음 활성 문서를 템플릿 기준으로 만든다.
     • agent-ui/README.md
     • agent-ui/definition/index.md
     • agent-ui/definition/views/index.md
     • agent-ui/definition/components/index.md
     • agent-ui/frame/index.md
   • 생성하는 활성 Markdown 문서에는 rules-agent-ui.md의 Frontmatter Schema를 적용한다.
   • 다음 archive/user-review 디렉터리가 빈 상태로 필요하면 .gitkeep을 둘 수 있다.
     • agent-ui/definition/archive/views/
     • agent-ui/definition/archive/components/
     • agent-ui/archive/user-review/
   • USER_REVIEW.md는 사용자 판단 항목이 있을 때만 만든다.

5. 초기 view 생성

   • code-first에서는 구현 코드에서 확인된 route/page/view/shell 단위를 view 후보로 만든다.
   • concept-first에서는 문서에서 확인된 운영 업무, 화면, 콘솔 영역을 view 후보로 만든다.
   • blank에서는 명시 views가 있을 때만 view 후보를 만든다.
   • 각 view 후보마다 다음 문서를 만든다.
     • agent-ui/definition/views/<view-id>/index.md
   • view 문서에는 Source Evidence와 Status를 반드시 남긴다.
     • 코드 근거가 있으면 status: implemented
     • 문서 근거만 있으면 status: planned
     • 명시 입력만 있고 근거가 부족하면 status: assumed
     • 판단 불가하면 status: unknown과 USER_REVIEW 항목을 남긴다.
   • 실제 근거 파일이 없으면 frontmatter source_evidence[].path는 null로 둔다.
   • visual source가 없는 초기 view 문서의 frontmatter frame은 null로 둔다.
   • frontmatter의 status, source_evidence, regions와 본문 Status, Source Evidence, Regions가 같은 기준을 말하게 작성한다.
   • .excalidraw 파일은 사용자가 요청했을 때만 빈 visual source로 만들거나 생성 후보로 보고한다.
   • .excalidraw 또는 다른 visual source를 만들거나 연결할 때만 agent-ui/frame/views/<view-id>/index.md를 만든다.
   • .excalidraw를 만들거나 연결하면 주요 박스 text label 또는 customData.region_id에 region id를 넣는다.
   • view id는 kebab-case가 아니면 정규화 후보를 보고하고 사용자 확인이 필요하면 생성하지 않는다.

6. 초기 component 생성

   • code-first에서는 반복 widget/component/table/filter/log/status/action 단위를 component 후보로 만든다.
   • concept-first에서는 문서상 반복 패턴이 분명한 data table, status badge, filter bar, log viewer 같은 구성요소만 component 후보로 만든다.
   • blank에서는 명시 components가 있을 때만 component 후보를 만든다.
   • 각 component 후보마다 agent-ui/definition/components/<component-id>/index.md를 만든다.
   • component 문서에는 Source Evidence와 Status를 반드시 남긴다.
   • 실제 근거 파일이 없으면 frontmatter source_evidence[].path는 null로 둔다.
   • component id가 path id이면 하위 디렉터리 구조로 만든다.
   • view에서 참조하지 않는 component도 사용자가 명시했으면 생성할 수 있다.

7. 불확실성 분리

   • 코드와 문서가 충돌하면 임의로 통합하지 않고 agent-ui/USER_REVIEW.md에 남긴다.
   • view 경계, component 신규 생성 여부, page/drawer/split 같은 UX 판단은 USER_REVIEW로 남긴다.
   • 문서 근거만 있는 계획 항목을 구현 완료처럼 쓰지 않는다.

8. 결과 보고

   • 선택된 source-mode
   • 읽은 근거 파일과 생성에 사용한 evidence
   • 생성한 파일
   • 적용한 frontmatter schema
   • 생성한 view/component의 status
   • USER_REVIEW 생성 여부
   • product UI 확장 후보
   • 후속 권장 작업

실행 결과 검증

• agent-ui/README.md가 생성되었는가
• definition/index.md, definition/views/index.md, definition/components/index.md, frame/index.md가 생성되었는가
• 활성 Markdown 문서가 ui_doc_type frontmatter를 포함하는가
• view/component는 folder-first + index.md 구조를 사용하는가
• 생성한 view/component에 Source Evidence와 Status가 있는가
• 구현 근거 없는 항목을 implemented로 표시하지 않았는가
• visual source가 없는 view에 빈 frame/views/<view-id>/index.md를 만들지 않았는가
• 코드/문서 충돌이나 UI 의도 판단이 필요한 항목이 USER_REVIEW에 남았는가
• 같은 레벨에 <name>.md와 <name>/가 함께 생기지 않았는가
• archive 본문 파일을 불필요하게 생성하지 않았는가
• 검증 실패 시: 누락된 scaffold만 보완하고 기존 문서를 덮어쓰지 않는다.

출력 형식

## 생성 완료

- 루트: agent-ui/
- source-mode: <code-first|concept-first|blank>
- evidence: <주요 근거 파일 목록>
- 생성 파일: <목록>
- frontmatter schema: <적용/부분 적용/없음>
- views: <view-id=status 목록 또는 없음>
- components: <component-id=status 목록 또는 없음>
- USER_REVIEW: <생성/없음>
- 확인 필요: <항목 또는 없음>
- 후속 권장: validate-agent-ui 실행

금지 사항

• 기존 agent-ui/ 문서를 덮어쓰지 않는다.
• .excalidraw 파일을 현재 UI source of truth로 만들지 않는다.
• 코드나 문서 근거 없이 화면 의도를 확정하지 않는다.
• 문서 근거만 있는 항목을 구현 완료 상태로 쓰지 않는다.
• product UI 전용 레이어를 요청 없이 추가하지 않는다.
• definition/archive/**나 archive/user-review/**에 현재 기준 문서를 만들지 않는다.