Besty0728/Unity-Skills

UnitySkills – Unity 에디터 자동화를 위한 AI 기반 REST API

개요 – UnitySkills는 Unity 에디터 내에서 로컬 HTTP 서버를 실행하는 Unity 2022.3+용 플러그인입니다. 이 서버는 805개의 '스킬'(작고 집중된 작업)을 REST 엔드포인트로 노출합니다. AI 기반 코딩 어시스턴트(Claude Code, Antigravity, Codex, Cursor, Kimi Code, OpenCode)는 이 엔드포인트를 호출하여 Unity 에셋, 씬, 프리팹, 셰이더, UI, 물리, 네트워크, XR 설정 및 기타 여러 에디터 작업을 생성, 수정 또는 삭제할 수 있습니다.

중요성 – 에디터 작업을 잘 정의된 API 뒤로 이동시킴으로써, UnitySkills는 대규모 언어 모델(LLM)이 실제 Unity 개발자처럼 행동할 수 있게 합니다. 단순히 코드 스니펫을 생성하는 대신 구체적인 명령을 내릴 수 있습니다. 이 프로젝트는 AI 기반 씬 편집의 가장 큰 우려 사항인 '실수로 인한 손상'을 해결하기 위해 안전 계층(드라이런 계획, 작업별 권한 모드, 감사 로그, 트랜잭션 롤백)을 추가했습니다.

핵심 기능

기능	설명
805개의 REST 스킬	54개 카테고리로 그룹화된 800개 이상의 즉시 사용 가능한 작업(예: YooAsset, Cinemachine, Netcode, UI Toolkit, XR, ShaderGraph 등). 각 스킬은 AI 어시스턴트가 스크립트로 작성하거나 호출할 수 있는 문서화된 작은 HTTP 호출입니다.
3단계 권한 시스템	승인(사용자가 토큰 부여), 자동(완전 자동 실행, 고위험 작업 차단), 바이패스(제한 없음). 모드는 Unity 패널에서 구성 가능하며 Claude Code의 권한 모델에 매핑됩니다.
드라이런 / 계획 모드	엔드포인트에 `?mode=dryRun` 또는 `?mode=plan`을 추가하여 프로젝트를 건드리지 않고 매개변수 검증 및 영향 평가를 받을 수 있습니다.
트랜잭션 배치 실행	`POST /skills/batch`는 일련의 스킬을 단일 트랜잭션으로 실행합니다. 페일패스트, 선택적 `continueOnError`, 단계 간 `$ref`, 실패 시 자동 롤백 및 변경 사항의 `?diff=1` 미리보기를 지원합니다.
감사 추적	모든 호출, 부여, 취소 및 차단된 요청은 `Library/UnitySkillsAudit.jsonl`에 기록됩니다. 로그는 패널 내에서 볼 수 있으며 삭제 작업도 기록됩니다.
롤백 세분성	5가지 스냅샷 유형이 도메인 리로드 후에도 유지됩니다. `workflow_undo_task`는 전체 프로젝트가 아닌 단일 작업을 롤백합니다.
다중 인스턴스 제어	서버는 사용 가능한 포트를 자동으로 검색하며 글로벌 레지스트리를 통해 여러 Unity 프로젝트를 동시에 관리할 수 있습니다.
장기 연결	구성 가능한 타임아웃(기본 15분) 및 도메인 리로드 후 자동 재연결 기능을 제공합니다.
환각 방지 가드레일	각 스킬에는 AI가 안전하지 않은 작업을 수행하지 못하도록 '금지' 목록과 라우팅 규칙이 포함되어 있습니다.

지원되는 AI 터미널(원클릭 설치)

터미널	상태
Antigravity	✅ (Codex와 `.agents/skills/` 공유)
Claude Code	✅
Codex	✅
Cursor	✅
Kimi Code	✅
OpenCode	✅

다른 도구를 사용하는 경우에도 수동으로 스킬을 설치할 수 있습니다('수동 스킬 설치' 섹션 참조).

빠른 시작(3단계)

Unity 패키지 추가 – Package Manager에서 Git URL을 추가합니다:
```
https://github.com/Besty0728/Unity-Skills.git?path=/SkillsForUnity
```
(또는 #beta나 태그가 지정된 버전을 사용하세요).
서버 시작 – Window → UnitySkills를 열거나 Alt + Shift + U를 누르고 서버 스위치를 켭니다. 서버는 도메인 리로드 후에도 자동으로 유지됩니다.
AI 스킬 세트 설치 – 동일한 패널에서 AI Config 탭으로 이동하여 터미널 아이콘을 선택하고 Install을 클릭합니다. 설치 프로그램은 unity-skills~/ 템플릿을 터미널의 스킬 디렉토리에 복사하고 필요한 agent_config.json을 생성하며 AI 도구에 스킬을 등록합니다.

안전 및 거버넌스

실행 전 미리보기 – ?mode=dryRun/?mode=plan을 사용하여 스킬이 변경할 내용을 확인합니다.
권한 게이트 – 고위험 작업(NeverInSemi로 표시됨)은 사용자가 허용 목록을 통해 명시적으로 허용하지 않는 한 차단됩니다.
구조화된 로깅 – 모든 활동은 JSONL로 저장되어 감사나 재실행이 용이합니다.
롤백 – 스냅샷은 콘텐츠 주소 지정 방식이므로 다른 작업을 잃지 않고 단일 작업이나 전체 배치를 되돌릴 수 있습니다.

대상 사용자

게임 개발자: 보일러플레이트 코드 작성 없이 LLM으로 레벨 레이아웃 프로토타이핑, UI 생성 또는 네트워크 설정을 수행하려는 분.
테크니컬 아티스트: AI 명령을 통해 에셋(YooAsset 번들, ShaderGraph 조정, ProBuilder 메시 등)을 일괄 처리하려는 분.
도구 제작자: Unity를 외부 자동화 파이프라인과 통합하기 위해 안정적이고 버전이 관리되는 API가 필요한 분.
연구원: 복잡한 에디터 환경에서 안전한 AI 보조 콘텐츠 제작을 탐구하는 분.

추가 정보

작동 모드 및 거버넌스 – docs/OPERATING_MODES.md
설정 가이드 – docs/SETUP_GUIDE.md (영어) / docs/SETUP_GUIDE_CN.md (중국어)
스킬 카탈로그 – README의 '805 Skills Category Overview' 섹션에 모든 스킬 그룹과 핵심 기능이 나열되어 있습니다.

요약

UnitySkills는 Unity 에디터를 AI 코딩 어시스턴트가 안전하게 호출할 수 있는 REST 기반 서비스로 변환합니다. 수백 개의 즉시 사용 가능한 작업, 세분화된 권한 시스템, 감사 로깅 및 트랜잭션 롤백을 제공하여 AI 기반 씬 편집을 실제 프로젝트에서 실용적으로 만듭니다.