claude.ai/design(클로드 디자인)을 떠받치는 디자인 방법론을, 웹사이트·구독·업로드 없이 내 컴퓨터에 이미 깔린 코딩 에이전트(Cursor·Claude Code·Codex 등) 안에서 그대로 돌릴 수 있게 재포장한 Agent Skill(에이전트 스킬)이다. 빌드 단계도, 런타임도 없다. 그저 마크다운 프롬프트 + 약간의 JSX 스캐폴드 묶음이며, 에이전트가 이 글들을 읽어 UI 목업·인터랙티브 프로토타입·와이어프레임·랜딩 페이지·대시보드·슬라이드 덱을 모두 자기완결형 HTML로 뽑아낸다. (저장소: JimLiu/baoyu-design · MIT 라이선스 · 70개 이상 에이전트 지원 · "Opus 4.8과 함께 쓸 때 최고" 배지)이 레포가 무엇을 하는 물건인가.
보통 클로드로 UI를 디자인하려면 claude.ai/design 웹사이트에 접속해, 요청을 적고, 결과물을 받아 내려받아야 한다. baoyu-design은 그 사이트가 내부적으로 쓰는 "디자인 방법론 + 장인정신 기준 + 출력 형식"을 전부 글(마크다운)로 적어, 내 컴퓨터의 코딩 에이전트가 읽고 그대로 따라 하게 만든다.
핵심은 "프롬프트 모음"이 아니라 스킬(skill)이라는 잘 짜인 구조다. 에이전트는 진입점 SKILL.md를 읽고 → 핵심 방법론 system-prompt.md를 로드하고 → 자신이 어떤 환경(Cursor/Claude Code/Codex)에서 도는지 감지해 맞는 도구 맵 문서만 골라 읽고 → 작업에 필요한 세부 스킬(덱·모바일·임포트 등)만 그때그때 끌어온다.
baoyu-design은 에이전트 스킬(Agent Skill)의 한 사례다. 빌드도 의존성 설치도 없이, 32개(2026-06 기준)의 내장 스킬(built-in skills)과 9개의 스타터 컴포넌트(starter components), 그리고 Figma .fig 파일을 완전 오프라인으로 디코딩하는 Node.js 도구들로 이루어져 있다. 산출물은 항상 designs/<프로젝트>/ 폴더에 자기완결형 HTML로 떨어져, 버전 관리·포크·내보내기·배포가 모두 가능하다. 메인테이너는 중화권에서 유명한 AI 콘텐츠 큐레이터 Jim Liu(宝玉)이며, Anthropic과 무관한 독립 커뮤니티 프로젝트다.
SKILL.md 진입점과 YAML 프론트매터의 description 인데, 에이전트는 이 설명을 보고 "지금 이 스킬을 써야 할 때인가"를 스스로 판단해 자동 발동한다. baoyu-design은 이 형식으로 "전문 디자이너의 두뇌"를 통째로 담았다.save-as-standalone-html 스킬이 전부를 한 파일로 인라인한다.트렌딩 이유 · 웹 서비스/일반 프롬프트 대비 장점.
요즘 "스킬"이 폭발적으로 늘고 있지만, baoyu-design이 두드러지는 이유는 "아주 무겁고 잘 만들어진 진짜 제품의 능력"을 거의 손실 없이 로컬로 옮겼다는 점이다. 첫째 웹사이트에서 해방(구독·업로드 불필요), 둘째 하니스 독립(harness-agnostic) 설계로 70개 이상 에이전트에서 작동, 셋째 "포인팅으로 수정하는" 시각적 2차 편집 루프, 넷째 Figma .fig 오프라인 디코딩·GitHub·HTML 임포트까지 갖춘 점이다.
| 비교 항목 | claude.ai/design (웹) | 그냥 프롬프트 붙여넣기 | baoyu-design (스킬) |
|---|---|---|---|
| 실행 위치 | 웹사이트(별도 구독) | 채팅창 | 내 에디터/에이전트 |
| 산출물 소유 | 웹에서 다운로드 | 채팅에 흩어짐 | 내 레포 designs/에 저장·버전관리 |
| 방법론 깊이 | 완전(내부 프롬프트) | 사용자 역량 의존 | 270줄(2026-06 기준) system-prompt + 32개 스킬 |
| 수정 루프 | 웹 UI에서 | 말로만 설명 | 라이브 프리뷰 요소를 가리켜 수정 |
| 임포트 소스 | 제한적 | 없음 | Figma .fig·GitHub·HTML/CSS |
| 환경 지원 | 웹 전용 | 모든 LLM | Cursor·Claude Code·Codex + 70여 종 |
첫째, 한 덩어리 프롬프트는 환경별 차이를 다룰 수 없다. "사용자에게 질문하기"·"미리보기"·"스크린샷"은 Cursor·Claude Code·Codex에서 호출하는 도구 이름이 전부 다르다. 거대한 프롬프트 하나에는 이 분기가 들어갈 자리가 없다. 둘째, 모든 능력을 한 번에 컨텍스트에 욱여넣으면 토큰이 폭발한다. 덱 만들기·Figma 임포트·PPTX 내보내기를 매번 다 읽으면 정작 디자인할 여력이 없다.
① 장인정신(craft)은 하니스 독립으로 system-prompt.md에 모으고, 환경별 도구 이름만 references/<harness>.md로 분리했다. 에이전트는 자기 환경에 맞는 도구 맵 1개만 읽는다. ② 32개(2026-06 기준) 능력을 전부 로드하지 않는다. SKILL.md가 작업을 보고 "지금 필요한 내장 스킬만" built-in-skills/에서 끌어온다. "변하는 부분은 따로, 안 변하는 핵심만 항상 로드"라는 점진적 공개(progressive disclosure)가 설계 철학이다.
"코드"보다 "프롬프트"가 핵심 자산인 특이한 스택.
baoyu-design의 진짜 소스 코드는 마크다운으로 쓴 프롬프트다. 빌드 단계도 런타임도 없다(README: "plain Markdown plus a few JSX/JS scaffolds — no build step, no runtime"). 즉 "실행 파일이 아니라 '읽혀서 실행되는 글'"이 본체다.
| 요소 | 역할 |
|---|---|
SKILL.md | 진입점. 전체 흐름을 오케스트레이션. YAML description으로 자동 발동. |
system-prompt.md | 디자인 방법론·장인정신 기준의 단일 진실원(270줄, 2026-06 기준). 하니스 독립. |
built-in-skills/*.md | 32개(2026-06 기준) 특화 프롬프트(덱·모바일·임포트·내보내기·디자인시스템 등). |
references/*.md | Claude Code·Cursor·Codex 각각의 도구 이름 맵. |
| YAML frontmatter | 각 .md 상단의 name/description — 스킬 발견·라우팅의 메타데이터. |
에이전트가 매번 기본 골격을 손으로 다시 짜지 않도록, starter-components/에 9개의 재사용 스캐폴드를 둔다. 디바이스 프레임·덱 무대·애니메이션 엔진 등이다.
| 요소 | 역할 |
|---|---|
ios-frame.jsx / android-frame.jsx | iOS·Android 기기 목업 프레임. |
macos-window.jsx / browser-window.jsx | macOS 창·브라우저 창 크롬(chrome). |
deck-stage.js | 슬라이드 덱 무대 — 키보드 내비·자동 스케일·발표자 노트·인쇄(PDF)·썸네일 레일까지 갖춘 웹 컴포넌트. |
design-canvas.jsx | 여러 디자인 옵션을 나란히 놓는 팬·줌 캔버스(<DCArtboard>). |
animations.jsx | 타임라인 애니메이션 엔진(영상형 HTML용). |
tweaks-panel.jsx / image-slot.js | 실시간 조절 패널 · 채울 수 있는 이미지 슬롯. |
임포트·디자인시스템 컴파일 같은 "프로그래밍이 필요한" 일은 agents/*.mjs Node 스크립트가 맡는다. 외부 의존성 없이 돌도록 React·Babel·압축 라이브러리를 agents/vendor/에 직접 넣어 뒀다(vendoring).
| 요소 | 역할 |
|---|---|
import-figma.mjs | Figma .fig를 오프라인 디코딩(계정·API·MCP 불필요). outline/mount/materialize/render/design-system 5개 서브커맨드. |
import-design-system.mjs | 디자인 시스템을 _ds/<slug>/로 자기완결 복사 + _d_meta.json 바인딩 기록. |
compile-design-system.mjs / check-design-system.mjs | 디자인 시스템 토큰·컴포넌트 번들링 / 읽기전용 검증기. |
build-preview.mjs | 디자인 시스템을 1파일 인터랙티브 preview.html로 컴파일(Shadow DOM 격리). |
record-asset.mjs | 산출물을 _d_meta.json에 자산으로 인덱싱(검토 상태 추적). |
vendor/ | react/react-dom 18.3.1 · babel.min.js · fflate(압축) · fig-materialize(kiwi 스키마 디코더). |
lib/ + tests/ | ds-core·asset-store·ds-prompt 라이브러리 + node --test 단위 테스트. |
AskUserQuestion vs AskQuestion). baoyu-design의 핵심 설계 과제가 바로 "이 차이를 어떻게 한 스킬로 흡수하나"였다.요청 → 스킬 로드 → 질문 → HTML 생성 → 미리보기·검증, 그리고 스킬 설계 패턴.
사용자가 "명상 앱 설정 화면을 디자인해 줘"라고 말하면, baoyu-design은 코드가 아니라 문서들의 연쇄 로딩으로 작동한다. 핵심은 "항상 읽는 것(코어)"과 "필요할 때만 읽는 것(세부)"의 분리다. 이 구조 덕분에 32개(2026-06 기준) 능력이 있어도 컨텍스트는 가볍게 유지된다.
system-prompt.md는 결코 구체적 도구 이름을 부르지 않는다. 대신 "당신의 Ask-Question 도구를 써라", "당신의 하니스 문서대로 미리보기하라"처럼 '능력(capability)'으로만 지시한다. 그 능력을 실제 함수로 매핑하는 표는 references/<harness>.md에만 있다. 추상화의 교과서다.
| 웹(claude.ai) 도구 | Claude Code 대응 |
|---------------------|---------------------------|
| questions_v2 | AskUserQuestion |
| show_to_user | SendUserFile + Preview MCP |
| write_file | Write |
| copy_files | Bash cp |
| eval_js | Bash / preview_eval |
| invoke_skill("X") | Read built-in-skills/X.md |핵심 통찰: "안 변하는 작업 방법(craft)"은 한 곳에, "환경마다 다른 도구 이름"은 분리. 새 하니스를 지원하려면 references/에 매핑 표 1개만 추가하면 된다 — 270줄(2026-06 기준) 방법론은 한 글자도 안 건드린다.
32개(2026-06 기준) 내장 스킬을 항상 다 읽으면 컨텍스트가 폭발한다. baoyu-design은 SKILL.md의 라우팅 규칙으로 "이번 작업에 필요한 스킬만" 끌어온다. 와이어프레임 요청 → wireframe.md, .fig 첨부 → import-from-figma.md, 기본 → hi-fi-design.md + interactive-prototype.md.
| 사용자 신호 | 로드되는 내장 스킬 |
|---|---|
| "와이어프레임 / 로파이로" | wireframe.md |
| 디자인 시스템 만들기/임포트 | design-system-authoring-guide.md + 보조 |
로컬 .fig 파일 첨부 | import-from-figma.md → import-figma.mjs |
| GitHub 레포를 소스로 | import-from-github.md (gh api로 트리 탐색) |
| 덱 / 모바일 / 애니메이션 | make-a-deck / mobile-prototype / animated-video |
| 기본(특별 신호 없음) | hi-fi-design.md + interactive-prototype.md |
한 번 디자인 시스템을 고르면, 에이전트는 그것을 _ds/<slug>/에 버전 고정 자기완결 복사본으로 가져오고, 바인딩을 _d_meta.json에 적는다. 이후 모든 화면은 그 시스템의 실제 토큰·타입·간격·컴포넌트로만 짜이고, 에이전트는 시스템 밖 색을 임의로 만들지 못한다("binding visual contract"). 프로젝트를 다시 열면 _d_meta.json을 읽어 자동 복원한다.
baoyu-design을 "신입 디자이너에게 건네는 업무 매뉴얼 바인더"로 생각하자. 맨 앞 표지(SKILL.md)에 "어떤 일이 들어오면 어느 챕터를 펴라"가 적혀 있고, 1장(system-prompt.md)은 회사 어디서든 통하는 디자인 철학이다. 사무실마다 다른 복사기·프린터 사용법은 부록(references/)으로 빼 놓았다. 신입은 표지를 보고 필요한 챕터만 펴서 읽는다 — 600쪽 바인더를 통째로 외울 필요가 없다. 이것이 점진적 공개다.
핵심은 skills/baoyu-design/ 한 폴더에 다 있다.
① SKILL.md로 "어떻게 라우팅되나" 파악 → ② system-prompt.md로 "디자인 장인정신의 실체"(React+Babel 규칙·이름 충돌 금지·디자인시스템 바인딩) → ③ references/claude.md로 "능력 → 도구" 매핑 실물 → ④ built-in-skills/hi-fi-design.md 한 개로 세부 스킬의 톤 → ⑤ CHANGELOG.md로 "왜 이렇게 설계했나"의 의사결정 맥락. 스킬 설계의 통찰은 ①②⑤에 거의 다 있다.
"좋은 에이전트 스킬"을 어떻게 설계하는가.
가장 큰 교훈은 "한 번에 다 읽히지 말 것"이다. LLM의 컨텍스트 창은 한정돼 있고, 무관한 지식을 잔뜩 채우면 추론 품질이 떨어진다(haystack 문제). baoyu-design은 "항상 필요한 코어(SKILL+system-prompt)"와 "가끔 필요한 세부(32개 built-in)"를 나누고, 진입점이 라우팅 규칙으로 필요한 것만 끌어오게 한다. 당신이 스킬을 만들 때 그대로 베낄 수 있는 패턴이다.
SKILL.md(진입+라우팅) + 세부 .md 3개로 쪼개고, "어떤 신호일 때 어느 세부를 읽는지"를 표로 명시하라.system-prompt가 AskUserQuestion이라는 구체 이름을 부르지 않고 "당신의 Ask-Question 도구"라고만 쓰는 것이 핵심이다. 이렇게 '무엇을 한다(능력)'와 '어떻게 부른다(구현)'를 분리하면, 새 환경 지원이 "매핑 표 추가"로 끝난다. 소프트웨어 공학의 의존성 역전(DIP)·어댑터 패턴을 프롬프트에 적용한 셈이다.
references/ 표로 빼라. 본문이 환경 독립이 되는지 확인.baoyu-design은 만든 HTML을 그냥 두지 않고 record-asset.mjs로 _d_meta.json에 등록한다 — 파일 경로·버전·검토 상태(approved/changes-requested)·디자인시스템 바인딩까지. 덕분에 프로젝트를 다시 열어도 "어디까지 했고 무슨 시스템을 썼는지"가 복원된다. "에이전트가 만든 것을 추적 가능한 상태로 남긴다"는 발상이 배울 점이다.
meta.json(파일명·생성시각·상태)에 기록하는 10줄짜리 Node 스크립트를 짜고, "다시 실행 시 기존 항목 갱신 vs 새로 추가"를 구분하라..fig 디코딩에 React·Babel·압축 라이브러리가 필요한데, baoyu-design은 이를 npm install로 받지 않고 agents/vendor/에 코드 자체를 넣어 뒀다(vendoring). 그래서 인터넷·패키지 매니저 없이도 작동한다. 오프라인·재현성이 중요한 도구에서 흔히 쓰는 전략이며, "의존성을 외부에 맡기지 않는다"는 트레이드오프를 보여 준다.
node_modules 대신 단일 파일로 vendor/에 넣고 상대경로 import로 돌려 보라. 장점(이식성)과 단점(업데이트 부담)을 적어 보라."무엇을 깔까"보다 "어떤 에이전트·모델을 쓰나"가 핵심.
| 항목 | 요구사항 |
|---|---|
| 코딩 에이전트(필수) | Cursor · Claude Code · Codex 중 하나(1급 지원), 또는 70여 종 파일 가능 에이전트(Cline·Roo Code·Copilot 등). |
| 모델(권장) | Claude Opus 4.8 — 스킬 자체가 길고 까다로운 디자인 브리프라 모델이 강할수록 결과가 좋음(README의 "Best with Opus 4.8" 배지). |
| Node.js | npx skills 설치 및 agents/*.mjs 실행용. |
| Python 3 (선택) | 로컬 미리보기 서버(python3 -m http.server 4311 --directory designs). |
| 설치(권장) | npx skills add JimLiu/baoyu-design — 에이전트 자동 감지(.claude/skills/ 또는 .agents/skills/). -g로 전역 설치. |
| 설치(대안) | 설치 없이 레포 URL을 채팅에 붙여 넣고 "이 SKILL.md를 따라 …해 줘"로 1회성 사용. |
| 빌드/런타임 | 없음. 마크다운 + JSX 스캐폴드라 빌드 단계 자체가 불필요. |
skills/<name>/를 찾아, 현재 어떤 코딩 에이전트를 쓰는지 자동 감지해 알맞은 폴더에 스킬을 떨어뜨리는 설치 도구. baoyu-design의 권장 설치 경로이며, --agent claude-code처럼 대상을 명시하거나 --list로 내용을 먼저 볼 수도 있다.난이도별 5단계 — 스킬을 "쓰는 법"과 "만드는 법" 둘 다.
본인 에이전트에 npx skills add JimLiu/baoyu-design로 설치한 뒤, "명상 앱 설정 화면 하이파이 변형 3개를 디자인해 줘"라고 요청한다. 에이전트가 어떤 명료화 질문을 던지는지, 산출물이 designs/ 어디에 떨어지는지 관찰하라.
SKILL.md의 "step 3"을 읽고, "어떤 사용자 신호 → 어떤 built-in-skills/*.md 로드"를 표 또는 흐름도로 직접 그려 본다. 그다음 "와이어프레임으로 빠르게"라고 요청해 정말 wireframe.md 경로로 가는지 확인.
system-prompt.md에서 "your Ask-Question tool"·"per your harness doc" 같은 추상 표현을 모두 찾아 목록화하고, references/claude.md의 매핑 표와 짝지어 본다. 그런 다음 가상의 새 하니스용 references/myagent.md를 한 장 직접 작성해 본다(매핑만 채우면 됨).
baoyu-design의 구조를 본떠, 본인 작업(예: "릴리스 노트 작성")을 스킬로 만든다. SKILL.md(YAML description + 라우팅) + system-prompt격 본문 + 세부 .md 2~3개로 쪼개고, 점진적 공개와 능력/구현 분리를 의식적으로 적용하라.
아무 Figma 커뮤니티 키트를 .fig로 받아 node agents/import-figma.mjs outline <file>로 인벤토리를 뽑고, materialize/design-system까지 돌려 본다. agents/vendor/fig-materialize.mjs가 kiwi 스키마 + zstd/deflate를 어떻게 오프라인 디코딩하는지 코드 흐름을 따라가며 정리한다.
6주 코스 — 스킬을 "쓰는 사람"에서 "설계하는 사람"으로.
| 주차 | 주제 | 실습 · 참고 |
|---|---|---|
| 1주차 | 에이전트 스킬 기초 — SKILL.md·YAML description·자동 발동 | SKILL.md 정독 · 과제 1~2 · Anthropic Agent Skills 문서 |
| 2주차 | 프롬프트 엔지니어링 — 방법론을 글로 명세하기 | system-prompt.md 270줄(2026-06 기준) 분석 · "장인정신 기준"이 어떻게 글이 되나 |
| 3주차 | 점진적 공개 — 컨텍스트 예산·라우팅 설계 | built-in-skills 32개(2026-06 기준) 인덱스 · 라우팅 규칙 도식(과제 2) |
| 4주차 | 추상화·이식성 — 능력/구현 분리, 어댑터 패턴 | references/*.md 3종 비교 · 가상 하니스 매핑 작성(과제 3) |
| 5주차 | 산출물 형식 — React+Babel 멀티파일·디자인시스템 바인딩 | hi-fi-design.md·use-design-system.md · _d_meta.json 구조 |
| 6주차 | 도구 통합 — Node 에이전트 스크립트·벤더링·오프라인 디코딩 | import-figma.mjs·vendor/ · 나만의 미니 스킬 완성(과제 4~5) |
본문·소스에 나온 용어 빠른 참조.
| 용어 | 의미 |
|---|---|
| Agent Skill | 에이전트에게 전문 작업법을 가르치는 마크다운+보조파일 패키지. 진입점은 SKILL.md. |
| SKILL.md | 스킬 진입점. YAML description으로 자동 발동, 본문이 전체 흐름을 라우팅. |
| system-prompt.md | 디자인 방법론·장인정신 기준의 단일 진실원(270줄, 2026-06 기준). 하니스 독립. |
| harness (하니스) | LLM을 감싸 도구·파일·미리보기를 제공하는 실행 환경(Claude Code·Cursor·Codex). |
| harness-agnostic | 특정 하니스에 종속되지 않는 설계. 능력은 추상, 도구 이름은 references/로 분리. |
| progressive disclosure | 점진적 공개. 필요한 세부 지식만 그때그때 로드해 컨텍스트를 아끼는 전략. |
| built-in skills | 32개(2026-06 기준) 특화 프롬프트(덱·모바일·임포트·내보내기·디자인시스템 등). 필요 시만 로드. |
| starter components | 9개 재사용 JSX/JS 스캐폴드(기기 프레임·덱 무대·애니메이션 엔진 등). |
| self-contained HTML | 스타일·스크립트·에셋이 한 묶음에 든 산출물 형식. baoyu-design의 출력. |
| design system (바인딩) | _ds/<slug>/로 가져온 토큰·컴포넌트 묶음. 한 번 묶이면 구속력 있는 시각 계약. |
| _d_meta.json | 프로젝트의 자산·검토상태·디자인시스템 바인딩을 기록하는 메타 파일. |
| .fig 오프라인 디코딩 | Figma 파일을 계정·API 없이 로컬에서 해독(kiwi 스키마+zstd/deflate, import-figma.mjs). |
| vendoring | 외부 의존성을 npm install 대신 코드 자체를 vendor/에 넣어 오프라인·재현성 확보. |
| npx skills | Vercel Labs의 스킬 설치 CLI. 에이전트를 자동 감지해 알맞은 폴더에 설치. |
| React + Babel | 인라인 JSX 프로토타입 표준. 버전·integrity 고정, 멀티파일은 HTTP 미리보기 필수. |
npx skills add JimLiu/baoyu-design)