ThreeUI 에이전트 스킬 설치법: 포인터·스캔·GPU 파티클을 Claude Code에 넣는 방법

 

카테고리: 생성형 AI & 웹디자인 | 작성자: 수석 AI & 3D 웹 개발 연구원 | 최종 업데이트:

ThreeUI 에이전트 스킬 설치법: 포인터·스캔·GPU 파티클을 Claude Code에 넣는 방법

ThreeUI의 Sylva 화면을 보고 "이걸 Claude Code 같은 AI CLI 에이전트가 반복해서 고품질로 구현할 수 있을까?"라고 생각하셨나요? 결론부터 말씀드리면 완전 가능합니다. 핵심 인터랙션이 재사용 가능한 SKILL.md 플레이북으로 표준화되어 있기 때문입니다.

📌 핵심 요약 (Executive Summary)
  • ThreeUI vs Agent Skills: ThreeUI가 완성된 WebGL 컴포넌트 '카탈로그'라면, 에이전트 스킬은 Claude Code 같은 AI 에이전트가 해당 효과를 상황에 맞게 재구현하도록 지침을 주는 '작업 지시서(SKILL.md)'입니다.
  • 핵심 스킬 3종: 마우스 반응형 오비트(add-mouse-driven-orbit), 와이어프레임 스캔(build-wireframe-scan-reveal), GPU 파티클 트레일(build-interactive-particle-trail)을 수록했습니다.
  • Claude Code 맞춤 설치 및 최적화: Claude Code 전역 메모리(~/.claude/skills) 및 프로젝트 경로(.claude/skills) 배치법과 함께 60FPS 최적화 체크리스트를 제공합니다.

1. ThreeUI와 에이전트 스킬의 구조적 차이점

웹 3D 구현 시 가장 흔히 발생하는 오해는 완성된 라이브러리와 AI용 지침서를 동일시하는 것입니다. 두 개념의 명확한 역할 분담을 이해해야 효율적인 인프라 구축이 가능합니다.

ThreeUI는 실시간 미리보기, 패러미터 조절, 소스 코드 확인을 제공하는 Three.js 컴포넌트 UI 카탈로그입니다. 커뮤니티 저장소에는 오픈소스 컴포넌트 구현체와 에셋이 포함되어 있습니다.

반면 MengTo/Skills 저장소의 Agent Skills는 Claude Code 및 다양한 AI 코딩 에이전트가 해석할 수 있는 작업 표준서입니다. 폴더 내 SKILL.md 파일에는 트리거 조건, 구현 알고리즘, 파라미터 기본값, 테스트 검증 루틴이 완벽히 정의되어 있습니다.

ThreeUI (Component UI)

정형화된 디자인 에셋 및 코드 덩어리를 직접 모듈 형태로 프로젝트에 복사하여 가져오는 정적 접근 방식입니다.

Agent Skill (Playbook)

Claude Code가 기존 프레임워크와 디렉터리 구조를 분석하여 상호작용 인터랙션을 프로젝트 맞춤형으로 유연하게 재설계하는 동적 작업서입니다.

2. Sylva 프로토타입 기반 핵심 스킬 3종 상세 분석

Sylva 데모에서 추출된 인터랙션 스킬은 저장소 업데이트에 따라 공식 명칭이 변경되었습니다. Claude Code 설정 시 **현재 공식 저장소 폴더명**을 지정해야 제대로 작동합니다.

[Three.js Interactive Render Stage: Pointer Orbit + Wireframe Scan + Particle Trail Integration]
[사진 1] Three.js 인터랙션 렌더링 파이프라인 (포인터 오비트, 스캔 리빌, GPU 파티클이 단일 RAF 상에서 구동되는 시각 구조화 맵)
초기 명칭 현재 스킬명 (공식 저장소) 핵심 작동 로직 및 렌더링 효과
threejs-pointer-orbit add-mouse-driven-orbit 마우스 커서 위치에 연동되어 카메라와 오브젝트 그룹이 서로 다른 패럴랙스 레이어로 부드럽게 반응 회전
threejs-wireframe-scan-reveal build-wireframe-scan-reveal 월드 공간 스캔 반경을 설정하여 선행 와이어 케이지가 지나간 자리에 솔리드 메쉬 표면이 등장하는 연출
threejs-gpu-particle-spray build-interactive-particle-trail 포인터 이동 거리를 측정해 고정 크기의 GPU Float32Array 버퍼에서 입자를 방출 및 순환 재활용하는 트레일 기법

3. Claude Code 환경별 에이전트 스킬 설치 단계별 가이드

Claude Code는 CLI 기반으로 터미널과 직접 연동되며 사용자 전역 스킬 경로(~/.claude/skills 또는 ~/.agents/skills)와 프로젝트 로컬 전용 경로(.claude/skills 또는 .agents/skills)를 참조합니다. 작업 환경에 맞춰 선택하세요.

$ claude
> /skills
Available skills:
- add-mouse-driven-orbit (~/.claude/skills/add-mouse-driven-orbit/SKILL.md)
- build-wireframe-scan-reveal (~/.claude/skills/build-wireframe-scan-reveal/SKILL.md)
- build-interactive-particle-trail (~/.claude/skills/build-interactive-particle-trail/SKILL.md)
[사진 2] Claude Code CLI 인터페이스에서 인식된 3D 에이전트 스킬 목록 확인 화면

방법 A: Claude Code 프롬프트에서 자동 다운로드 설치

Claude Code 터미널 실행 상태에서 아래 명령어를 전달하면 Claude가 Bash 도구를 활용해 저장소에서 세 스킬을 가져와 자동으로 배치합니다.

https://github.com/MengTo/Skills 저장소에서 다음 3개 스킬을 가져와 내 ~/.claude/skills/ 폴더에 설치해줘:
1. agent-skills/web-design/add-mouse-driven-orbit
2. agent-skills/web-design/build-wireframe-scan-reveal
3. agent-skills/web-design/build-interactive-particle-trail

방법 B: macOS 및 Linux 터미널 전역(Global) 직접 설치

모든 개발 프로젝트에서 Claude Code가 스킬을 바로 인식하도록 시스템 계정 전역 경로로 직접 복사합니다.

work_dir="$(mktemp -d)"
git clone --depth 1 https://github.com/MengTo/Skills.git "$work_dir/Skills"
mkdir -p "$HOME/.claude/skills"

cp -R "$work_dir/Skills/agent-skills/web-design/add-mouse-driven-orbit" "$HOME/.claude/skills/"
cp -R "$work_dir/Skills/agent-skills/web-design/build-wireframe-scan-reveal" "$HOME/.claude/skills/"
cp -R "$work_dir/Skills/agent-skills/web-design/build-interactive-particle-trail" "$HOME/.claude/skills/"

find "$HOME/.claude/skills" -maxdepth 2 -name SKILL.md -print

방법 C: 특정 프로젝트 전용(Local) 레포지토리 설치

프로젝트를 공유하는 팀원들과 동일한 스킬 지침을 유지하려면 워크스페이스의 .claude/skills 폴더에 배치합니다.

work_dir="$(mktemp -d)"
git clone --depth 1 https://github.com/MengTo/Skills.git "$work_dir/Skills"
mkdir -p .claude/skills

cp -R "$work_dir/Skills/agent-skills/web-design/add-mouse-driven-orbit" .claude/skills/
cp -R "$work_dir/Skills/agent-skills/web-design/build-wireframe-scan-reveal" .claude/skills/
cp -R "$work_dir/Skills/agent-skills/web-design/build-interactive-particle-trail" .claude/skills/
💡 Windows 운영체제 안내: Windows 사용자는 Git Bash를 통해 위 명령어를 수행하거나, GitHub 저장소에서 ZIP 압축 파일을 다운로드한 후 사용자 경로(C:\Users\사용자명\.claude\skills)로 세 폴더를 수동 복사하시면 됩니다.

4. 실전 워크플로우: Claude Code 전용 프롬프트 명령어

Claude Code에 작업을 지시할 때는 파일 경로 지정, 3D 렌더링 목적, 스킬 플레이북 호출 방식을 조합하여 프롬프트를 작성하면 완성도가 극대화됩니다.

① 마우스 오비트 및 시네마틱 깊이감 구현 프롬프트

add-mouse-driven-orbit 스킬 지침을 참고해서 src/components/HeroCanvas.tsx 파일의 Three.js 씬에 포인터 오비트 반응을 추가해줘.
OrbitControls의 드래그 조작 대신, 마우스 커서 위치에 따라 카메라인 전경 3D 메쉬와 배경 메쉬가 서로 다른 레이어로 parallax 회전해야 해.
포인터가 화면을 벗어나면 중앙 원점으로 감쇄(Damping)하며 복귀하고, 모바일 뷰포트에서는 중앙 구도를 고정해줘.
prefers-reduced-motion 미디어 쿼리도 반드시 지원해야 해.

② 와이어프레임 스캔 리빌 효과 구현 프롬프트

build-wireframe-scan-reveal 스킬 플레이북을 적용해서 메인 3D 모델 최초 로딩 등장 이펙트를 구현해줘.
동일한 월드 스캔 반경 값을 공유하도록 와이어 케이지 셰이더와 솔리드 표면 재질을 작성해줘.
와이어프레임이 선행 발광하며 지나간 뒤 솔리드 표면이 메워지도록 설정하고, 3.4초 이내에 연출이 완료되게 해줘.
애니메이션이 끝나면 와이어 임시 메모리를 dispose 처리하고, Replay 버튼 및 창 리사이즈 대응 로직도 포함해줘.

③ GPU 파티클 트레일 연출 구현 프롬프트

build-interactive-particle-trail 스킬 규칙에 따라 마우스 이동 궤적을 따르는 파티클 트레일을 추가해줘.
setInterval 방식이 아닌 포인터 이동 거리(DistanceThreshold)를 계산해 속도와 관계없이 균일한 간격으로 입자가 방출되게 해줘.
고정 크기 Float32Array GPU 파티클 버퍼를 순환 재활용하여 메모리 증가를 막아줘.
포인터 재진입 시 튀는 대각선 잔상이 생기지 않도록 이전 좌표를 초기화하고, 접근성을 위한 실행 대체 버튼도 작성해줘.

④ 복합 인터랙션 파이프라인 통합 프롬프트

add-mouse-driven-orbit, build-wireframe-scan-reveal, build-interactive-particle-trail 세 개의 스킬을 결합해서 메인 캔버스 컴포넌트를 작성해줘.

구현 조건:
1. Viewport 기준 카메라 바운딩 박스를 먼저 고정할 것.
2. 컴포넌트 마운트 시 와이어프레임 스캔 연출로 3D 모델을 공개할 것.
3. 공개 완료 후 포인터 오비트와 GPU 파티클 트레일을 활성화할 것.
4. 모든 비주얼 연산은 단 하나의 requestAnimationFrame 루프 내에서 처리할 것.
5. devicePixelRatio는 Math.min(window.devicePixelRatio, 2)로 제한할 것.
6. React 언마운트 시 geometry, material, texture 메모리를 완벽히 해제할 것.

5. ThreeUI 독립 컴포넌트 직접 패키지 설치 방법

스킬을 통한 AI 재구현 방식 외에 ThreeUI에 등록된 커뮤니티 React 컴포넌트를 모듈 형태로 즉시 프로젝트에 탑재하고자 할 경우 공식 npm 패키지를 이용합니다.

npm install @designcodeio/threeui 
import { AtTheHorizon } from "@designcodeio/threeui";
import "@designcodeio/threeui/style.css";

export function HeroSection() {
  return (
    <div style={{ width: "100%", height: "500px" }}>
      <AtTheHorizon />
    </div>
  );
}

전체 오픈소스 카탈로그 프로젝트를 로컬 개발 환경에서 직접 실행하여 구조를 파악하고 싶다면 Git 저장소를 클론합니다.

git clone https://github.com/MengTo/threeui.git
cd threeui
npm install
npm run dev

6. WebGL 성능 저하 및 메모리 누수 방지 체크리스트

Three.js 기반의 웹 인터랙션이 지속적인 60FPS 모바일 성능을 유지하려면 Claude Code로 작성한 결과물에서 아래 최적화 항목을 검증해야 합니다.

  • ✓ 단일 애니메이션 루프(Single RAF) 유지: 각 스킬 모듈마다 개별적으로 requestAnimationFrame을 호출하면 프레임 드랍이 생깁니다. 모든 렌더링 로직을 메인 틱 루프 하나로 수집하세요.
  • ✓ Device Pixel Ratio (DPR) 상한선 고정: 모바일 고해상도 OLED 디스플레이에서 병목 현상을 방지하기 위해 renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2))를 강제 적용하세요.
  • ✓ 가시성 상태에 따른 백그라운드 일시정지: document.hidden 이벤트 및 IntersectionObserver를 사용해 화면 밖으로 스크롤되었을 때 렌더링 틱을 정지시키세요.
  • ✓ WebGL 자원 명시적 메모리 해제: SPA(Single Page App) 페이지 이동 또는 컴포넌트 언마운트 시 geometry.dispose(), material.dispose(), texture.dispose()를 반드시 호출하세요.
  • ✓ 접근성 가이드라인 준수: 애니메이션에 민감한 사용자를 위해 prefers-reduced-motion: reduce 감지 시 모션을 정지하고 정적 3D 포즈만 표출하도록 구현하세요.

결론 및 종합 제언

ThreeUI 웹 카탈로그를 활용해 감각적인 레퍼런스를 발굴하고, 해당 구조를 명세한 MengTo Agent Skills의 SKILL.md 플레이북을 Claude Code 환경에 연결하는 흐름은 웹 3D 개발 속도를 획기적으로 향상시킵니다.

Claude Code에 작업을 지시할 때는 단순한 설명보다 **스킬 명세서 참조, 세부 파라미터 제어값, 프레임 최적화 및 메모리 해제 조건**을 패키지로 제공하는 것이 완벽한 생산성을 보장합니다.

댓글

댓글 쓰기

이 블로그의 인기 게시물

정부 무료 공공데이터 종류 총정리 & Python API 실전 호출 연동 가이드

이미지
  정부 무료 공공데이터 종류 총정리 & Python API 실전 호출 연동 가이드 "아이디어는 있는데 활용할 데이터가 없다고요?" 정부와 지자체가 무료로 제공하는 11,000개 이상의 공공데이터(Open API)를 활용하면 상권 분석, 부동산 추이, 날씨 연동 앱 등 수많은 서비스를 직접 구축할 수 있습니다. 카테고리별 공공데이터 종류부터 파이썬(Python)으로 상권 API를 연동하는 실전 코드 까지 한 번에 정리해 드립니다. 📌 목차 1. 수익화에 유용한 대표 공공데이터 6가지 분류 2. [실전 코드] Python으로 상권 정보 API 호출 & 데이터 파싱하기 3. API 연동 시 필수 주의사항 (디코딩 인증키 오류 해결) 4. 공공데이터 + AI(Claude/ChatGPT) 서비스 자동화 아이디어 5. 공공데이터포털 API 신청 3단계 절차 ✍️ 운영자 노트 저는 기상 데이터를 다루는 일을 하고 있어서 공공데이터포털의 기상청 API를 실무에서 꾸준히 씁니다. 처음 신청했을 때 가장 오래 헤맨 지점이 아래 3번의 Encoding/Decoding 인증키 구분 이었습니다 — 에러 메시지는 키가 등록되지 않았다고 나오는데, 실제 원인은 키 종류를 잘못 고른 것이었습니다. 같은 곳에서 시간을 버리지 않도록 트러블슈팅 섹션을 꼭 확인하세요. 1. 주요 공공데이터 종류 및 대표 Open API 공공데이터포털(data.go.kr)에서 다룰 수 있는 수천 가지 데이터 중,...
자세한 내용 보기

말 대신 화면을 녹화하면 AI가 그대로 따라합니다: 클로드(Claude) 화면 녹화 스킬 & Chrome 연동 가이드

이미지
  말 대신 화면을 녹화하면 AI가 그대로 따라합니다: 클로드(Claude) 화면 녹화 스킬 & Chrome 연동 가이드(2026.7월 기준 macOS만 가능) 복잡한 프롬프트 작성 없이 화면 작업 과정을 녹화하기만 하면 클로드가 스스로 웹을 조종해 반복 업무를 자동화합니다. 구체적인 설치부터 실전 활용 방법까지 정리했습니다. ✍️ 운영자 노트 이 블로그의 운영 작업(설정 변경·게시·검증) 상당 부분을 실제로 클로드 + Chrome 연동으로 처리하고 있습니다. 브라우저를 직접 조종하는 방식은 확실히 강력하지만, 화면 녹화(Record a Skill) 스킬 자체는 글 작성 시점 기준 macOS 전용 입니다. 윈도우 사용자는 아래 '함께 보면 좋은 글'의 윈도우 대안 정리를 먼저 확인하세요. 💡 어떤 업무를 스킬로 만들면 좋을까? (3가지 기준) 모든 일을 녹화할 필요는 없습니다. 다음 3가지 조건에 부합하는 업무일수록 자동화 효과가 극대화됩니다. 자주 반복하는 일: 매일/매주 정기적으로 수행하는 데이터 수집 및 정리 작업 직접 커넥터 연결이 안 되는 서비스: API나 전용 연동 도구가 없는 외부 웹사이트 활용 업무 글로 설명하기 어려운 일: 프롬프트로 조건과 순서를 일일이 기재하기 복잡한 마우스 클릭·타이핑 작업 🛠️ 사전 설치 및 설정 방법 step-by-step 1. 클로드 데스크톱(Claude Desktop) 앱 설정 클로드 데스크톱 앱 실행 후 좌측 메뉴에서 사용자 지정(Custom) 클릭 스킬(Skills) 탭 선택 후 우측 상단의 추가(Add) 클릭 메뉴 중 화면 녹화(Record...
자세한 내용 보기

Claude Code 하나로 논문 작성부터 심사까지: academic-research-skills 완벽 가이드

이미지
  Academic AI Tool Claude Code 하나로 논문 작성부터 심사까지: academic-research-skills 완벽 가이드 AI 환각을 차단하고 연구 생산성을 극대화하는 대학원생·연구원 필수 라이브러리 논문 작성 시 AI를 활용할 때 가장 두려운 순간은 "존재하지 않는 가짜 인용(Hallucination)" 이나 "기계가 쓴 듯한 진부한 문체" 때문일 것입니다. 오늘 소개할 Imbad0202/academic-research-skills 는 단순한 AI 자동 글쓰기 도구가 아닙니다. 연구자가 주도권을 쥐고 AI를 '학술 전문가 파트너'로 활용하도록 설계된 Claude Code 전용 프레임워크 입니다. 1. 왜 이 라이브러리를 써야 할까? 이 툴은 2026년 최신 연구 지표와 학술적 가이드라인을 반영하여 개발되었습니다. 핵심 철학은 "AI는 코파일럿(보조)이지, 필럿(주도자)이 아니다" 입니다. 엄격한 인용 검증 (Claim Audit): 논문에 포함된 인용 출처가 실제 주장과 일치하는지 3단계 앵커로 실시간 검증합니다. 개인 맞춤형 문체 학습 (Style Calibration): 기존에 본인이 작성했던 논문 어조를 학습하여 AI 특유의 상투적인 문체를 제거합니다. 다단계 동료 심사 모의 테스트 (Peer Reviewer): 제출 전 논문의 논리적 허점, 과장된 주장, 근거 부족을 미리 찾아냅니다. 전 과정 통합 관리: 연구 기획 → 문헌 조사 → 작성 → 검토 → 최종 출력(DOCX/PDF)을 원스톱 처리합니다. ✍️ 운영자 노트 — 논문을 쓰고 심사하는 입장에서 저는 대기과학 분야에서 실제로 논문을 쓰고 국제 학술지 심사(리뷰)에도 참여...
자세한 내용 보기