Machine Skill의 기능
Machine Skill은 Claude Code를 위한 오픈 소스 Agent Skill입니다. 한 줄로 기계를 설명하면 Claude가 실제 장치를 조사한 후, 하나의 HTML 파일 안에 사실적인 대화형 3D 시뮬레이션을 생성합니다.
생성된 페이지는 메커니즘, 엔진, 기기, 산업 장비를 표현할 수 있습니다. 절차적으로 생성된 three.js 형상, 실제 비율, 이름이 지정된 구성 요소, 재질, 대화형 모드, 그리고 해당 기계에 적합한 간단한 물리 솔버를 사용합니다. 결과 HTML 파일을 브라우저에서 열어 부품을 살펴보고, 작동 조건을 변경하고, 내부를 절개하거나, 계산된 고장 조건에서 파손시킬 수 있습니다.
이 프로젝트에는 생성된 페이지에서 반복 가능한 영상, 스크린샷, 소셜 미디어 형식을 제작할 수 있는 레코더도 포함되어 있습니다.
주요 기능
- 사실적인 기계 구성: 모델에는 실제 치수, 이름이 지정된 부품, 솔리드 구성 요소, 블레이드, 기어, 볼트, 파이프 및 기타 절차적 형상이 포함됩니다.
- 물리 기반 동작: Brayton 사이클, 로켓 노즐, 펌프 곡선, 비틀림 진동자, Darcy, Kienzle 모델 등의 솔버가 움직임과 표시 값을 구동합니다.
- 대화형 프레젠테이션: 페이지에서 드래그, 일시 정지, 실시간 라벨, 슬로 모션, 분해도, 엑스레이 뷰, 솔리드 절단면이 있는 절개도를 지원합니다.
- 스튜디오급 렌더링: 런타임에서 재질, 조명, 그림자, 앰비언트 오클루전, 블룸, 열 발광, 프레젠테이션 환경을 제공합니다.
- 결정론적 영상: 필름 모드를 사용하면 레코더가 시뮬레이션을 프레임 단위로 진행하므로 반복 촬영 시 일관된 결과를 렌더링할 수 있습니다.
- 빌드 단계 불필요: 생성된 페이지는 인라인 런타임과 고정된 three.js 0.170 CDN 의존성을 사용하는 독립 실행형 HTML 파일입니다.
요구 사항
기계를 제작하려면 Claude Code를 설치하거나 Agent Skills를 지원하는 다른 호스트를 사용하세요. 생성된 페이지를 실행하려면 최신 데스크톱 버전의 Chrome, Safari, Firefox 또는 Edge처럼 WebGL 2를 지원하는 브라우저를 사용하세요.
스크린샷과 영상을 제작하려면 Node 18 이상, Playwright, Chromium, ffmpeg도 필요합니다.
npm i -D playwright
npx playwright install chromium운영 체제의 패키지 관리자를 통해 ffmpeg를 설치하세요. 휴대폰에서도 더 가벼운 페이지를 실행할 수 있지만, 복잡한 시뮬레이션은 실제 GPU가 탑재된 최신 컴퓨터에서 가장 원활하게 작동합니다.
Machine Skill 설치
권장 설치 방법은 skills CLI를 사용해 저장소를 Claude Code 스킬로 설치하는 것입니다.
npx skills add AirsupHQ/machine-skill -g -a claude-code전역 설치 시 스킬은 ~/.claude/skills/machine에 배치됩니다. 현재 프로젝트에만 설치하려면 전역 및 에이전트 옵션을 생략하세요.
npx skills add AirsupHQ/machine-skill이 프로젝트 설치 방식에서는 스킬이 .claude/skills/machine에 배치됩니다. 저장소를 직접 복제할 수도 있습니다.
git clone https://github.com/AirsupHQ/machine-skill.git ~/.claude/skills/machine
# 또는 하나의 프로젝트에 설치
git clone https://github.com/AirsupHQ/machine-skill.git .claude/skills/machineClaude Code는 일반적으로 실행 중인 세션에서 새 스킬을 감지합니다. 세션이 시작될 때 skills 디렉터리가 존재하지 않았다면 /reload-skills를 실행하세요.
첫 번째 기계 생성
설치가 끝나면 Claude Code를 열고 구체적인 설명과 함께 /machine 명령을 사용하세요.
/machine a mechanical watch movement, the escapement tickingClaude는 watch.html과 같은 HTML 페이지를 생성합니다. WebGL 2 브라우저에서 파일을 열고 시뮬레이션과 상호 작용하세요. 생성된 기계에 따라 뷰를 드래그하고, 라벨을 살펴보고, 조립체를 분해하거나, 내부를 절개하거나, 모델링된 고장 동작을 실행할 수 있습니다.
사용할 수 있는 다른 프롬프트는 다음과 같습니다.
/machine a hydroelectric Francis turbine/machine a Swiss lever escapement, slowed down so I can see the impulse/machine the gearbox of a 5 MW wind turbine, cut open/machine a steam locomotive's valve gear, and give me a 30 second video for X
더 나은 기계 프롬프트 작성
프롬프트에 Claude가 대상 객체를 조사하고 유용한 작동 지점을 선택할 수 있을 만큼 충분한 공학적 맥락을 제공할 때 Machine Skill이 가장 잘 작동합니다.
- 실제 기계의 이름을 지정하세요. “제트 엔진”보다 “787에 장착된 것과 같은 터보팬”이라는 프롬프트가 더 구체적인 방향을 제시합니다.
- 동작과 고장 동작을 지정하세요. 무엇이 움직이고 무엇이 파손되어야 하는지 설명하세요. 예를 들어 엔진 밸브가 뜰 때까지 엔진 회전수를 높여 달라고 요청할 수 있습니다.
- 사용 목적을 설명하세요. 출력물이 임베디드 페이지, 소셜 영상, 정지 이미지 중 어떤 용도인지 Claude에 알려 주세요. 영상이라면 원하는 화면 비율이나 길이도 포함하세요.
생성되는 물리는 CFD나 FEA가 아니라, 실제 현상을 정직하게 단순화한 소규모 모델입니다. 각 페이지는 무엇을 계산하고 무엇을 단순화했는지 설명하므로, 표시 값은 공인된 공학 결과가 아닌 교육 및 예시용으로 활용하세요.
영상 녹화
저장소의 record.mjs 스크립트를 사용해 생성된 페이지를 동영상 파일로 렌더링하세요.
node ~/.claude/skills/machine/scripts/record.mjs watch.html out/watch.mp4 --music freepd:Classical/Easy_Lemon복제한 저장소에서 작업할 때는 로컬 스크립트 경로를 사용하세요.
node scripts/record.mjs examples/turbofan.html out/turbofan.mp4 --music freepd:Classical/Easy_Lemon출력 크기를 설정하면 피드용 세로 영상을 만들 수 있습니다.
node scripts/record.mjs examples/turbofan.html out/turbofan-feed.mp4 --w 1080 --h 1350동영상 대신 선택한 정지 프레임을 내보내려면 출력 디렉터리와 프레임 번호를 지정하세요:
node scripts/record.mjs examples/turbofan.html out/stills --stills 3,9,14,19레코더는 추가 렌더링 제어 기능을 지원합니다. 슈퍼샘플링에는 --ss 1.5, 모션 블러에는 --blur 2, 빠른 움직임에는 --fps 60을 사용하세요. 음악은 로컬 파일, URL 또는 FreePD의 freepd:<Category>/<Name> 트랙을 사용할 수 있습니다.
생성된 페이지는 ?film=1&shot=main과 같은 쿼리 매개변수를 사용해 결정론적 필름 모드로 실행할 수 있습니다. 이 모드에서는 레코더가 시간을 진행할 때만 시간이 흐르므로 모든 프레임이 완전히 렌더링되고 반복 촬영 결과도 일관되게 유지됩니다.
렌더링된 출력 확인
Machine Skill에는 헤드리스 렌더링 실패를 방지하는 안전장치가 포함되어 있습니다. 레코더는 스크린샷에서 단색 마젠타 프레임을 확인하며, pinkscan.mjs로 완성된 동영상을 검사할 수도 있습니다.
node scripts/pinkscan.mjs out/*.mp4분홍색 프레임이 감지되면 명령이 0이 아닌 상태 코드로 종료되므로 자동화된 워크플로에 사용할 수 있습니다.
저장소 살펴보기
SKILL.md는 품질 기준, 조사 및 모델링 워크플로, 비평 라운드, 필름 제작 과정, 화면 문구 스타일을 정의합니다.kit/lab-kit.js는 생성된 페이지에 인라인으로 삽입되는 런타임입니다. 스튜디오, 후처리, 재질, 기하 도우미, 라벨, 효과, 상호작용 모드, 필름 타임라인을 포함합니다.kit/template.html은 수동으로 기계를 제작할 때 사용하는 시작 페이지 템플릿입니다.references/solvers.md에는 가스터빈, 로켓, 피스톤 엔진, 펌프, 로터, 전기 기계와 같은 기계를 위한 물리 공식과 실제 상수가 포함되어 있습니다.scripts/에는 스크린샷, 녹화, 분홍색 프레임 검사, 런타임 인라이닝 도구가 들어 있습니다.examples/에는 터보팬, 로켓 엔진, 공정 펌프, 압축기를 포함한 독립 실행형 HTML 데모가 들어 있습니다.film/launch.html은 발사 필름에 사용되는 디렉터 페이지입니다.
인터랙티브 절개 이해하기
절개 시스템은 닫힌 솔리드와 클리핑 평면을 사용합니다. 평면이 솔리드를 열면 런타임이 단면 표면을 감지하고 재질의 가공된 외관과 은은한 해칭이 적용된 솔리드 단면을 렌더링합니다. 단면 깊이가 올바르게 기록되므로 별도의 캡 메시 없이도 절개면이 다른 기하를 가릴 수 있습니다.
이를 통해 모델 내부에서 절단 위치를 이동하면서 설득력 있는 금속 또는 재질 표면을 유지할 수 있습니다. 동일한 런타임은 반단면과 사분단면, 엑스레이 표현, 폭발 조립도, 라벨, 흐름 줄무늬, 플룸, 불꽃, 강체 파편도 지원합니다.
다른 에이전트 호스트에 맞게 워크플로 조정
Machine Skill은 표준 Agent Skill로 패키징되어 있습니다. Claude.ai 또는 Claude 데스크톱 앱에서는 스킬 폴더를 압축한 뒤 Settings, Capabilities, Skills에서 업로드할 수 있습니다. Claude Agent SDK 또는 API에서는 해당 폴더를 스킬 디렉터리로 마운트하세요. 다른 Agent Skills 호환 도구에서는 SKILL.md를 직접 지정할 수 있습니다.
에이전트를 사용하지 않는다면 kit/template.html을 복사하고 각 섹션을 직접 작성하세요. 생성된 페이지는 브라우저에서 실행되는 일반 HTML 파일로 유지됩니다.
제한 사항 이해하기
- 이 스킬은 기계, 메커니즘, 엔진, 계측기, 장치를 대상으로 합니다. 사람, 풍경, 지도는 적합성이 낮은 사용 사례입니다.
- 기하는 절차적으로 생성되는 three.js 콘텐츠입니다. 제조 공차나 CAD 내보내기 정밀도가 아니라 정확한 비율과 부품 수를 목표로 합니다.
- 물리 모델은 의도적으로 작고 투명하게 구성되어 있습니다. 공개 자료와 대조해 확인하지만 CFD, FEA 또는 인증된 공학 해석을 대신할 수는 없습니다.
- 복잡한 페이지에는 약 600,000개의 삼각형이 포함될 수 있으며, 그림자, 앰비언트 오클루전, 블룸을 부드럽게 유지하려면 최신 노트북 GPU가 필요할 수 있습니다.
결론
Machine Skill은 간결한 공학 프롬프트를 실제 비율, 계산된 동작, 프레젠테이션 수준의 렌더링을 갖춘 탐색 가능한 브라우저 시뮬레이션으로 바꿉니다. skills CLI로 설치하고, 명확한 움직임과 고장 요구 사항을 포함해 구체적인 기계를 설명한 다음 생성된 HTML 페이지를 여세요. 게시할 준비가 되면 결정론적 레코더를 사용해 동일한 시뮬레이션에서 동영상이나 정지 이미지를 제작할 수 있습니다.