Unity AI 완전 정복 시리즈
1편 — Unity AI Assistant 완전 입문: Ask·Plan·Agent 모드 차이점과 언제 무엇을 쓸까
2편 — Unity MCP 완전 가이드: Claude Code·Codex·Gemini·Cursor를 Unity Editor와 연결하기
3편 — Unity MCP 커스텀 도구 만들기: McpTool Deep Dive와 4가지 등록 방식
4편 — Unity Skills 시스템으로 AI 워크플로우 자동화하기: SKILL.md 완전 가이드 (현재 글)
Appendix — Unity MCP 빌트인 도구 완전 레퍼런스 — 51개 도구 파라미터·활성화 가이드
5편 — Unity AI Assistant Project Overview 자동 생성 — AI가 내 프로젝트를 이해하게 만드는 방법
6편 — Unity AI Assistant × Profiler — 성능 병목을 자연어로 진단하는 완전 가이드
AI Assistant에게 같은 패턴의 작업을 반복해서 부탁하다 보면 설명이 점점 길어집니다. 예를 들어 “레벨에 적 스포너를 배치해줘”라는 단순한 요청 하나에도 — “빈 GameObject를 생성하고, EnemySpawner 컴포넌트를 붙이고, 적 프리팹 목록을 ScriptableObject에서 불러와 연결하고, NavMesh 위에 올라가 있는지 확인하고, Gizmo가 씬 뷰에 보이는지까지 점검해줘”처럼 매 단계를 풀어줘야 AI가 한 단계도 빼먹지 않고 따릅니다. 다음 대화에서 같은 작업을 또 부탁할 때면 같은 지시를 처음부터 다시 쓰게 됩니다.
Skills 시스템은 이 반복을 없애기 위해 설계됐습니다. SKILL.md(대소문자 구분) 파일 하나에 워크플로우 지침, 사용할 도구, 필요한 패키지 조건을 패키징해 두면 — Assistant가 Editor를 열 때마다 자동으로 발견하고, 필요한 순간에 꺼내 씁니다. 한 번 만들어두면 팀 전체가 .unitypackage로 공유할 수도 있습니다.
위의 적 스포너 워크플로우를 예로 들어보겠습니다. Assets/AI/Skills/place-enemy-spawner/SKILL.md로 5단계를 한 번 정의해두면 — 그다음부터는 "여기에 적 스포너 추가해줘" 한 줄이면 끝입니다. Assistant가 description 필드를 읽고 자동으로 이 스킬을 활성화한 뒤, 안에 적힌 5단계를 순서대로 실행합니다. EnemySpawner 컴포넌트를 빠뜨리거나 NavMesh 검증을 건너뛰는 일이 사라집니다. 새 멤버가 합류해도 같은 한 줄로 같은 결과를 얻기 때문에, 워크플로우가 사람을 옮겨가며 흐릿해질 일도 없습니다.
이 포스팅은 Unity 6.3(com.unity.ai.assistant 2.7) 기준으로 Skills 시스템의 구조와 실전 활용법을 정리합니다.
TL;DR
– Skills:SKILL.md(대소문자 구분) 파일로 정의하는 재사용 가능한 AI 워크플로우 모듈
– 자동 발견:Assets/또는 사용자 스킬 폴더에 놓으면 Editor 시작 시 자동 스캔
– Progressive Disclosure: YAML 메타데이터만 초기 로드 → 세부 파일은 필요 시만 로드
– Static Utility Function:public staticC# 메서드를 등록 없이 스킬에서 호출 가능
– 팀 공유:.unitypackage로 내보내면 임포트 즉시 자동 발견
목차
- Skills란 무엇인가
- 파일 배치 위치
- SKILL.md 파일 구조
- YAML 프론트매터
- 본문: 자연어 지침 작성법
- 지원 파일 구성
- Progressive Disclosure — 컨텍스트를 아끼는 전략
- Static Utility Function
- AgentTool과의 차이
- 유틸리티 클래스 설계 원칙
- Instance ID로 Unity 오브젝트 참조
- 실전 예시: red top hat 스킬
- 스킬 테스트 & 검증
- 팀 공유 (.unitypackage)
- 마무리
Skills란 무엇인가
Skills는 특정 워크플로우에 대한 지침과 메타데이터를 패키징해 Unity AI Assistant를 확장하는 모듈형 기능입니다. 단순히 프롬프트를 저장해두는 것과는 다릅니다. 스킬 파일 안에 “어떤 상황에서 이 스킬을 써야 하는지”, “어떤 단계를 어떤 순서로 수행해야 하는지”, “프로젝트의 어떤 C# 메서드를 호출해야 하는지” 등등 AI가 따라야 하는 ‘지침’ 혹은 ‘가이드라인’들이 담겨 있는 일종의 ‘작업 지침서’입니다.
공식 문서가 제시하는 Skills의 핵심 특성 4가지입니다.
한 가지 실무 팁: 공식 문서는 스킬 파일을 먼저 만들고 테스트하는 게 아니라, Assistant 채팅에서 워크플로우를 직접 시도해 잘 작동하는 것을 먼저 확인한 뒤 SKILL.md에 옮기는 방식을 권장합니다. 이미 동작이 검증된 지침을 파일로 굳히는 셈이라 훨씬 안정적입니다.
한 가지 중요한 점이 있습니다. Unity AI Assistant의 Skills는 Unity Agent(Ask·Plan·Agent 모드)에서만 로드됩니다. 직접 테스트해 본 결과, AI Gateway를 통해 사용하는 Claude Code·Codex 등 외부 에이전트는 각자의 하네스(harness) 안에서 독립적으로 동작하기 때문에 Unity의 SKILL.md를 읽지 않습니다. Claude Code라면 CLAUDE.md나 Claude Code 전용 Skills, Codex라면 AGENTS.md 등 에이전트별 지침 파일을 따로 작성해두어야 합니다.
파일 배치 위치
Assistant가 자동으로 스캔하는 위치는 두 곳입니다.
| 종류 | 경로 | 범위 |
|---|---|---|
| 프로젝트 스킬 | Assets/ 디렉터리 내 아무 곳 |
해당 프로젝트에서만 사용 |
| 사용자 스킬 | Windows: %APPDATA%\Unity\AIAssistantSkillsmacOS: ~/Library/Application Support/Unity/AIAssistantSkills |
같은 머신의 여러 프로젝트에서 공유 |
프로젝트 스킬은 Git으로 팀과 바로 공유할 수 있고, 사용자 스킬은 개인 작업 방식을 여러 프로젝트에 일괄 적용할 때 유용합니다. 사용자 스킬 폴더가 아직 없다면 Edit > Project Settings > AI > Skills > Create user skills folder 버튼으로 생성합니다.
스캔 시점은 Editor 시작 및 도메인 리로드 시입니다. 스킬을 추가하거나 수정한 경우 새 Assistant 대화를 시작해야 변경이 반영됩니다. 기존 대화에는 적용되지 않습니다.
SKILL.md 파일 구조
YAML 프론트매터
스킬 폴더의 권장 구성은 다음과 같습니다.
Assets/MySkills/
└─ my-test-skill/
├── SKILL.md
├── references/
│ ├── api-notes.md
│ └── common-patterns.md
└── resources/
├── scenario_A.md
└── template.cs
YAML 프론트매터의 전체 구조입니다.
--- name: my-test-skill description: Just a test skill. Activate it if we want to test skills. required_packages: com.unity.inputsystem: ">=1.8.0" com.unity.cinemachine: ">=3.0.0, <4.0.0" required_editor_version: ">=6000.3.13" enabled: true tools: - MyTools.Log ---
각 필드의 역할을 정리하면:
| 필드 | 필수 | 설명 |
|---|---|---|
name |
필수 | 스킬의 고유 이름. 폴더명과 일치시키는 것이 관례 |
description |
필수 | 스킬이 하는 일과 언제 활성화해야 하는지. AI가 활성화 판단에 사용 |
required_packages |
선택 | 지정된 패키지가 설치된 경우에만 스킬 활성화 |
required_editor_version |
선택 | 스킬 활성화 조건이 되는 Unity Editor 버전 범위 |
enabled |
선택 | false로 설정 시 비활성화. 기본값 true |
tools |
선택 | 스킬 활성화 중 Assistant가 사용할 수 있는 커스텀 도구 ID 목록 |
description 필드가 실질적으로 가장 중요합니다. AI는 이 설명을 읽고 현재 사용자 프롬프트에 어떤 스킬을 활성화할지 판단합니다. “이 스킬을 언제 쓰면 되는지”를 명확히 기술할수록 자동 활성화 정확도가 높아집니다. 그리고 >=, < 같은 연산자가 포함된 버전 문자열은 반드시 따옴표로 감싸야 YAML 파싱 오류를 피할 수 있습니다.
본문: 자연어 지침 작성법
SKILL.md의 본문은 고정 문법이 없는 자연어 지침입니다. 구어체 지시문이 그대로 작동합니다. 공식 문서 예시에 등장하는 표현들을 보면 감이 옵니다.
"에셋 생성을 호출하기 전에 반드시 대상 오브젝트를 확인합니다."— 순서 강제"3단계(검증)는 절대로 건너뛰지 않습니다."— 절대 금지 조건"정확히 하나의 경로만 따릅니다. 서로 다른 경로의 단계를 혼합하지 않습니다."— 분기 처리 규칙"스크린샷을 찍어 모자가 대상 오브젝트 위에 정확히 배치됐는지 시각적으로 확인합니다."— 검증 지시
단순 절차 나열을 넘어 “어떤 조건에서 어느 경로를 따르라”는 분기 로직, “반드시 거쳐야 할 검증 단계”, “절대로 하면 안 되는 것” 같은 제약 조건까지 자연어로 표현할 수 있습니다. SKILL.md 목표 크기는 가능하면 500줄 이하로 유지하고, 세부 내용은 지원 파일에 위임하는 것이 좋습니다.
지원 파일 구성
resources/와 references/는 관례명입니다. 다른 이름을 써도 되지만, SKILL.md 지침에서 정확한 상대 경로로 참조해야 합니다. 스킬이 활성화될 때 필요한 파일만 그 시점에 로드하므로, 초기 컨텍스트 크기에 영향을 주지 않습니다.
실제로 자주 쓰는 패턴 세 가지입니다.
- 코드 템플릿:
"'resources/snippet.cs' 템플릿을 사용해 MonoBehaviour를 생성합니다." - API 레퍼런스:
"사용 가능한 메서드와 파라미터는 'references/my-api.md'를 참조합니다." - 단계별 상세 지침:
"전체 배치 절차는 'resources/placement-steps.md'를 따릅니다."
Progressive Disclosure — 컨텍스트를 아끼는 전략
프로젝트에 스킬이 5개, 10개로 늘어난다고 상상해 보십시오. 모든 SKILL.md의 내용이 대화 시작 시 통째로 컨텍스트 창에 올라간다면 — AI가 쓸 수 있는 컨텍스트 공간이 빠르게 소모됩니다. Skills 시스템은 Progressive Disclosure(점진적 공개) 전략으로 이 문제를 해결합니다. 이미 Agent AI를 왕성하게 사용하시는 개발자분들이라면 익숙한 전략일 것 입니다.
초기 로드 단계에서는 YAML 프론트매터(name, description 등 메타데이터)만 컨텍스트 창에 올라옵니다. 스킬이 10개라도 초기에 로드되는 것은 각 스킬의 메타데이터뿐입니다. 스킬이 활성화되는 순간 본문 지침과 필요한 지원 파일이 그 시점에 로드됩니다.
이 구조 덕분에 스킬이 많아도 평상시 컨텍스트 소모는 최소화됩니다. 지원 파일(resources/, references/)은 스킬이 실제로 실행될 때만 로드됩니다.
Static Utility Function
AgentTool과의 차이
[AgentTool] 어트리뷰트와 Static Utility Function은 모두 Assistant가 C# 메서드를 활용하도록 해주지만, 호출 메커니즘이 다릅니다.
| 구분 | [AgentTool] |
Static Utility Function |
|---|---|---|
| 등록 | 어트리뷰트 필요 | 불필요 |
| 호출 방식 | AI가 직접 호출 | 스킬이 생성한 C# 코드로 호출 |
| 파라미터 전달 | AI가 판단해서 전달 | 스킬 지침에 명시된 대로 전달 |
| 적합한 경우 | 고수준 재사용 동작 | 프로젝트별 정밀 제어가 필요한 동작 |
[AgentTool]은 AI가 자유롭게 판단해 호출하는 반면, Static Utility Function은 스킬 지침이 “언제, 어떤 파라미터로 호출하라”를 명시합니다. 어트리뷰트 등록 없이 public static 메서드를 그대로 쓸 수 있어, 기존 에디터 유틸리티 클래스를 스킬에서 바로 재활용할 수 있다는 장점도 있습니다.
유틸리티 클래스 설계 원칙
스킬 지침은 완전한 메서드명(Namespace.ClassName.MethodName)으로 C# 코드를 생성해 호출합니다. 공식 문서가 제시하는 유틸리티 클래스 설계 원칙입니다.
| 요소 | 목적 |
|---|---|
| 완전한 클래스 경로 | 스킬 지침에서 메서드를 찾을 수 있도록 (예: Acme.Editor.HatUtils.PlaceHatOnTarget()) |
| 명확한 파라미터명과 타입 | AI가 올바른 값으로 메서드 호출 구성 |
| 명명 필드가 있는 반환 구조체 | AI가 값을 이름으로 읽고 다음 단계에 연결 |
Success 필드 |
AI가 성공/실패를 일관되게 판단 |
Message 필드 |
결과나 오류의 설명 제공 |
반환 타입을 string이나 bool 하나로 단순화하면 AI가 다음 단계에 필요한 값을 가져오기 어렵습니다. 아래처럼 명명 필드를 갖춘 구조체(또는 클래스)로 반환하는 것이 핵심입니다.
public static PlaceHatOutput PlaceHatOnTarget(int hatAssetInstanceId, int targetInstanceId, float yOffset = -0.1f)
{
var prefab = EditorUtility.EntityIdToObject(hatAssetInstanceId) as GameObject;
if (prefab == null)
return new PlaceHatOutput { Message = $"No prefab found for instance ID {hatAssetInstanceId}." };
var target = EditorUtility.EntityIdToObject(targetInstanceId) as GameObject;
if (target == null)
return new PlaceHatOutput { Message = $"No GameObject found for instance ID {targetInstanceId}." };
// 위치 지정 및 인스턴스화 ...
return new PlaceHatOutput {
Success = true,
Message = $"Hat placed on '{target.name}'.",
GameObjectInstanceId = hat.GetInstanceID(), // 다음 단계에 전달
PrefabPath = AssetDatabase.GetAssetPath(prefab)
};
}
[Serializable]
public class PlaceHatOutput
{
public bool Success;
public string Message;
public int GameObjectInstanceId;
public string PrefabPath;
}
씬 오브젝트를 수정하는 메서드라면 Undo 지원도 잊지 마십시오. 기존 오브젝트를 변경할 때는 Undo.RecordObject(), 새 컴포넌트를 추가할 때는 Undo.AddComponent<>()를 사용하면 사용자가 Ctrl+Z로 취소할 수 있습니다.
Instance ID로 Unity 오브젝트 참조
Static Utility Function은 GameObject, Component, UnityEngine.Object 파라미터를 직접 받을 수 없습니다. 대신 각 오브젝트에 메모리 내에서 부여된 정수 값인 instance ID(int)를 사용합니다.
| 타입 | 이름 관례 | 식별 대상 |
|---|---|---|
int |
gameObjectInstanceId |
씬의 특정 GameObject |
int |
componentInstanceId |
GameObject의 특정 Component |
int |
assetInstanceId |
프리팹, 텍스처 같은 프로젝트 에셋 |
int? |
위와 동일 | 선택적 오브젝트 ID |
int[] |
gameObjectInstanceIds |
배치 처리용 여러 오브젝트 |
이름 관례를 지키면 AI가 컨텍스트에서 오브젝트를 올바르게 식별합니다. 예를 들어 hatInstanceId와 targetInstanceId처럼 의미 있는 접두어를 붙이면 다단계 워크플로우에서 AI가 어떤 ID를 어느 메서드에 넘겨야 하는지 혼동하지 않습니다.
실전 예시: red top hat 스킬
Unity 공식 문서가 제공하는 완전한 예시입니다. AI로 3D 모자를 생성한 뒤 씬의 지정 오브젝트 위에 올려놓고, 스크린샷으로 결과를 검증하는 워크플로우를 하나의 스킬로 패키징합니다.
이 예시가 Skills 시스템을 이해하기 좋은 이유는 단순 절차 나열이 아닌, 분기 로직·필수 조건·검증 단계까지 자연어로 표현한 실전 패턴을 보여주기 때문입니다.
YAML 프론트매터:
--- name: create-red-tophat description: AI 생성으로 빨간 탑햇 3D 에셋을 만들고 대상 오브젝트 위에 배치합니다. 모자의 XZ 바운드를 대상에 맞추고 꼭대기에 위치시킵니다. 사용자가 탑햇 생성, 캐릭터에 모자 씌우기, 오브젝트 꾸미기를 요청할 때 사용합니다. ---
본문 지침 구조 (핵심 발췌):
이 스킬에서 사용하는 C# API 전체는 `resources/hatutils-api-reference.md`를 참조합니다. ## 필수 규칙 - 에셋 생성을 호출하기 전에 반드시 대상 오브젝트를 확인합니다. - 3단계(검증)는 절대로 건너뛰지 않습니다. ## 1. 대상 오브젝트 확인 ## 경로 A: 선택된 오브젝트 사용 사용자가 현재 선택 항목을 언급하고 오브젝트가 선택된 경우에만 따릅니다. 1. 선택 컨텍스트에서 선택된 오브젝트의 instance ID를 확인합니다. ## 경로 B: 이름으로 오브젝트 지정 사용자가 오브젝트 이름을 명시한 경우에만 따릅니다. 1. `TestProject.Scripts.HatUtils.FindHatPlacements("<이름>")` C# 스크립트를 호출합니다. 2. 첫 번째 일치 결과를 대상으로 사용하고 `GameObjectInstanceId`를 기록합니다. ## 경로 C: 대상 미지정 기존 대상이 지정되지 않은 경우에만 따릅니다. 1. `TestProject.Scripts.HatUtils.FindHatPlacements()` C# 스크립트를 호출합니다. 2. 결과 목록에서 대상을 선택하도록 사용자에게 요청합니다. 중요: 정확히 하나의 경로만 따릅니다. 서로 다른 경로의 단계를 혼합하지 않습니다. ## 2. 모자 생성 및 배치 1. 생성: 모델에 "반짝이는 빨간 탑햇을 생성합니다"라고 요청합니다. 에셋의 instance ID를 기록합니다. 2. 배치: `TestProject.Scripts.HatUtils.PlaceHatOnTarget(hatAssetInstanceId, targetInstanceId)`를 호출합니다. 3. 콜라이더 맞춤: `TestProject.Scripts.HatUtils.FitHatCollider(hatInstanceId)`를 호출합니다. ## 3. 검증 스크린샷을 찍어 모자가 대상 오브젝트 위에 정확히 배치됐는지 시각적으로 확인합니다. 배치가 잘못됐다면 조정 후 재검증합니다. 검증을 3회 이상 반복하지 않습니다 — 대신 사용자에게 입력을 요청합니다.
빨간 박스로 강조한 세 줄이 이 스킬의 핵심입니다. Section 3 검증 단계는 항상 거치고, 경로는 반드시 하나만 따르고, 검증을 3회 이상 반복하지 않는 것 — 이 규칙들이 AI의 자유 해석을 막고 예측 가능한 동작을 보장합니다.
실제 resources/hatutils-api-reference.md에는 FindHatPlacements(), PlaceHatOnTarget(), FitHatCollider() 각 메서드의 완전한 시그니처, 파라미터 표, 반환 구조체 필드가 담깁니다. 스킬 본문을 가볍게 유지하고 세부 API 정보는 지원 파일에 분리하는 패턴입니다.
스킬 테스트 & 검증
로드 확인: Edit > Project Settings > AI > Skills 페이지를 엽니다. 세 섹션으로 나뉩니다.
| 섹션 | 내용 |
|---|---|
| Project skills | 현재 프로젝트 Assets/에서 발견된 스킬 목록 |
| User skills | 사용자 스킬 폴더에 저장된 스킬 목록 |
| Skills with issues detected | 파싱 또는 유효성 검사 문제가 있는 스킬 |
스킬이 “Issues detected” 섹션에 들어갔다면 대부분 세 가지 중 하나입니다: 빈 스킬 파일, name 또는 description 필드 누락, --- 구분자 누락. Rescan 버튼으로 스캔을 다시 실행해 결과를 갱신합니다.
활성화 확인: Assistant 대화창의 Thoughts 섹션에서 Activate Skill과 함께 skill_name 파라미터가 표시되면 스킬이 정상 활성화된 것입니다. 활성화가 보이지 않는다면 description 필드의 설명이 충분히 구체적인지 먼저 점검하십시오.
스킬 필요 여부 판단: 공식 문서가 권장하는 방법입니다.
- 특정 도메인 및 시나리오 선택
- 스킬 없이 동일 프롬프트를 3~4회 실행
- 스킬 있이 동일 프롬프트를 3~4회 실행
- 결과 비교 — 측정 가능한 향상이 있을 때만 스킬 생성
워크플로우가 이미 스킬 없이 잘 작동한다면 스킬 추가가 오히려 불필요한 복잡도를 더할 수 있습니다.
팀 공유 (.unitypackage)
스킬 생성과 테스트가 완료됐다면 .unitypackage로 내보내 팀원이나 다른 프로젝트와 공유할 수 있습니다. Unity의 표준 에셋 패키지 워크플로우를 그대로 사용합니다.
패키지에 포함할 항목:
SKILL.md가 포함된 스킬 폴더 전체resources/,references/아래의 지원 파일- Static Utility Function이나 커스텀 도구(
[AgentTool])를 정의하는 에디터 스크립트
다른 사용자가 패키지를 임포트하면 Assistant가 포함된 스킬을 자동으로 발견합니다. 별도 설정 없이 Editor 시작 시 즉시 사용 가능한 상태가 됩니다.
마무리
Skills 시스템은 Unity AI Assistant를 팀 단위 워크플로우 도구로 바꿔주는 열쇠입니다. 매번 반복하던 컨텍스트 설명을 SKILL.md 파일로 고정하고, Static Utility Function으로 프로젝트 데이터에 정밀하게 접근하고, .unitypackage로 팀 전체에 배포하는 구조는 규모가 커질수록 가치를 발휘합니다.
한 가지 덧붙이고 싶은 것은 — 스킬부터 먼저 설계하려 하면 오히려 방향을 잃기 쉽습니다. 공식 문서가 권장하듯 Assistant 채팅에서 직접 시도해 동작을 검증한 뒤 파일로 굳히는 방식이 훨씬 빠릅니다. SKILL.md는 이미 검증된 워크플로우의 기록이지, 설계 문서가 아닙니다.
관련 포스팅
- Unity AI Assistant 완전 입문: Ask·Plan·Agent 모드 차이점과 언제 무엇을 쓸까
- Unity MCP 커스텀 도구 만들기: McpTool Deep Dive와 4가지 등록 방식
- Unity MCP 완전 가이드: Claude Code·Codex·Gemini·Cursor를 Unity Editor와 연결하기
← 이전 편: 3편 — Unity MCP 커스텀 도구 만들기: McpTool Deep Dive와 4가지 등록 방식
→ Appendix: Unity MCP 빌트인 도구 완전 레퍼런스 — 51개 도구 파라미터·활성화 가이드