게임 개발용 Agent Skills: Claude Code, Codex, Cursor 설정

게임 프로젝트의 루트 디렉터리에서 npx skills add gamedev-skills/awesome-gamedev-agent-skills 명령으로 gamedev-skills/awesome-gamedev-agent-skills를 설치하고, router를 포함한 뒤 사용할 코딩 에이전트를 선택하세요. 그다음 router를 명시적으로 호출하고, 큰 기능을 요청하기 전에 Godot나 Unity에서 작은 변경 하나를 검증하세요. 전체 카탈로그를 설치해도 모든 스킬 본문이 한꺼번에 컨텍스트에 들어가지는 않습니다. 에이전트는 먼저 메타데이터를 확인하고, 필요할 때 선택한 지침을 읽습니다.

2026-10-26 기준 현재 저장소에는 전문 스킬 76개와 별도의 router가 있으며, 스킬 정의는 총 77개입니다. 저장소의 About 설명에는 아직 74개로 표시되어 있으므로, 실제로 무엇이 설치되는지는 현재 파일과 설치 프로그램의 미리보기로 확인하세요. 이 패키지에는 Apache-2.0 라이선스가 적용됩니다.

이 설정은 이미 코딩 에이전트를 사용하면서 게임 엔진별 지침을 반복해서 활용하고 싶은 개발자에게 유용합니다. 패키지는 코드와 작업 절차에 대한 지침을 제공하므로, 게임 에디터와 프로젝트, 정상적으로 사용할 수 있는 코딩 에이전트 계정 또는 API 설정은 별도로 필요합니다.

프로젝트 범위로 설치하기

먼저 프로젝트 내부에 설치하면 게임 파일과 함께 추가된 스킬 파일을 검토할 수 있습니다. npm 메타데이터에 따르면 2026-10-26 기준 배포된 skills CLI 버전은 1.7.4이며, Node.js 22.20.0 이상이 필요합니다. 저장소를 가져올 수 있도록 Git도 준비하세요.

게임 프로젝트의 루트 디렉터리에서 Bash를 열고 카탈로그를 미리 확인합니다.

node --version
git --version
npx skills add gamedev-skills/awesome-gamedev-agent-skills --list

목록에서 router, godot-2d-movement, platformer, unity-scriptableobjects를 찾으세요. --list 옵션은 스킬을 설치하지 않고 사용 가능한 목록을 보여 줍니다. 설치를 확정하기 전에 router와 사용할 스킬의 지침을 읽어 보세요.

패키지에서 공식적으로 안내하는 설치 명령을 실행합니다.

npx skills add gamedev-skills/awesome-gamedev-agent-skills

이 안내를 따라 진행할 때는 대화형 선택 화면에서 router와 전체 카탈로그를 포함하고, 사용할 에이전트를 고른 다음 설치 범위를 Project로 선택하세요. 여러 프로젝트에서 쓸 수 있도록 사용자 범위에 설치하려는 경우에만 의도적으로 -g를 추가합니다.

Codex에 전체 카탈로그를 설치하겠다고 명시하려면 다음 명령을 대신 사용할 수 있습니다.

npx skills add gamedev-skills/awesome-gamedev-agent-skills --skill '*' -a codex

다른 클라이언트에 설치할 때는 codex를 claude-code 또는 cursor로 바꾸세요. Bash가 와일드카드를 확장하지 않도록 '*'의 따옴표는 유지합니다. CLI 명령 참조는 모든 스킬을 선택하는 --skill '*'와 모든 에이전트까지 선택하는 --all을 구분합니다.

설치 결과를 확인합니다.

npx skills list

router와 선택한 엔진의 검증에 필요한 스킬이 목록에 있는지 확인하세요. 설치 프로그램은 공개 스킬 파일을 가져오는 역할을 합니다. 모델 인증은 코딩 클라이언트에서 계속 관리하며, 에이전트를 실행하면 기존 모델 사용 한도가 차감되거나 API 요금이 부과됩니다.

Claude Code, Codex, Cursor는 파일을 어디에서 읽을까?

에이전트가 지원하는 디렉터리와 CLI가 선택하는 디렉터리가 항상 같지는 않으므로, 실제 설치 위치를 확인하세요. skills 1.7.4로 프로젝트에 설치할 때의 경로는 다음과 같습니다.

에이전트	`-a` 뒤에 지정할 값	프로젝트 설치 위치	채팅에서 router를 명시적으로 호출하는 방법
Claude Code	`claude-code`	`.claude/skills/`	`/router`
Codex CLI 또는 IDE 확장	`codex`	`.agents/skills/`	`/skills`에서 `router`를 선택하거나 `$router`로 언급
Cursor Agent	`cursor`	`.agents/skills/`	`/`를 입력한 뒤 `router` 선택

이 호출 방식은 Bash가 아니라 에이전트의 채팅에서 사용합니다. Cursor는 수동 설치 위치로 .cursor/skills/도 지원하므로 패키지의 간단한 설치 페이지는 호환 경로를 확인하는 데 여전히 유용합니다. 다만 .cursor/skills/가 비어 있다는 이유만으로 CLI 설치가 실패했다고 판단하면 안 됩니다.

현재 설치 프로그램의 에이전트별 경로 설정은 Codex와 Cursor 모두에 .agents/skills/를 지정합니다. 대상 디렉터리가 하나뿐이면 그곳에 파일이 복사됩니다. 서로 다른 설치 디렉터리를 사용하는 클라이언트를 선택하면, 설치 프로그램은 .agents/skills/의 공통 사본을 심볼릭 링크로 공유하거나 각각 별도의 사본을 만들 수 있습니다. 모든 설치에서 링크가 생성된다고 가정하지 말고 설치 요약에서 적용된 방식을 확인하세요.

설치된 각 스킬은 <skills-directory>/<skill-name>/SKILL.md 형태여야 합니다. 예를 들어 Codex의 이동 스킬은 .agents/skills/godot-2d-movement/SKILL.md에 있고, Claude Code에서는 .claude/skills/godot-2d-movement/SKILL.md에 해당합니다. 수동 설치 지침에 따라 스킬에 references/, scripts/, assets/ 디렉터리가 포함되어 있다면 함께 보존하세요.

router는 필요한 스킬을 어떻게 고를까?

router는 엔진과 작업에 맞는 지침을 선택하며, 필요할 때 본문을 읽는 기본 로딩 기능은 이를 사용하는 에이전트가 제공합니다. Agent Skills 사양 개요는 이름과 설명으로 스킬을 발견하고, 본문을 읽어 활성화한 뒤, 작업에 필요한 추가 리소스를 불러오는 흐름을 설명합니다.

패키지의 router 지침은 이 방식을 게임 개발에 적용합니다.

프로젝트에서 엔진 하나를 식별하고 해당 버전을 읽습니다.
엔진, 작업 분야, 게임 장르, 작업 절차에 맞는 최소한의 스킬 조합을 선택합니다.
선택한 스킬 본문을 읽고, 함께 제공된 참고 자료는 작업에 필요할 때만 엽니다.

Godot를 식별하는 주요 파일은 project.godot입니다. Unity는 Assets/와 ProjectSettings/ProjectVersion.txt의 조합으로 식별합니다. 이동 기능을 요청하면 godot-2d-movement와 platformer를 선택할 수 있고, 이후 저장 기능을 요청하면 무관한 엔진의 카탈로그를 읽는 대신 데이터 영속성에 관한 지침을 선택해야 합니다.

router 자체도 모델이 따라야 할 절차를 적은 SKILL.md 파일입니다. 읽기 횟수의 상한을 강제하는 별도의 실행 프로그램이 아닙니다. 또한 router만 설치한다고 해서 그것이 참조하는 전문 지침까지 제공되는 것은 아닙니다. 해당 스킬도 설치되어 있어야 하며 에이전트가 발견할 수 있어야 합니다.

메타데이터도 컨텍스트 공간을 차지하며, 읽어 들인 지침과 도구 결과, 재시도 역시 모델 사용량에 포함됩니다. 기존 스킬 모음 때문에 초기 스킬 목록의 컨텍스트 예산에 관한 경고가 발생한다면, --skill로 router와 작업에 필요한 전문 스킬만 포함한 작은 구성을 설치하세요. 스킬 개수만 보고 특정 비율의 토큰 절감 효과가 측정되었다고 가정할 수는 없습니다.

작은 엔진 작업으로 검증하기

지침을 실제로 읽었는지와 엔진에서 결과가 제대로 동작하는지를 모두 확인하세요. 게임 프로젝트에서 에이전트의 새 세션을 시작하고, 위 표의 방법으로 router를 명시적으로 선택한 다음 아래 프롬프트 중 하나를 사용합니다.

클라이언트에서 도구 활동을 볼 수 있다면 실제 스킬 활성화나 파일 읽기 기록을 확인하세요. 에이전트가 스킬을 불러왔다고 말하는 것보다 설치된 SKILL.md를 성공적으로 읽은 기록이 더 확실한 근거입니다.

Godot: 공중에서 점프 한 번 더 추가하기

CharacterBody2D 플레이어, 충돌 판정용 도형, 바닥이 있는 기존 Godot 4 장면을 사용하세요. 이미 실행할 수 있는 장면이어야 합니다. router는 이 요청에 godot-2d-movement와 platformer를 함께 사용하도록 안내하며, 이동 스킬은 엔진에 맞는 컨트롤러 지침을 제공합니다.

Use the installed router skill for this Godot project. Inspect project.godot
and the actual editor version before editing, and preserve that version.

Report the resolved paths of the router and selected SKILL.md files you
actually read. Resolve skill names through the installed skill locations.

Add one extra mid-air jump to the existing CharacterBody2D player.
Keep the change in the player controller and preserve the current controls.
A fresh jump press on the ground starts the first jump. One more fresh
press in the air starts the second. A third press before landing does
nothing. Holding the button must not repeatedly jump. Landing restores
both jumps.

List the changed files and give the exact scene and controls for checking
the result. Separate checks you ran from checks I must perform in Godot.

에이전트가 지정한 장면을 실행하세요. 지상에서 버튼을 한 번 누르고 공중에서 다시 누르면 두 번 점프해야 하며, 공중에서 세 번째로 눌렀을 때는 추가 점프가 발생하지 않아야 합니다. 착지하면 같은 점프 순서를 다시 사용할 수 있어야 합니다. 점프하는 동안 버튼을 계속 누르고 있어도 반복해서 점프하지 않는지, 새로운 스크립트 오류나 런타임 오류가 발생하지 않는지도 확인하세요.

패키지의 이동 스킬은 Godot 4.7을 기준으로 하지만, 엔진 감지 지침은 기존 프로젝트의 버전을 유지하도록 명시합니다. 패키지를 설치했다는 이유로 프로젝트를 마이그레이션하거나 다른 릴리스의 API로 바꿀 필요는 없습니다.

Unity: 공유 데이터와 실행 중 수량 분리하기

기존 Unity 프로젝트에서 검증 후 버려도 되는 테스트 장면을 사용하세요. 이 검증에서는 unity-scriptableobjects를 활용하며, 데이터를 사용하는 작은 컴포넌트에는 unity-csharp-scripting도 적합합니다. 완전한 인벤토리 시스템을 요청하지 않고도 공유 데이터에 관한 스킬 지침을 확인할 수 있습니다.

Use the installed router skill for this Unity project. Read
ProjectSettings/ProjectVersion.txt and preserve the editor and package
versions. Report the resolved SKILL.md paths you actually read.

Create an ItemDefinition ScriptableObject with itemId, displayName,
and maxStack, using CreateAssetMenu. Use one example asset with
itemId "potion", displayName "Potion", and maxStack 10. Treat the asset
as read-only configuration during play.

Create two distinct runtime slot instances referencing that same asset.
Start their quantities at 2 and 5. Add one small probe component that
decrements only the first slot, then reports quantities 1 and 5,
confirms both slots reference the same asset, and checks that the
definition fields are unchanged. Start each probe run with fresh slots.

Keep the output to the data model and probe component. Give exact
asset-creation, component-attachment, Inspector-assignment, and Play-mode
steps. Distinguish checks you executed from checks I must perform.

생성된 Assets 메뉴 항목으로 예제 에셋을 만들고, 빈 GameObject에 검증 컴포넌트를 추가한 뒤 Inspector에서 에셋을 할당하고 Play 모드에 들어가세요. 서로 독립적인 슬롯 수량이 2와 5에서 1과 5로 바뀌면서도, 두 슬롯은 동일한 정의 에셋에 대한 참조를 유지해야 합니다. Play 모드를 종료한 뒤에도 에셋에는 potion, Potion, 10이 그대로 남아 있어야 합니다.

Unity의 ScriptableObject 문서는 데이터를 사용하는 여러 객체가 참조를 통해 에셋 하나를 공유할 수 있다고 설명합니다. 에셋이 본질적으로 불변인 것은 아닙니다. 이 예제는 바뀌는 수량을 의도적으로 별도의 런타임 객체에 보관합니다. 두 수량이 동시에 바뀐다면 구현에서 정의뿐 아니라 슬롯 객체까지 실수로 공유하고 있는지 확인하세요.

router나 선택한 스킬을 찾지 못할 때

설치 여부, 스킬 발견 여부, 파일 경로 해석을 구분해서 확인하세요. 나타난 증상에 맞춰 다음 조치를 선택합니다.

증상	확인할 내용과 다음 조치
스킬 목록이 나오기 전에 미리보기가 실패함	실제 오류를 읽고, 현재 사용 중인 Node.js 버전과 Git 사용 가능 여부, npm/GitHub 접근을 확인하세요. 문제가 있는 전제 조건을 해결한 다음 `--list`를 다시 실행합니다.
설치 목록에 엔진 스킬은 있지만 `router`가 없음	설치를 다시 진행하면서 `router`를 포함하세요. 저장소의 `skills/` 내용만 수동으로 복사하면 별도 디렉터리인 `router/`가 빠집니다.
파일은 있지만 에이전트에 스킬이 나타나지 않음	세션이 의도한 프로젝트에서 열렸는지, 각 폴더에 `SKILL.md`가 있는지 확인하세요. 클라이언트 문서의 경로를 확인하고, 스킬 목록이 갱신되지 않았다면 세션을 다시 시작합니다.
에이전트가 `skills/godot/` 또는 `skills/unity/`로 시작하는 경로를 열지 못함	스킬 이름을 기준으로 실제 설치 위치를 찾고, 파일을 성공적으로 읽었는지 확인한 뒤 수정 작업을 시작하세요.
에이전트가 잘못된 엔진을 선택함	게임의 올바른 하위 디렉터리를 열거나 사용할 엔진과 프로젝트를 명시하세요. 에이전트가 보고한 식별 파일과 버전도 확인합니다.

경로 해석 문제는 특히 살펴볼 필요가 있습니다. router는 원본 파일을 skills/<category>/<name>/SKILL.md 형태로 설명하지만, CLI 설치 프로그램은 각 스킬을 설치 경로 바로 아래의 스킬 이름 디렉터리에 배치합니다. 원본 저장소를 기준으로 한 상대 경로를 그대로 따라가는 에이전트는 설치된 스킬을 찾지 못할 수 있습니다. 이는 확인해야 할 디렉터리 구조 차이이며, 모든 클라이언트에서 실패한다는 증거는 아닙니다.

따라서 Codex나 Cursor에 설치된 Godot 스킬의 실제 경로는 .agents/skills/godot-2d-movement/SKILL.md일 수 있으며, 해당 스킬의 참고 자료도 그 옆에 있습니다. 게임 프로젝트 안에 저장소와 같은 디렉터리 트리를 하나 더 만들지 말고, 스킬 검색으로 확인한 실제 경로를 사용하세요.

외부 스킬은 재사용 전에 검토하기

이 파일들은 에이전트의 코드 수정과 명령 실행에 영향을 줄 수 있는 지침으로 보고 검토하세요. 처음 사용하기 전에 router, 선택한 스킬 본문, 필수 참고 자료, 에이전트에게 실행하도록 요구하는 스크립트나 외부 명령을 읽어 보세요. 의존성 설치, 다운로드 경로, 업로드, 삭제 같은 파괴적 작업이 실제 요청한 작업 범위와 맞는지 확인해야 합니다.

--list 미리보기는 스킬 패키지를 설치하지 않지만, npx는 설치 프로그램 자체를 실행합니다. 평소 사용하던 명령 승인 절차를 유지하고, 설치 요약에서 기존 스킬 중 덮어쓰게 될 항목이 있는지 확인하세요.

업데이트를 적용할 때는 파일 앞부분의 메타데이터인 프런트매터도 검토하세요. 예를 들어 Claude Code의 allowed-tools 문서는 이 필드가 도구 사용을 미리 승인할 수 있다고 설명합니다. 이 필드는 샌드박스로 실행을 제한하는 설정이 아닙니다. 프런트매터가 간단하더라도 변경된 지침과 포함된 명령은 확인해야 합니다.

첫 변경은 diff로 검토하기 쉬운 작은 범위로 유지하세요. 스킬 업데이트를 적용한 뒤에는 더 큰 기능을 맡기기 전에 해당 엔진의 검증을 다시 수행하세요.