[노트] Unreal Engine Skills for Claude Code

언제부터 있었나#

• 개발은 5.8 프리뷰가 나오기 전부터 Epic 내부에서 시작한 것으로 보인다. 커밋 히스토리가 GitHub 레포 생성 시점보다 몇 달 앞선다.
• GitHub에는 5.8.0 정식 릴리스와 비슷한 시기에 공개됐고 그 직후부터 외부 사용자의 포크와 PR이 보인다.
• 엔진의 Unreal MCP와 함께 준비해 정식 출시에 맞춰 내놓은 동반 플러그인으로 볼 수 있다.

그런데도 새로 나온 것처럼 보였던 건 10월 19일에 관심이 갑자기 몰렸기 때문이다. 하루 사이에 스타가 수백 개 붙었는데, Threads와 X에서 이 레포를 소개하는 글이 바이럴된 영향으로 보인다. 나도 Threads에서 보고 처음 알았고, X에도 비슷한 영문 글이 올라와 있었다.

description은 트리거 명세다#

description은 요약문 대신 언제 불릴지를 정하는 명세로 쓰였다. 원문에 붙은 세 구역의 라벨을 그대로 살려 줄을 나눴다.

1
Concrete triggers:
2
  spawn/move/duplicate/transform actors,
3
  create or edit a Blueprint/Widget/Material/...,
4
  read or write properties on actors
5
  (e.g. `bIsLocked` on `BP_DoorActor`), ...
6
Treat as Unreal context even without
7
the word "Unreal":
8
  asset prefixes `BP_`, `WBP_`, `M_`, `SK_`, ...;
9
  UE C++ types/macros; `.uproject`;
10
  Content Browser; Outliner; PlayerStart; ...
11
Skip for:
12
  pure conceptual/docs questions,
13
  Unity, Godot, or unrelated uses of
14
  "blueprint"/"sequencer"/"widget".

• 긍정 트리거, 암묵 신호, 부정 트리거로 나뉜다.
• 암묵 신호가 특징적이다. 사용자가 “언리얼”이라고 말하지 않아도 BP_ 같은 에셋 접두사나 UPROPERTY가 보이면 UE 작업으로 본다.
• 부정 트리거는 개념 질문과 다른 엔진, 일반 명사로서의 “blueprint”를 제외한다.

description은 처음부터 이렇지는 않았다.

1. 처음에는 “Control Unreal Editor via MCP: create actors, edit Blueprints, …”처럼 기능을 나열했다.
2. 다음에는 “Use this skill whenever the user mentions Unreal Engine … even if they don’t explicitly name the skill.”로 넓게 불리게 했다.
3. 지금은 위의 세 구역 구조로 정확하게 불리게 했다.

더 자주 불리게 했다가 필요할 때만 불리게 고친 셈이다. 넓게 잡은 description이 UE 개념 질문에도 에디터 조작 스킬을 불렀던 것으로 보인다.

.gitignore에는 skills/*-workspace/를 무시하는 규칙이 있고 주석에 skill-creator의 description 최적화 루프와 eval 작업 공간이라고 적혀 있다. 트리거 정확도를 측정하면서 다듬은 것 같다.

본문: 설명서에서 지시문으로#

본문도 같은 무렵 지시문 형태로 다시 썼다.

• 이전 본문은 “Unreal MCP exposes hundreds of tools…”로 시작하는 제품 설명이었다.
• 지금은 “You are wired into a live Unreal Editor…”로 시작하는 2인칭 지시문이다.
• 설치와 장애 대응을 references/setup.md, references/operations.md로 옮겨 본문이 12KB에서 7KB로 줄었다. 처음부터 읽을 내용과 문제가 생겼을 때 읽을 내용을 나눴다.

현재 본문의 구성은 다음과 같다.

도구 검색: 메타 도구 3개#

• Unreal MCP 서버는 기본 설정(bEnableToolSearch = true)에서 list_toolsets, describe_toolset, call_tool 세 도구만 노출한다. 수백 개의 실제 도구는 call_tool의 인자로 이름을 넘겨 서버 안에서 실행된다.
• 레포 문서에는 컨텍스트 축소와 프롬프트 캐시 유지가 이유로 적혀 있다. 세션 중에 도구 목록이 바뀌지 않으니 캐시가 깨지지 않는다.
• v3.0.0 이전에는 load_toolset으로 툴셋을 네이티브 도구로 등록했고, v3.0.0에서 지금의 call_tool 방식으로 바꿨다.

Safety rules가 이 스킬의 핵심이다#

• 대량 변경 전후로 저장한다. MCP로 한 편집은 특히 컴파일 경계를 넘으면 되돌릴 수 없을 수 있다.
• C++이나 셰이더 컴파일 중에는 도구 호출이 멈추거나 이상하게 실패한다. C++ 재빌드는 LiveCodingToolset.CompileLiveCoding으로 하고 결과를 기다린다.
• 서로 의존하는 호출과 같은 에셋을 건드리는 변경은 순서대로 보낸다.
• 많은 도구가 예외 없이 status 값으로 성공과 실패를 돌려준다. 명시적인 성공이 아니면 멈춘다.
• PIE 중에는 에셋 생성 같은 에디터 전용 도구가 다르게 동작한다.

모두 도구 스키마를 읽어서는 알 수 없는 운영 지식이다. 뒤에서 볼 unreal-skill의 Novel 원칙(도구를 써서 알 수 있는 것은 쓰지 마라)에 가장 잘 맞는 부분이기도 하다.

공식 문서와 겹치는 부분, 겹치지 않는 부분#

동시 호출은 둘의 내용이 다르다. 공식 문서는 도구를 게임 스레드에서 순서대로 실행하므로 “clients should not issue overlapping Tool calls”라고 한다. 스킬은 최근 “MCP accepts concurrent requests”로 바뀌었다. 스킬이 문서보다 앞서 바뀌는 구간도 있다.

공식 문서가 이 플러그인을 언급하는 곳은 툴셋 작성 절의 한 문장뿐이다. Claude Code 사용자는 “the unreal-mcp Claude Code plugin”의 create-toolset 스킬로 툴셋을 만들 수 있다고 적혀 있다. 이름은 개명 전 그대로이고 레포 링크나 설치 방법은 없다. 문서만 읽어서는 이 플러그인이 GitHub와 공식 마켓플레이스에 있다는 것을 알기 어렵다.

쓰기 전에 확인할 것#

스킬은 코드를 쓰기 전에 다음을 순서대로 따지게 한다.

1. 이미 있는 기능인가? 있으면 만들지 말고 해당 도구를 알려 준다.
2. 요청이 생각보다 일반적인가? “Blueprint 에셋 메타데이터 읽기”는 모든 에셋에 해당하므로 BlueprintTools가 아니라 AssetTools에 둔다.
3. 같은 도메인의 툴셋이 이미 있는가?
4. 새 플러그인이 필요한가? 분명하지 않으면 사용자에게 묻는다.
5. Python과 C++ 중 무엇으로 만들 것인가? 사용자가 정할 문제다. 양쪽에서 쓸 수 있는 API를 요약해 보여 주고 결정을 기다린다. 둘 다 API가 없으면 우회하지 말고 멈춘다.

이후에는 공통 규약(실제 타입 사용, 실패는 반환값이 아니라 raise, 모든 도구는 static, 테스트 필수)과 C++/Python 작성법이 이어진다. 마지막은 테스트 루프로, MCP로 에디터에 붙어 만든 도구를 AutomationTestToolset으로 테스트한다.

문서화 규칙은 AI의 버릇을 겨냥한다#

문서화 지침은 나중에 간결한 쪽으로 한 번 더 강화됐다. 해당 커밋 메시지에 따르면 원래 지침이 “too abstract to counter the default bias toward over-documenting”이었다고 한다. 추가된 내용은 다음과 같다.

• 판정 기준: 시그니처, 이름, 타입만 보고 유능한 독자가 추론할 수 있는 줄이면 지운다.
• “LLMs over-document by default; resist it.”
• 구현 사유(왜 이렇게 짰는지)는 쓰지 않고 계약(무엇을 하는지)만 쓴다.
• 남길 것: 단위, 범위, 특이한 인코딩, 빈 결과의 의미.
• before/after 예시:

1
// Over-documented: every line restates the signature or narrates usage.
2
/**
3
 * Runs a cheat. @param CheatName The cheat name (case-insensitive), pass it to run the cheat.
4
 * @param Args Optional arguments; fill in the slots from the Args hint (e.g. "<float F>" -> "2.0",
5
 *             "<float A> <float B>" -> "1 2"). Empty string for no arguments.
6
 */
7
// Trimmed: only the non-inferable facts remain.
8
/**
9
 * Runs a cheat on the local player, as if typed into the console.
10
 * @param CheatName The cheat command name.
11
 * @param Args Arguments as a single space-separated string. Empty for none.
12
 */

이 수정에도 Co-Authored-By: Claude 트레일러가 붙어 있다. Claude가 말이 많아지는 버릇을 막는 규칙을 Claude와 함께 썼다.

엔진 쪽 구조 때문에 이 규칙이 중요하다. 여기서 쓴 주석은 그대로 AI가 보는 도구 설명이 된다. list_toolsets는 툴셋마다 이름과 설명 한 줄만 돌려주므로 스킬도 “An LLM will often see only the toolset name and this description”이라고 적고 툴셋 설명이 혼자서 이해되게 쓰라고 한다. 장황한 문서는 다음 에이전트의 컨텍스트를 잡아먹는다.

반환값 규칙과 엔진 코드가 어긋난다#

• 공통 규약의 제목은 “Return values carry data, not status”다. 이어지는 문장은 “Never return a boolean, error string, or result wrapper to communicate an error”라고 한다.
• 두 문장이 막는 범위가 다르다. 제목대로면 상태를 알리는 반환값은 모두 안 되고, 본문대로면 에러를 알리는 bool만 안 된다. 실패하면 에러를 올리고 성공하면 true를 돌려주는 도구는 그 사이에 걸린다.
• 엔진의 UAgentSkillToolset::CreateSkill은 실패하면 RaiseScriptError로 에러를 올린 뒤 빈 문자열을 반환한다. C++ 에러 처리 절이 시키는 방식 그대로다.
• 같은 클래스의 UpdateSkill은 실패하면 에러를 올리고 false를, 성공하면 true를 반환한다. CreateSkill은 이 반환값을 받아 실패하면 방금 만든 에셋을 지운다.
• AI는 이 false를 받지 않는다. 에러가 올라오면 툴셋 레지스트리가 반환값을 버리고 에러 메시지만 넘긴다(FunctionLibraryToolset.cpp:177-183). 성공하면 {"returnValue":true}가 간다.
• UpdateSkill만 이런 것도 아니다. 5.8.3의 Engine/Plugins에서 AICallable 함수 중 bool을 반환하는 것은 40개가 넘고, IsPIERunning처럼 질문에 답하는 것을 빼도 30개 넘게 같은 모양이다. 이름이 같은 도구도 갈린다. PCG의 UpdateNode는 bool, Dataflow의 UpdateNode는 void를 반환한다.
• ConfigSettingsToolset::SaveSection은 마지막에 return Section->Save();를 한다. 저장이 실패해도 에러 없이 false가 정상 응답으로 간다. 규칙이 막으려는 경우가 이쪽이다.
• 도구를 쓰는 쪽 스킬은 반대 전제를 둔다. unreal-mcp는 많은 도구가 예외 없이 성공과 실패 상태를 돌려준다며 응답을 꼭 확인하라고 한다.

스킬이 두 층이다#

이 스킬은 엔진 쪽 Agent Skill을 작성하는 방법을 다룬다. Claude Code 스킬과는 이름만 같고 다른 물건이다.

Agent Skill은 플러그인의 C++/Python 클래스로 정의하거나 프로젝트 Content에 블루프린트 클래스 에셋으로 만든다. 어느 쪽이든 에디터가 로드한 클래스를 MCP 도구가 텍스트로 돌려준다.

• ListSkills는 UAgentSkill의 파생 클래스를 모두 찾아 경로와 Description을 돌려준다. 프로젝트 설정의 허용/차단 정규식(AgentSkillAllowedNames, AgentSkillBlockedNames)으로 노출할 스킬을 거른다.
• 자동 호출이 없기 때문에 unreal-mcp 스킬이 “낯선 작업을 시작할 때마다 ListSkills를 확인하라”고 지시한다. Claude Code에서는 하네스가 하는 일을 여기서는 지시문이 대신한다.

Agent Skill 에셋의 정체: Data-only Blueprint#

CreateSkill이 만드는 것은 블루프린트다.

• UBlueprintFactory의 부모 클래스를 UAgentSkill로 지정해 블루프린트 에셋을 만든다.
• 생성된 클래스의 CDO(Class Default Object)에 Description과 Instructions를 쓴다.
• 패키지를 dirty로 표시할 뿐 저장하지는 않는다.
• UpdateSkill은 C++/Python으로 정의한 스킬은 수정하지 않는다. 저장할 에셋이 없어서 재시작하면 바뀐 내용이 사라지기 때문이다.

형식은 그래프 없이 Class Defaults만 채우는 Data-only Blueprint다. GameplayEffect를 블루프린트로 만들어 값만 채우는 것과 같은 방식이다. 다만 채우는 내용이 AI에게 주는 자연어 지시문이다.

지시문이 코드처럼 동작하는 예: PCG#

5.8.3에는 이미 Agent Skill이 몇 개 들어 있다. PCG 툴셋의 스킬은 GeneratePrompt를 오버라이드해 지시문의 자리표시자를 에디터에서 조회한 값으로 채운다.

경로는 Engine/Plugins/Experimental/Toolsets/PCGToolset/Source/PCGToolset/Public/PCGToolsetSkills.h다.

1
UCLASS()
2
class UPCGGraphGenerationSkill : public UAgentSkill
3
{
4
  GENERATED_BODY()
5

6
protected:
7
  virtual FString GeneratePrompt_Implementation(const FString& InitialInstructions) const override
8
  {
9
    FString CustomInstructions = InitialInstructions;
10
    CustomInstructions.ReplaceInline(TEXT("{Subgraphs}"),
11
      *FString::Join(UPCGToolset::ListAvailableSubgraphs(), TEXT(", ")));
12
    CustomInstructions.ReplaceInline(TEXT("{Nodes}"),
13
      *FString::Join(UPCGToolset::ListNativeNodes(true), TEXT(", ")));
14
    // {Examples}, {Instant Graphs}도 같은 방식으로 채운다.
15
    return CustomInstructions;
16
  }
17
};

스킬을 불러오는 순간 현재 프로젝트의 PCG 노드 목록과 서브그래프가 지시문에 들어간다. 정적인 SKILL.md로는 할 수 없는 일이다.

작성 원칙 6개#

unreal-skill이 제시하는 원칙은 다음과 같다.

• Novel: 도구를 써 보면 알 수 있는 것은 쓰지 않는다.
• Collegial: 문서가 아니라 유능한 동료에게 브리핑하듯 쓴다.
• Flexible: 개념 설명이든 절차든 가장 명확한 형태를 고른다.
• Durable: 프로퍼티나 도구 이름처럼 바뀌는 세부를 넣지 않는다.
• Agnostic: 오케스트레이션, 역할 이름, 모델 이름을 언급하지 않는다.
• Parsimonious: 모든 토큰은 비용이다. 없어도 아쉽지 않을 문장은 지운다.

Agnostic이 눈에 띈다. Claude Code용 플러그인이 엔진 Agent Skill에는 Claude조차 언급하지 말라고 한다. Agent Skill은 MCP로 전달되고 GenerateClientConfig는 Claude Code 외에 Cursor, VS Code, Gemini, Codex 설정도 만든다. 클라이언트와 무관한 지식은 엔진 쪽에 두고 이 플러그인은 Claude Code에서 그 지식에 닿는 입구 역할을 맡는 것으로 보인다.

Durable은 레포 스스로도 적용했다. unreal-mcp의 ## Workflows 절을 “names that drift”라는 이유로 지웠다. 정확한 Toolset.tool 이름에 묶인 절차였다.