Besty0728/Unity-Skills

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

무엇인가요 – UnitySkills는 Unity 2022.3 이상에서 작동하는 플러그인으로, 로컬 HTTP 서버를 실행하여 스킬(사전에 작성된 에디터 명령어)을 REST 엔드포인트로 노출합니다. 외부 AI 어시스턴트(Claude Code, Antigravity, Codex, Cursor, OpenCode 등)는 이 엔드포인트를 호출하여 사용자의 대신 장면, 프리팹, 자산 및 .meta 파일을 생성, 수정, 삭제할 수 있습니다.

핵심 개념

계층	기능
스킬 카탈로그	25개의 설계 가이드 모듈(UI, Netcode, XR, ShaderGraph 등)로 그룹화된 784개의 "스킬" 모듈. 각 스킬은 필요한 매개변수, 위험 수준, 장면이나 자산을 변경하는지 여부를 알고 있는 작고 타입이 지정된 작업입니다.
REST 인터페이스	`POST /skill/{name}`(단일) 또는 `POST /skills/batch`(트랜잭션). `?mode=dryRun` 또는 `?mode=plan` 쿼리 매개변수를 사용하면 프로젝트에 영향을 주지 않고 검증 오류와 영향 예측을 미리 확인할 수 있습니다.
권한 시스템	세 가지 모드 – 승인, 자동, 바이패스 – Claude Code의 권한 모델을 모방합니다. 각 스킬의 메타데이터(`RiskLevel`, `MayEnterPlayMode` 등)가 실행을 제어합니다. 고위험 호출에 대해 선택적으로 `ConfirmationToken`을 추가하여 사용자 승인 단계를 두 번째로 추가할 수 있습니다.
감사 및 롤백	모든 요청, 권한 부여, 취소, 차단된 호출은 `Library/UnitySkillsAudit.jsonl`에 추가됩니다(1 MiB마다 회전). 각 파일 변경의 스냅샷은 `Library/UnitySkills/` 아래 콘텐츠 주소 방식으로 저장되어, 도메인 재로드 후에도 타입 지정된 `workflow_undo_task`를 사용해 단일 작업만 롤백할 수 있습니다.
배치 트랜잭션	`POST /skills/batch`는 fail-fast 또는 continueOnError를 지원하며, 이전 단계의 출력을 `$ref`로 재사용할 수 있고, 실패 시 자동으로 롤백됩니다. `?diff=1` 플래그를 사용하면 전체 배치의 파일 시스템 차이를 반환합니다.
장기 연결	설정 가능한 타임아웃(기본값 15분), 도메인 재로드 후 자동 재연결, Unity가 스크립트를 재컴파일하는 동안 리트라이 힌트 제공.
환각 방지 가드레일	각 스킬은 "DO NOT" 목록과 라우팅 규칙을 포함하여, 알 수 없는 명령어나 잘못된 매개변수 호출을 에디터에 도달하기 전에 거부합니다.

작동 방식 (개요)

Unity 패키지 설치 – Unity 패키지 매니저를 통해 Git URL(안정판, 베타판, 태그된 버전)로 패키지를 설치합니다. 패키지는 Window → UnitySkills 패널과 Library/UnitySkills 아래의 서버 코드를 추가합니다.
서버 시작 – 패널에서 시작하거나 토글 단축키 Alt+Shift+U를 사용합니다. 도메인 재로드 후 자동으로 재시작됩니다.
AI 터미널 구성 – 패널의 AI Config 탭에서 Claude Code, Antigravity, Codex, Cursor, OpenCode를 선택하고 Install을 클릭합니다. 설치 프로그램은 템플릿 스킬 번들(unity-skills~/)을 터미널의 스킬 디렉터리에 복사하고, AI 에이전트를 식별하는 agent_config.json을 생성합니다.
AI가 스킬 호출 – 예: POST /skill/createGameObject?mode=plan에 JSON 본문 { "name": "Enemy", "position": [0,1,0] }을 전송합니다. 서버는 매개변수를 검증하고, 계획(또는 오류)을 반환하며, 사용자가 승인하면 Unity 에디터에서 작업을 실행합니다.
감사 및 롤백 – 모든 호출은 로그에 기록됩니다. 사용자는 패널에서 로그를 열람, 필터링, 삭제할 수 있습니다(삭제 자체도 로그에 기록됨). 실수 발생 시, 스냅샷 ID를 POST /skill/workflow_undo_task에 전달하여 해당 변경만 되돌릴 수 있습니다.

빠른 시작 체크리스트

단계	명령어 / UI 작업
1️⃣ 설치	Unity 패키지 매니저 → Git URL에서 패키지 추가 → `https://github.com/Besty0728/Unity-Skills.git?path=/SkillsForUnity` (또는 `#beta`, `#v1.6.0` 등)
2️⃣ 서버 시작	`Window → UnitySkills` → Server 를 켜기 (또는 `Alt+Shift+U`)
3️⃣ AI 연결	동일한 패널에서 AI Config 로 이동, 터미널 선택 후 Install 클릭
4️⃣ 스킬 테스트	`curl -X POST http://localhost:5000/skill/createGameObject?mode=plan -d '{"name":"Test","position":[0,0,0]}'`
5️⃣ 검토	패널의 기어 아이콘에서 Audit Log 열어 요청과 결과 확인

누구에게 유용할까

게임 개발자 – AI 보조 레벨 설계, 일괄 자산 조정, 빠른 프로토타이핑을 원하지만 에디터를 수동으로 클릭하고 싶지 않은 사람.
CI/CD 파이프라인 – 결정론적이고 스크립트 가능한 Unity 편집이 필요하며(예: 자동 프리팹 생성, 패키지 버전 업데이트), 완전한 감사 로그를 유지하고 싶은 사람.
도구 개발자 – Unity 프로젝트를 조작하는 맞춤형 AI 에이전트를 만들고 싶은 사람. REST 계약 덕분에 언어에 구애받지 않는 통합이 가능.
대규모 팀 – AI 생성 변경에 대해 세밀한 권한 제어(승인 모드)와 롤백 보안이 필요한 사람.

제한 사항 및 주의사항 (문서 참조)

서버는 로컬 전용입니다. 공개적으로 노출하려면 추가 보안 계층이 필요합니다.
도메인 재로드 또는 스크립트 재컴파일 중 REST 엔드포인트는 일시적으로 사용 불가능합니다(클라이언트는 짧은 대기 후 재시도해야 함).
공식 지원은 Unity 2022.3 이상만입니다. 일부 2021 코드는 남아 있지만 새로운 기능은 제공되지 않습니다.
새 설치와 업그레이드에서는 권한 기본값이 다릅니다(새 설치는 자동, 업그레이드는 바이패스로 이전 동작 유지).
AI는 스킬 카탈로그를 이해해야 합니다. 지원되지 않는 터미널은 사용자 정의 설치가 필요합니다.

더 많은 정보 찾기

문서 – docs/SETUP_GUIDE.md (영어) 및 docs/SETUP_GUIDE_CN.md (중국어)에서 완전한 설치 절차.
릴리스 자산 – 모든 버전 패키지는 GitHub Releases 페이지에 있습니다.
DeepWiki 문서 – 자동 생성 문서는 https://deepwiki.com/Besty0728/Unity-Skills 에서 확인 가능.
라이선스 – MIT (파일 LICENSE 참조).

결론 – UnitySkills는 AI 에이전트가 안전하게 호출할 수 있는, 내장된 위험 제어, 드라이런 미리보기, 작업 단위 롤백을 갖춘 신뢰할 수 있고 감사 가능한 REST 기반 자동화 인터페이스로 Unity 에디터를 전환합니다. AI 보조 게임 개발을 진정으로 목표로 하는 진정한 소프트웨어 프로젝트입니다.