Blender 에이전트 스킬 쓰는 법: SKILL.md 넣기, 검사, 지오메트리 노드 실습

기준: Blender Agent Skills 1.1.0(2026년 10월 16일 판, MIT 라이선스), Blender 5.2 LTS(시험은 5.2.1), Claude Code 공식 스킬 문서. 2026년 10월에 확인했습니다. 그림은 실제 터미널 화면과 Blender 렌더(EEVEE)입니다. 비행기는 이 글을 위해 상자와 원통으로 만든 블록 모형입니다.

MCP가 AI에게 Blender를 움직일 "손"을 준다면, 스킬은 Blender를 잘 다루는 "요령"을 줍니다. AI는 Blender 버전마다 바뀐 함수 이름을 헷갈리고, 다 만든 모델을 검사하지 않고 "끝났다"고 하기도 합니다. 스킬은 이런 실수를 줄이려고 미리 써 둔 설명서와 검사 스크립트 묶음입니다.

이 글은 2026년 10월에 공개된 Blender Agent Skills 묶음을 예로 듭니다. 설치하기 전에 무엇을 검사하는지, 프로젝트 폴더에만 넣는 법, 그리고 스크립트 두 개를 실제 Blender에서 돌린 결과를 보여 줍니다. 결과에는 스크립트가 잘한 것과 함께 실제로 걸린 문제 두 가지도 있습니다.

MCP 연결이 아직이라면 Blender 공식 MCP 설치하기를, AI 코딩 도우미가 처음이라면 Claude Code 입문을 먼저 보세요.

이 글을 마치면 아래를 할 수 있습니다.

1. 스킬과 MCP의 차이를 설명합니다.
2. 남이 만든 스킬을 설치하기 전에 스크립트를 검사합니다.
3. 필요한 스킬만 프로젝트 폴더의 .claude/skills에 넣습니다.
4. 자산 검사 스크립트로 허공에 뜬 부품을 찾습니다.
5. 지오메트리 노드 스크립트로 날개폭을 숫자 하나로 바꾸고, 결과를 눈으로 확인합니다.
6. 스킬 맨 위에 내 프로젝트 규칙을 덧붙입니다.

1. 스킬이란

스킬은 폴더 하나입니다. 안에 SKILL.md라는 설명서와, 필요하면 스크립트 파일이 들어 있습니다. AI 도우미는 시작할 때 각 스킬의 이름과 한 줄 설명만 읽어 둡니다. 그러다 일이 그 설명과 맞으면 그때 본문을 펼쳐 읽습니다.

주방의 요리책 선반을 떠올리면 됩니다. 요리사는 책등의 제목만 훑어 두고, 생선 요리를 할 때 생선 책을 꺼내 펼칩니다. 책을 다 외우고 있지 않으니 머리(컨텍스트)가 가볍습니다. Claude Code 공식 문서도 "스킬 설명은 늘 컨텍스트에 있고, 전체 내용은 부를 때 읽는다"고 설명합니다. 컨텍스트라는 말은 토큰과 컨텍스트 창 뜻에 풀어 두었습니다.

둘은 함께 씁니다. Blender Agent Skills 설명서도 "Blender MCP 서버가 있으면 열린 Blender에서, 없으면 화면 없는 Blender로 실행한다"고 적습니다.

스킬 형식(SKILL.md 꼴)은 공개 표준이라 여러 도구가 함께 읽습니다. Blender Agent Skills는 Claude Code, Codex, OpenCode, Gemini CLI, GitHub Copilot, Cursor를 대상으로 적어 두었습니다.

2. Blender Agent Skills 둘러보기

22개는 모델링, UV, PBR 재질, 베이크, 리깅, 애니메이션, 최적화, 내보내기, 렌더, 시간대(해 질 녘·밤), 날씨, 시뮬레이션, 자산 검사(QA)를 나눠 맡습니다. 시작점은 blender-core이고, 여기서 일에 맞는 다른 스킬로 안내합니다.

이 글에서 쓰는 스킬은 넷입니다.

3. 설치하기 전에 검사하기

스킬 안의 스크립트는 AI가 여러분 컴퓨터에서 실행합니다. 남이 만든 프로그램을 설치하는 것과 같으므로, 넣기 전에 한 번 훑어봅니다. 공개 저장소라도 마찬가지입니다.

따라 하기: 저장소를 내려받은 뒤(초록 Code 단추 ‣ Download ZIP 또는 git clone) 압축을 풀고, 각 스킬의 scripts 폴더에서 아래 낱말을 찾아봅니다. 텍스트 편집기의 "폴더에서 찾기"를 쓰면 빠릅니다.

이 묶음(1.1.0)의 스크립트에서는 인터넷 접속과 파일 지우기가 나오지 않았습니다(시험용 폴더는 빼고 봤습니다). 다른 프로그램을 실행하는 곳은 한 군데였습니다. blender-core/scripts/run_in_blender.py가 화면 없는 Blender를 띄우는데, --user-prefs를 주지 않으면 --factory-startup을 붙입니다. 여러분 설정을 망가뜨리지는 않지만, 설치한 애드온과 바꿔 둔 환경설정 없이 돈다는 뜻입니다. 평소 쓰는 애드온이 있어야 하는 작업이라면 이 점을 알고 씁니다.

4. 필요한 스킬만 프로젝트 폴더에 넣기

설치 방법은 두 가지입니다.

방법 1: Claude Code 플러그인(저장소 안내). Claude Code 안에서 두 줄을 넣습니다.

/plugin marketplace add EL4CTEO/blender-skills
/plugin install blender-agent-skills@blender-agent-skills

22개가 한꺼번에 들어갑니다.

방법 2: 필요한 것만 복사(이 글의 방법). 저장소의 설치 스크립트(install.ps1, install.sh)는 기본으로 사용자 전체 폴더(~/.claude/skills, ~/.agents/skills)에 넣습니다. 그러면 Blender와 상관없는 작업에서도 22개의 설명이 늘 따라옵니다. 처음에는 Blender 작업 폴더에 필요한 것만 넣는 편이 가볍습니다. 설치 스크립트에도 --project <폴더> 옵션이 있습니다.

따라 하기:

1. Blender 작업용 프로젝트 폴더를 정합니다. 이 글은 E:\blender_ai_demo\skills_demo를 씁니다.
2. 그 안에 .claude\skills 폴더를 만듭니다.
3. 내려받은 저장소의 skills 폴더에서 blender-core, blender-asset-qa, blender-geometry-nodes, blender-hardsurface-modeling 네 폴더를 통째로 복사해 넣습니다.
4. 명령 프롬프트에서 들어갔는지 확인합니다.

dir /b .claude\skills

그림 1. 프로젝트 폴더에 넣은 스킬 4개. 맨 위 스킬 폴더 목록, 가운데 한 스킬의 구성(SKILL.md와 scripts), 아래쪽 SKILL.md 머리말의 name과 description (터미널 화면 캡처)

그림 1 아래쪽 머리말이 AI가 시작할 때 읽어 두는 부분입니다. name은 스킬 이름, description은 "언제 이 스킬을 쓰는지"입니다. 이 스킬의 설명은 "Blender에서 만들거나 고친 모든 메시·자산에 반드시 거치는 검사 관문"이라는 뜻으로 시작합니다. 모델 작업이 끝날 무렵 AI가 이 설명을 보고 검사 스킬을 꺼내도록 쓴 문장입니다.

Claude Code는 프로젝트 폴더의 .claude/skills/<스킬 이름>/SKILL.md를 읽습니다. 다른 도구들(Codex, Gemini CLI 등)은 .agents/skills를 읽는다고 저장소 안내는 적습니다. Antigravity CLI의 스킬 폴더는 agy에 Blender MCP 연결하기에 있습니다.

5. 실습 1: 허공에 뜬 부품 잡기

AI가 만든 모델에서 흔한 실수는 부품이 몸통에서 떨어져 허공에 뜨는 것입니다. 작은 장면에서는 눈에 잘 띄지만, 부품이 수백 개면 놓치기 쉽습니다.

시작 상태: 아래 블록 비행기에서 시작합니다. 원통 동체, 넓은 주날개, 꼬리날개 셋은 붙어 있고, 빨간 작은 상자(이름 Stray) 하나를 일부러 동체 위 4 m 허공에 띄웠습니다.

그림 2. 검사 전 장면. 아래쪽 동체·주날개·꼬리날개, 위쪽 허공에 뜬 빨간 상자 Stray (Blender 렌더, EEVEE)

따라 하기: AI에게는 이렇게 말하면 됩니다.

blender-asset-qa 스킬로 Fuselage, Wing, Tail, Stray 네 물체를 한 자산으로 보고 검사해 줘. 프로필은 render로.

스킬 설명서의 검사 순서 1단계가 qa_check.py 실행입니다. 직접 실행해 보고 싶다면 화면 없는 Blender로 이렇게 부릅니다. plane.blend는 검사할 파일 이름입니다.

blender -b plane.blend -P .claude\skills\blender-asset-qa\scripts\qa_check.py -- --objects Fuselage Wing Tail Stray --profile render

-b는 화면 없이, -P는 파이썬 스크립트 실행, -- 뒤는 스크립트에 넘기는 값입니다. 결과는 JSON 한 덩어리로 나옵니다. 중요한 부분만 옮기면 이렇습니다.

{
  "pass": false,
  "errors": ["floating/detached part in Stray (8 verts at [0.0, 0.0, 4.0])"],
  "warnings": [
    "Wing: unapplied scale [2.0, 11.2, 0.2]",
    "Tail: unapplied scale [1.0, 3.2, 0.1]",
    "asset lowest point z=-0.6 (not resting on ground plane z=0)"
  ]
}

따라 하기: 스킬 설명서의 고치는 법 표를 따라 고칩니다.

1. Stray를 지웁니다. 일부러 띄운 부품이 아니라면 붙이거나 지웁니다.
2. 주날개와 꼬리날개를 골라 Ctrl+A ‣ Scale로 크기 값을 적용합니다.
3. 같은 검사를 다시 돌립니다.

{
  "pass": true,
  "errors": [],
  "warnings": ["asset lowest point z=-0.6 (not resting on ground plane z=0)"]
}

그림 3. 고친 뒤. 떠 있던 상자가 사라지고 검사는 pass true (Blender 렌더, EEVEE)

남은 경고 한 줄은 바닥 높이입니다. 공중에 떠 있는 비행기라면 받아들여도 되는 경고입니다. 스킬 설명서도 "경고는 고치거나, 받아들이는 까닭을 사용자에게 알린다"고 적습니다. 오류는 반드시 고치고, 경고는 고칠지 까닭을 적을지 고릅니다.

6. 실습 2: 날개폭을 숫자 하나로 바꾸기

blender-geometry-nodes 스킬의 gn_builder.py는 짧은 JSON 설정으로 지오메트리 노드 묶음을 만들어 줍니다. 지오메트리 노드는 모양을 규칙으로 만드는 Blender 기능입니다. 레시피에 "날개폭 = 숫자"를 적어 두면, 숫자만 바꿔 다른 크기의 날개를 얻습니다. 기초는 Blender 지오메트리 노드 입문에 있습니다.

시작 상태: 5절에서 고친 비행기에서 이어 갑니다. 주날개 자리에 크기 1 m짜리 상자(GNWing)를 하나 새로 놓습니다.

이 실습의 설정은 "상자를 앞뒤 길이 Chord, 좌우 길이 Span, 두께 0.2로 늘린다"는 뜻입니다. 기본값은 Span 11.2, Chord 2.0입니다.

{
  "name": "ParamWing", "tree": "geometry",
  "inputs": [["Geometry", "GEOMETRY"], ["Span", "FLOAT", 11.2], ["Chord", "FLOAT", 2.0]],
  "outputs": [["Geometry", "GEOMETRY"]],
  "nodes": {"cmb": ["ShaderNodeCombineXYZ", {}, {"Z": 0.2}], "xf": ["GeometryNodeTransform"]},
  "links": [["in.Chord", "cmb.X"], ["in.Span", "cmb.Y"], ["in.Geometry", "xf.Geometry"],
            ["cmb.Vector", "xf.Scale"], ["xf.Geometry", "out.Geometry"]]
}

따라 하기: AI에게 이렇게 말합니다.

blender-geometry-nodes 스킬의 gn_builder로 위 설정을 GNWing에 적용해 줘. Span은 6.0으로.

그림 4. 기본값 Span 11.2로 만든 날개. 치수 2.0 × 11.2 × 0.2 m (Blender 렌더, EEVEE)

그림 5. Span 6.0으로 만든 날개. 치수 2.0 × 6.0 × 0.2 m (Blender 렌더, EEVEE)

숫자 하나로 날개폭이 11.2 m에서 6.0 m로 바뀌었습니다. 같은 설정으로 여러 기체를 만들 때 쓸모가 큽니다.

시험하면서 걸린 문제 두 가지: 스킬도 사람이 만든 것이라 틀린 곳이 있습니다. 1.1.0 판에서 실제로 확인한 것이고, 두 번째 것은 같은 시험을 두 번 돌려 다시 확인했습니다. 저장소에 따로 알리지는 않았으므로, 새 판에서는 고쳐졌을 수 있습니다.

둘 다 결과 JSON만 보면 "성공"입니다. 첫 번째는 ok가 나왔고, 두 번째도 오류가 없었습니다. 그림 4·5처럼 렌더나 화면으로 모양을 직접 보는 확인이 있어야 잡힙니다. 자산 검사 스킬의 설명서가 "숫자로 검사한 뒤 반드시 눈으로 본다"고 강조하는 까닭입니다.

7. 내 규칙을 스킬 맨 위에 덧붙이기

스킬은 그냥 글 파일이라 고쳐 써도 됩니다. MIT 라이선스라 고쳐 쓰는 것도 허용됩니다. 6절 같은 함정을 찾았거나, 내 프로젝트만의 규칙이 있다면 blender-core/SKILL.md의 머리말(--- 두 줄 사이) 바로 아래에 적어 둡니다. AI가 Blender 일을 시작할 때 가장 먼저 펼치는 스킬이기 때문입니다.

따라 하기:

1. .claude\skills\blender-core\SKILL.md를 텍스트 편집기로 엽니다.
2. 두 번째 --- 줄 바로 아래에 빈 줄을 하나 두고 아래처럼 적습니다. 내용은 여러분 프로젝트에 맞게 바꿉니다.

## 이 프로젝트 규칙 (이 스킬보다 먼저 읽기)
- 렌더는 EEVEE로 한다. 첫 렌더는 960x540.
- 렌더 출력 경로는 절대 경로로 쓴다.
- gn_builder를 파이썬으로 부를 때 적용 인자는 apply_to= 다(apply=는 무시됨).
- 같은 물체에 gn_builder를 두 번 부르지 않는다. 값은 모디파이어 패널에서 바꾼다.
- 모델을 만들거나 고치면 blender-asset-qa로 검사하고, 렌더 한 장으로 모양을 확인한 뒤 끝났다고 말한다.

3. 저장합니다. 다음 대화부터 반영됩니다.

머리말 위쪽(name, description)은 고치지 않습니다. AI가 스킬을 고르는 기준이라, 잘못 고치면 스킬을 못 찾습니다. 저장소를 새 판으로 바꿀 때 덧붙인 글이 지워질 수 있으니, 규칙은 따로 메모해 두세요.

연습 문제

1. 내려받은 저장소에서 subprocess를 검색해 보세요. 어느 파일에서 나오는지 적어 보세요.
2. 여러분 프로젝트 폴더에 스킬 두 개만 넣고 dir /b .claude\skills로 확인합니다.
3. 기본 큐브 위 허공에 작은 큐브를 하나 띄운 장면을 만들고, 자산 검사를 돌려 floating 오류가 나오는지 보세요.
4. 6절의 설정에서 Chord를 3.0으로 바꿔 새 물체에 적용하고, 치수가 3.0 × 11.2 × 0.2가 되는지 확인합니다.
5. blender-core/SKILL.md에 여러분 규칙 세 줄을 덧붙이고 저장해 두세요.

자주 하는 실수와 해결

한 줄 정리

스킬은 요리책, MCP는 손. 넣기 전에 검사하고, 필요한 것만 프로젝트 폴더에, 결과는 숫자와 그림 둘 다로 확인.

함께 읽기

• Blender 공식 MCP 설치하기
• Claude Code에 Blender 공식 MCP 붙이기
• AI에게 Blender를 맡기기 전 안전 점검
• Gemini CLI에서 Antigravity CLI로: agy에 Blender MCP 연결하기
• Blender 지오메트리 노드 입문
• AI와 Blender, 작은 작업부터 함께 시작하기

참고 자료

• Blender Agent Skills 저장소(README, CHANGELOG, LICENSE): https://github.com/EL4CTEO/blender-skills
• Claude Code 공식 문서, Skills: https://code.claude.com/docs/en/skills
• Agent Skills 공개 형식: https://agentskills.io/
• Blender 5.2 매뉴얼, 지오메트리 노드: https://docs.blender.org/manual/en/5.2/modeling/geometry_nodes/index.html
• 단축키: 크기 값 적용 Ctrl+A ‣ Scale
• 그림: 터미널 화면 1장(Windows 명령 프롬프트), Blender 5.2.1 EEVEE 렌더 4장. 블록 비행기는 이 글을 위해 만든 예제