AI 스킬 만들기 10계명: Figma→Code 자동화 실전기

🔗 원문 전체 보기 → 네이버 D2

요약

이 글에서 예로 든 스킬은 naver/design-to-ui라는 이름의 오픈 소스로 공개되어 있습니다.

들어가며: 같은 모델, 다른 결과

AI 코딩 도구를 쓰다 보면 프롬프트에서 같은 설명을 매번 반복하게 됩니다. "이건 아이콘이니까 에셋으로 받아", "이건 그래프니까 Canvas로 그려", "색상은 하드코딩하지 말고 디자인 토큰을 써" 같은 설명이 그렇습니다. Figma 디자인을 Android 코드로 옮길 때도 마찬가지였습니다.

그래서 Claude의 스킬(Agent Skills) 기능이 공개되자마자 Figma 디자인을 Android UI로 변환하는 스킬을 만들기 시작했습니다. 목표는 프롬프트 한 번으로 완성도 높은 UI를 얻는 것이었습니다.

스킬의 효과는 생각보다 컸습니다. 2026년 3월, 같은 모델(Claude Opus 4.6)과 같은 프롬프트에 Figma Desktop MCP 서버까지 똑같이 쓰고 스킬만 바꿔 화면 하나를 조건마다 한 번씩 변환해 보았습니다. 그 결과는 다음과 같습니다.

colorScheme 참조가 많을수록 색상을 하드코딩하지 않고 디자인 토큰을 썼다는 뜻이고, drawable은 Figma의 아이콘을 실제 에셋 파일로 받아 왔는지를 보여 줍니다. 이 숫자를 어떻게 얻었는지는 계명 10에서 다룹니다.

Figma 공식 스킬이 부족해서 생긴 차이는 아닙니다. 범용 스킬은 프로젝트의 디자인 토큰과 에셋 규칙을 알 수 없고, 맞춤 스킬은 바로 그 공식 스킬 위에 프로젝트 규칙을 얹은 것입니다. 이 방식은 계명 2에서 자세히 다룹니다.

Figma 원본과 세 조건으로 변환한 날씨 화면(오토앱)을 나란히 놓으면 다음과 같습니다. 지역과 날씨 데이터는 Figma 시안의 예시 값이거나 캡처 시점의 실제 값이라 서로 다릅니다.

Figma 원본

그림 1 Figma 원본(위)과 세 조건으로 변환한 날씨 화면(아래)

모델은 같았는데 결과물의 디테일은 확연히 달랐습니다. 예를 들어 '서울시 명동' 옆 위치 아이콘은 맞춤 스킬에서만 제대로 나왔고, 시간별 기온 그래프도 맞춤 스킬에서만 그려졌습니다.

다만 이 스킬을 틈틈이 만드는 데 3개월쯤 걸렸습니다. 이 글에서는 3개월 동안 알게 된 원칙 10가지를 정리했습니다. 처음부터 알았다면 그 시간을 크게 줄일 수 있었을 것입니다. 사내 Engineering Day에서 발표한 내용을 글로 옮기면서 발표에서 다 하지 못한 사례를 더했습니다.

스킬은 무엇이고 프롬프트와 무엇이 다른가

스킬은 특정 작업을 어떻게 해야 하는지 적어 둔 폴더입니다. 폴더에는 SKILL.md 파일이 하나 있고, 필요하면 참고 문서(references/)와 스크립트(scripts/)를 함께 넣습니다. Claude는 평소에는 스킬의 이름과 설명만 알고 있다가, 요청이 그 설명과 맞으면 SKILL.md 본문을 읽어 들여 그 지침에 따라 작업합니다.

프롬프트와의 차이는 세 가지입니다.

• 반복 설명이 사라집니다. 매번 프롬프트에 붙여 넣던 에셋 규칙과 변환 절차를 스킬에 한 번만 적어 두면 됩니다.
• 스크립트를 함께 넣을 수 있습니다. 말로 설명하기 어렵고 결과가 늘 같아야 하는 작업(예: SVG를 VectorDrawable로 변환)은 스크립트로 만들어 두고 Claude가 실행하게 합니다.
• 팀이 같이 키울 수 있습니다. 파일이라 버전 관리가 되고, 플러그인으로 묶어 배포할 수 있습니다.

이 글의 예시는 Claude Code 기준이지만, 같은 스킬 형식(Agent Skills)을 지원하는 다른 에이전트 도구에도 대부분 적용됩니다.

이 글에 자주 나오는 용어를 먼저 정리합니다.

스킬 만들기 10계명

10계명은 사전 점검(1∼2), 본문 설계(3∼7), 검증과 개선(8∼10) 세 단계로 나뉩니다. 각 계명에는 스스로 던져 볼 핵심 질문과 figma-to-android 스킬을 만들며 겪은 실제 사례를 덧붙였습니다.

사전 점검

스킬을 만들기 전에 확인할 것들입니다. 스킬에 무엇을 담을지 직접 해 보며 찾고, 쓸 만한 스킬이 이미 있는지 살펴봅니다.

계명 1. 스킬부터 만들지 마라 — 먼저 직접 해 봐라

핵심 질문: 스킬 없이 해 보면서 무엇을 반복해서 설명했나?

/skill-creator에 원하는 스킬을 설명하면 형식에 맞는 스킬을 금방 만들어 줍니다. 하지만 그보다 먼저 스킬 없이 프롬프트만으로 작업을 해 봐야 합니다. 그러면서 세 가지를 관찰합니다.

• 매번 반복해서 설명하는 정보
• Claude가 놓치는 것
• 사람이 손으로 고쳐 주는 패턴

이 세 가지가 스킬에 들어갈 내용입니다. Anthropic에서 Claude Code를 만드는 Thariq Shihipar도 Lessons from building Claude Code: How we use skills에서 같은 이야기를 합니다. 뻔한 내용은 빼고 Claude의 기본 행동을 바꾸는 정보에 집중하라고 하면서, Anthropic의 좋은 스킬도 대부분 몇 줄짜리 지시와 gotcha 하나로 시작했다고 말합니다.

저는 반대로 했습니다. 처음부터 목표(Figma → Compose)와 필요할 것 같은 자료(Figma와 Compose의 매핑 정보)를 한꺼번에 주고 스킬을 만들어 달라고 했습니다. 그 결과 700줄이 넘는 스킬에서 출발했고, Claude는 긴 지시를 제대로 따르지 못했습니다. 이것이 3개월 동안 가장 큰 병목이었습니다.

그림 2 Compose와 XML을 함께 지원하도록 스킬을 다시 만들 때 쓴 프롬프트

다시 직접 날씨 화면을 변환해 보니 매번 "colorScheme을 써라", "SVG를 VectorDrawable로 변환해라", "기존 drawable이 있는지 확인해라"를 반복하고 있었습니다. 이 세 문장이 스킬의 핵심이 됐습니다.

단, 이미 절차를 잘 아는 워크플로를 스킬로 옮길 때는 "만들어 줘"로 시작해도 괜찮습니다.

계명 2. 기존 스킬 위에 쌓아라 — 바퀴를 재발명하지 마라

핵심 질문: 비슷한 공식 스킬이나 커뮤니티 스킬은 없나?

만들기 전에 비슷한 스킬이 이미 있는지부터 찾아봅니다. 검증된 구조 위에 도메인 특화 부분만 얹는 편이 훨씬 빠르고 안정적입니다.

• anthropics/skills: Anthropic 공식 스킬 저장소
• figma/mcp-server-guide: Figma 공식 스킬과 MCP 가이드
• 사내 스킬 저장소

Figma가 공식 스킬 implement-design을 공개한 뒤에는 그 워크플로를 뼈대로 가져왔습니다. 이 스킬은 2026년 3월 figma-implement-design으로 이름이 바뀌었고 5월에 저장소에서 삭제됐지만, 워크플로를 figma-to-android 안에 옮겨 두었기 때문에 영향은 없었습니다. figma-to-android의 7단계는 Step 1(Node ID 추출), Step 2(디자인 컨텍스트), Step 3(스크린숏), Step 4(에셋 분류), Step 5(에셋 다운로드 및 처리), Step 6(코드 변환), Step 7(검증)입니다.

디자인 컨텍스트를 받아(Step 2) 코드로 옮기는(Step 6) 흐름은 공식 스킬에서 가져온 그대로이고, 그 위에 Android 에셋 파이프라인, 에셋 A/B/C 분류, Canvas 변환, 디자인 시스템 토큰 매핑만 얹었습니다. 그 결과 유지 보수 비용이 크게 줄었습니다.

본문 설계

SKILL.md와 참고 문서를 어떻게 구성하고 무엇을 적을지에 관한 원칙입니다. 구조, description, 지울 내용, 지시의 자유도, 단계별 이유를 차례로 다룹니다.

계명 3. SKILL.md는 목차다 — 구조부터 잡아라

핵심 질문: 이 내용은 항상 읽혀야 하나, 필요할 때만 읽히면 되나?

SKILL.md는 모든 내용을 담는 매뉴얼이 아니라 목차여야 합니다. Anthropic의 Skill authoring best practices는 본문을 500줄 이내로 쓰도록 권장합니다. 모든 디테일을 넣으면 토큰이 낭비되고 핵심이 묻힙니다. 그래서 로드 시점에 따라 세 층으로 나눕니다(Progressive Disclosure).

각 층이 언제 읽히는지 그림으로 보면 다음과 같습니다. 이름과 설명은 항상, SKILL.md 본문은 호출될 때, 참고 문서는 필요할 때만 읽힙니다.

그림 3 스킬이 읽히는 방식

figma-to-android 스킬의 폴더도 이 세 층에 맞춰 나눴습니다.

figma-to-android/
├── SKILL.md              # 7단계 워크플로(2층)
├── references/
│   ├── compose.md        # Compose 전용 규칙(3층)
│   └── xml.md            # XML 전용 규칙(3층)
└── scripts/
    └── convert_assets.sh # 에셋 변환

참조는 SKILL.md에서 한 단계만 내려갑니다. a.md가 다시 b.md를 부르는 중첩 참조는 Claude가 일부만 읽고 끝낼 수 있습니다. 100줄이 넘는 참고 문서에는 목차를 넣으면 Claude가 필요한 절로 바로 찾아갈 수 있습니다. 두 가지 모두 같은 가이드에 나오는 권고입니다.

Compose 전용이던 스킬을 XML까지 넓힐 때 이 구조가 진가를 발휘했습니다. 공통 7단계는 그대로 두고 코드 생성 단계의 규칙만 compose.md와 xml.md로 나눴습니다. 이 구조는 뒤에서 iOS까지 넓힐 때도 그대로 쓰였습니다(실전 절 참고).

계명 4. description이 명함이다 — 트리거는 대부분 여기서 결정된다

핵심 질문: description에 무엇을 하는지, 언제 쓰는지, 어떤 키워드에 반응하는지 적었나?

frontmatter의 description은 Claude가 수많은 스킬 가운데 "지금 이걸 읽을까?"를 고를 때 이름(name)과 함께 보는 핵심 단서입니다. 패턴은 [무엇을 하는지] + [언제 쓰는지] + [트리거 키워드]입니다.

# 나쁜 예: 무엇을, 언제 하는지 알 수 없다
description: 피그마 관련 작업을 도와주는 스킬

# 좋은 예
description: >
  Figma 디자인을 Android UI(Compose/XML)로 변환하는 워크플로.
  Figma URL이나 Android 화면 변환 요청 시 사용하세요.

모호하게 쓰면 트리거가 안 되거나 엉뚱한 때 트리거됩니다. 트리거가 잘 안 되면 키워드와 상황을 더 적고, 너무 자주 되면 "이럴 때는 쓰지 마라"를 넣습니다. /skill-creator는 여러 프롬프트에서 스킬이 트리거되는지 실험하므로, 트리거가 고민이라면 써 볼 만합니다.

계명 5. Claude가 이미 아는 건 지워라 — 토큰은 공공재다

핵심 질문: Claude가 모르는 것만 남겼나?

스킬이 차지하는 토큰은 시스템 프롬프트, 대화 이력, 다른 스킬과 같은 공간을 나눠 씁니다. 그래서 토큰은 '공공재'입니다.

왼쪽은 Claude가 이미 아는 일반 지식이고, 오른쪽은 Claude가 실제로 틀리던 도메인 규칙입니다. 700줄이 넘던 초기 SKILL.md에서 Android 컴포넌트 설명을 모두 지우고 에셋 A/B/C 분류 같은 규칙만 남기자 241줄이 됐습니다.

모델이 좋아지면 더는 필요 없는 문장도 생깁니다. 그래서 주기적으로 스킬 다이어트를 합니다. 다만 다이어트도 감으로 하면 안 됩니다. 저희 팀은 문장 하나를 지울 때마다 그 문장이 실제 행동을 막는 방어선인지, 행동에 영향이 없는 서사인지를 가리는 skill-diet 스킬을 따로 만들어 씁니다. 근거 없이 줄였다가 같은 날 되돌린 적이 있었기 때문입니다.

계명 6. 자유도를 태스크에 맞게 설정하라 — 좁은 다리엔 난간을, 넓은 들판엔 방향만

핵심 질문: 이 단계는 스크립트인가, 가이드인가?

어떤 단계는 정답이 하나라 스크립트로 강제해야 하고, 어떤 단계는 판단이 필요해 가이드라인이면 충분합니다. 양쪽이 절벽인 좁은 다리에서는 정확한 길을, 넓은 들판에서는 방향만 알려 주는 셈입니다.

모든 것을 엄격하게 강제하면 Claude가 경직돼 예외 상황에 대응하지 못합니다. 모든 것을 느슨하게 두면 매번 다른 결과가 나옵니다. 공식 가이드도 결과가 정해진 작업에는 Claude가 코드를 새로 짜게 하기보다 미리 만든 스크립트를 쓰라고 권합니다. 꼭 지켜야 하는 검증은 문장 대신 스크립트로 둡니다.

중간 자유도의 예로 든 에셋 A/B/C 분류 기준표는 다음과 같습니다. Figma의 그래픽 요소를 처리 방식에 따라 세 유형으로 나눕니다.

계명 7. 이유를 설명하라 — 이유를 알면 단계를 건너뛰지 않는다

핵심 질문: 이 단계를 건너뛰면 무엇이 깨지는지 적었나?

7단계 중 일부를 Claude가 자꾸 건너뛰었습니다. "절대 건너뛰지 마라"를 넣어도 여전했습니다.

그런데 Claude가 지시를 따르지 않고 자기 판단대로 할 때 "왜"를 설명하면 다시 했던 경험이 있었습니다. 이를 스킬에 옮겨, 단계마다 건너뛰면 어떤 문제가 생기는지 적어 보았습니다.

실제 SKILL.md에는 'Why each step matters' 절을 두고, 7단계 전체에 다음과 같이 이유를 붙였습니다.

## Why each step matters

에이전트가 각 Step을 건너뛰지 않도록, 왜 필요한지 이해하는 것이 중요합니다.

**Step 1 (Node ID 추출):** file key와 node ID가 없으면 이후 모든 MCP 호출이 불가능합니다. URL 파싱 실수(예: `node-id`의 `-`를 `:`로 변환 누락)는 잘못된 노드를 가져오는 원인이 됩니다.

**Step 2 (디자인 컨텍스트):** `get_design_context`가 반환하는 React+Tailwind 코드는 **Step 6 코드 변환의 원본**입니다. 이 코드에 정확한 레이아웃 비율, gap, padding, 컴포넌트 계층구조가 모두 들어있습니다. 또한 이미지가 Figma의 임시 URL(`localhost:3845/assets/...`)로 포함되어 있어 세션 종료 시 만료되므로 Step 4~5의 에셋 파이프라인이 필요합니다.

**Step 3 (스크린샷):** 시각 참조 없이는 에셋 분류(Step 4)에서 동적/정적 판단이 불가능하고, 최종 검증(Step 7)에서 비교 기준이 없습니다.

**Step 4 (에셋 분류):** design_context의 시각 요소를 정적 에셋(A) / 동적 비주얼(B) / 기존 에셋(C)으로 분류합니다. 여기서 "시각 요소"란 `<img>` 태그뿐 아니라, **React 컴포넌트로 래핑된 아이콘**(IconToolbar → IconEtc → img 같은 중첩 호출)까지 포함합니다. `<img>` 태그만 추적하면 컴포넌트로 감싸진 아이콘이 누락되어 최종 화면에서 빠지게 됩니다.

**Step 5 (에셋 다운로드 및 처리):** 유형 A는 Figma REST API → SVG/PNG → Vector Drawable XML/WebP로 변환하여 `res/drawable`에 배치합니다. **유형 B는 SVG를 다운로드한 뒤 `Read`로 열어 Canvas 파라미터(stroke-width, 색상, opacity, 도형 유형)를 확인합니다.** design_context에서 "추론 가능"하다고 판단하여 이 단계를 생략하면, 전체 원 vs 270° arc, stroke-width 18 vs 16, black 6% opacity vs solid blue 같은 차이를 잡을 수 없어 코드를 재작성하게 됩니다.

**Step 6 (코드 변환):** Step 2의 React 코드를 Android UI로 **1:1 변환**합니다. 스크린샷을 보고 새로 짜는 것이 아니라, React의 컴포넌트 계층·Tailwind 수치를 그대로 Android 코드로 옮기는 것입니다. Step 4~5 산출물이 없으면 에셋 참조가 불가능합니다. 플랫폼별 변환 규칙은 `references/` 하위 문서를 참조합니다.

**Step 7 (검증):** Step 3의 스크린샷과 Step 5의 SVG 파라미터를 기준으로, 구현 결과의 시각적 일치와 디자인 시스템 규칙 준수를 검증합니다. 앞 단계를 건너뛰면 검증 기준 자체가 없습니다.

결과적으로 잘 동작했습니다. "건너뛰지 마라"는 명령이고 "건너뛰면 이게 깨진다"는 이해입니다. 체크리스트와 함께 쓰면 더 효과적입니다. 체크리스트는 빠뜨리지 않게, 이유는 건너뛰지 않게 해 줍니다. 스킬의 지시를 Claude가 잘 따르지 않아 고민이라면 시도해 볼 만합니다.

이 계명은 처음에 공식 문서에서 찾지 못해 직접 겪으며 얻은 것입니다. 나중에 보니 Anthropic의 skill-creator 스킬에도 요청하는 모든 것에 이유를 설명하라는 권고가 있었습니다.

검증과 개선

만든 스킬이 의도대로 동작하는지 확인하고 계속 고쳐 나가는 방법입니다. 깨끗한 환경에서 테스트하고, 실패 사례를 gotcha로 쌓으며, 효과를 숫자로 확인합니다.

계명 8. 컨텍스트 오염을 막아라 — 순수한 환경에서 테스트하라

핵심 질문: 스킬 밖의 정보 없이도 똑같이 동작하나?

"내 환경에선 잘되는데"의 전형적인 원인은 스킬 밖의 정보입니다. 스킬을 만든 사람의 대화 맥락과 메모리가 결과를 왜곡합니다. 실제로 겪은 오염원은 세 가지였습니다.

대화 맥락 오염을 피하려면 Claude A와 Claude B로 역할을 나눠 작업을 반복합니다. 먼저 Claude A에서 스킬을 설계하고, 새 세션의 Claude B에서 테스트합니다. 관찰 결과를 전달받은 A가 스킬을 수정하면, B에서 다시 테스트합니다. 세 오염원과 이 반복 순서를 그림으로 정리하면 다음과 같습니다.

그림 4 컨텍스트 오염원과 Claude A/B 반복 순서

그림 4의 .claude/memory/는 경로를 줄여 쓴 것이고, Claude Code의 자동 메모리는 실제로 ~/.claude/projects/<project>/memory/에 저장됩니다.

기존 코드를 베끼지 않도록 프롬프트에 금지 사항을 명시할 때는 다음과 같이 씁니다.

현재 선택한 Figma 레이어를 Compose UI 코드로 변환해 줘.
WeatherCard composable 파일들을 만들어서 작성해 줘.
기존 커밋 히스토리에서 관련 파일을 찾아서 참고하는 행동은 하지 마.

계명 9. gotcha를 쌓아라 — 스킬에서 가장 높은 시그널

핵심 질문: 이 실패를 다음 사람이 재현할 수 있게 적었나?

gotcha는 Claude가 반복해서 실수하는 지점을 기록한 것입니다. 계명 1에서 소개한 Lessons from building Claude Code: How we use skills에서 Thariq Shihipar는 스킬에서 가장 시그널이 높은 내용이 gotcha 섹션이라고 말합니다. 좋은 gotcha는 세 가지를 담습니다.

• 실패 상황: 무엇을 했고 무엇이 틀렸나
• 원인: 왜 틀렸나
• 해결책: 어떻게 해야 하나

발표에서는 다음 두 가지를 예로 들었습니다. Figma SVG의 mask 태그를 VectorDrawable이 지원하지 않는 문제와, 컴포넌트 안에 감싸인 이미지를 놓치는 문제입니다.

Figma SVG의 mask 태그는 VectorDrawable에서 지원 안 됨 → clipPath로 변환 필요.
컴포넌트 내부에 img 포함 시 → 컴포넌트 트리 전체를 탐색해야 함

실제로 팀에 모인 gotcha 하나를 세 요소로 정리하면 이렇습니다.

• 실패 상황: Figma에서 한글은 어절 단위로 줄이 바뀌는데 Compose에서는 음절 사이에서도 끊겨, "핸드오프"가 "핸 / 드오프"로 나뉘었습니다.
• 원인: 글자 폭이 아니라 줄을 끊는 규칙의 문제였습니다. 줄 바꿈 위치를 직접 지정한 옆 카드는 한 줄 폭이 Figma와 1px밖에 차이 나지 않았습니다. 글자 폭은 맞는데 끊는 위치만 달랐던 것입니다.
• 해결책: TextStyle에 두 설정을 함께 넣었습니다. 조합별로 재어 보니 두 설정이 모두 있어야만 맞았습니다.

TextStyle(
    // fontSize, lineHeight 등 기존 설정은 그대로 두고 아래 두 인자를 추가
    lineBreak = LineBreak(
        strategy = LineBreak.Strategy.Simple,
        strictness = LineBreak.Strictness.Normal,
        wordBreak = LineBreak.WordBreak.Phrase,
    ),
    localeList = LocaleList("ko-KR"),  // 기기 로캘이 en-US여도 어절 단위로 끊도록
)

LineBreak.WordBreak.Phrase는 Android 13(API 33)부터 동작합니다. 그보다 낮은 버전에서는 확인하지 못했습니다.

gotcha는 처음부터 다 알 수 없고 쓸수록 쌓입니다. 그래서 어느 정도 검증이 끝나면 팀 단위로 쓰면서 모으길 권합니다. 저희는 사내 저장소의 Discussions에 gotcha 카테고리를 두고, /discussion 명령 하나로 세션 내용을 요약해 등록합니다. 등록 양식에는 사용 모델, 재현 시작점, 판정 방법을 적게 해서 다음 사람이 같은 문제를 재현하고 검증할 수 있게 했습니다. 공개 저장소의 discussion 스킬은 design-to-ui Discussions에 같은 방식으로 등록합니다.

계명 10. 숫자로 증명하라 — 감으로 판단하지 마라

핵심 질문: 측정 가능한 지표가 있나?

기준 없이 gotcha를 넣다 보면 스킬 성능이 오히려 나빠질 수 있습니다. 그래서 스킬의 목표에 맞는 지표를 먼저 정하고, 바꿀 때마다 지표로 확인한 뒤 반영합니다. figma-to-android에서는 100점 만점의 3축 점수를 썼습니다.

실험에서는 변수를 통제합니다. 같은 모델, 같은 프롬프트, 같은 화면에서 스킬만 바꾸고, 계명 8의 오염원을 모두 막습니다. 들어가며에서 보인 colorScheme 참조 8회, 20회, 39회와 drawable 0개, 0개, 1개도 이렇게 얻은 숫자입니다. 두 숫자는 위 3축 가운데 코드 품질(디자인 토큰 채택률)과 에셋 정확도(drawable 생성)에 관련된 세부 수치입니다.

실제로 쓸 모델마다 테스트합니다. Opus에서 완벽한 스킬이 Haiku에서는 설명이 부족할 수 있기 때문입니다.

지표를 정한 뒤에는 사람의 개입도 줄일 수 있습니다. 오염을 막은 채 실험하는 스크립트를 만들어 두면, gotcha마다 효과가 있는지 AI가 직접 측정하고 보고서를 씁니다. 스킬을 고도화하는 반복 작업이 크게 줄어듭니다.

실전: 개인 스킬에서 팀 플러그인으로

혼자 만든 figma-to-android 스킬은 2026년 4월 사내 팀 플러그인 Figma-To-UI가 됐고, 이 플러그인을 naver/design-to-ui라는 이름으로 바꿔 오픈 소스로 공개했습니다. 10계명은 이 과정에서도 그대로 적용됐습니다. 이 글의 스킬 이름과 폴더 구조, 숫자는 사내 저장소 기준이라 공개 저장소와 다를 수 있습니다.

• 구조(계명 3): Android 전용이던 스킬을 iOS(SwiftUI/UIKit)까지 처리하도록 확장했습니다. Node ID 추출, 디자인 컨텍스트, 검증은 플랫폼 공통으로 두고 에셋과 코드 생성만 플랫폼별 reference로 나눴습니다. 프로젝트마다 다른 디자인 토큰 매핑은 각 프로젝트의 project-design-system 스킬로 분리했습니다.
• 자유도(계명 6): 눈대중으로 스크린숏을 비교해서는 실기기에서 요소가 8dp 밀리거나 글자 위치가 달라지는 것을 찾아내기 어려웠습니다. 그래서 실기기 화면과 Figma 원본을 겹쳐 비교하는 design-qa 스킬을 따로 만들고, 측정은 스크립트에 맡겼습니다.
• gotcha(계명 9): 팀원과 디자이너까지 쓰기 시작하자 Discussions에 글이 55건(2026년 10월 기준) 쌓였고, 그중 31건이 gotcha입니다. 예를 들어 에셋 변환 스크립트가 transform이 있는 SVG를 놓치고도 "errors 0"으로 성공 처리하던 문제는 다른 팀 개발자가 찾아 주었습니다.
• 다이어트(계명 5): gotcha가 쌓이며 문서가 다시 길어졌고, skill-diet 스킬로 한 절씩 줄이고 있습니다. 실제로 줄여 보니 절 하나에서 빠지는 건 대개 1∼7줄이었습니다. 눈에는 군더더기처럼 보여도 대부분은 방어선이었다는 뜻입니다.

2026년 10월 기준으로 플러그인에는 변환, 검수, 에셋 다운로드, 온보딩 등 스킬 10개가 들어 있고, 15명이 커밋 448개를 쌓았습니다. 개발자가 만든 화면을 디자이너가 개발 단계에서 먼저 확인하고 고치는 '선(先)디자인 검수' 워크플로도 이 플러그인 위에서 돌아갑니다.

초기 지표도 있습니다. 선디자인 검수를 적용한 스펙에서 디자인 검수 공수는 대체로 절반으로 줄었고, 오토앱의 한 위젯은 5MD에서 0.5MD가 됐습니다(1MD는 한 사람이 하루 8시간 일하는 양). 반면 UI 개발 공수는 이미 AI로 개발하는 상태와 비교하면 아직 뚜렷한 차이가 없습니다. 적용한 스펙이 아직 적어 대푯값으로 보기는 이릅니다.

마치며: 이번 주에 해 볼 일 하나

가장 중요한 건 시작하는 것입니다. 이번 주에 AI에 세 번 넘게 반복해서 설명한 작업이 있었다면 적어 보세요. 그중 패턴이 가장 분명한 하나로 SKILL.md 초안을 쓰고, 아래 표로 하나씩 점검해 보세요. v1은 완벽하지 않아도 됩니다. 쓰다 보면 gotcha가 쌓이고 정확도도 올라갑니다.

비슷한 고민을 하고 있다면 design-to-ui Discussions에서 언제든 이야기 나눠 주세요.

참고 자료

• Skill authoring best practices — Anthropic
• Lessons from building Claude Code: How we use skills — Thariq Shihipar, Anthropic
• anthropics/skills — Anthropic 공식 스킬 저장소
• skill-creator — Anthropic 공식 스킬 작성 스킬
• figma/mcp-server-guide — Figma MCP 서버 가이드와 공식 스킬