18장. Skills 작성과 활용 — 팀의 디자인 판단을 AI에게 가르치는 마크다운 파일

좋은 에이전트 협업은 모델보다 기준에서 나온다

AI 에이전트와 같이 일하다 보면 금방 이런 장면을 보게 된다. 같은 모델인데 어떤 날은 꽤 쓸 만한 결과가 나오고, 어떤 날은 엉뚱한 산출물이 튀어나온다. 많은 사람은 이 차이를 모델 성능으로만 설명하려고 하지만, 실무에서는 그것만으로는 부족하다. 자주 갈리는 지점은 오히려 팀의 기준이 얼마나 문서화되어 있느냐다.

예를 들어 어떤 팀은 버튼 간격을 8pt 스케일로만 쓴다. 어떤 팀은 경고 상태에서 빨강을 바로 쓰지 않고 항상 semantic token을 거친다. 어떤 팀은 카드형 레이아웃에서 타이틀 줄 수를 2줄로 제한한다. 사람끼리는 이런 것을 오래 같이 일하며 눈치로 배운다. 하지만 에이전트는 눈치를 보지 못한다. 주어지지 않은 규칙은 없는 규칙이나 마찬가지다.

그래서 Skills가 중요해진다. Skill은 단순한 팁 문서가 아니라, 반복되는 작업 순서와 판단 기준을 재사용 가능한 지침으로 묶은 것이다.¹²

Skill은 프롬프트와 무엇이 다른가

프롬프트는 보통 한 번의 요청을 해결하기 위한 문장이다. "이 화면을 우리 디자인 시스템에 맞춰 구현해 줘"처럼 지금 당장 필요한 일을 설명한다. 반면 Skill은 그 요청이 자주 반복될 때, 매번 같은 설명을 다시 하지 않도록 작업 방식 자체를 정리한 문서에 가깝다.

둘의 차이를 감각적으로 나누면 이렇다.

• 프롬프트는 지금 할 일을 말한다.

• Skill은 그 일을 어떤 순서와 기준으로 처리해야 하는지 가르친다.

예를 들어 프롬프트가 "이 결제 화면을 구현해 줘"라면, Skill은 그 구현을 할 때

• 먼저 Figma 링크에서 디자인 문맥을 읽고,

• Code Connect 매핑을 우선 확인하고,

• 없으면 팀 공용 버튼과 입력 컴포넌트를 사용하며,

• spacing token은 임의 숫자 대신 space/* 계열만 쓰고,

• 접근성 속성을 마지막에 반드시 점검하라

같은 흐름을 담는다. 그래서 Skill은 일회성 브리프보다 운영 매뉴얼에 더 가깝다.

Figma가 말하는 Skills는 무엇인가

Figma 공식 문서에서 Skills는, Figma MCP 서버와 함께 쓰는 사전 제작된 지침 묶음이다. 에이전트가 특정 Figma 작업을 더 안정적으로 수행하도록 도와주는 instructions 모음이라고 보면 된다.¹ 중요한 점은 Skill이 MCP 자체를 대체하지 않는다는 것이다. MCP가 도구 연결이라면, Skill은 그 도구를 어떤 순서로 어떤 맥락에서 써야 하는지 알려주는 사용 지침에 가깝다.

Figma는 몇 가지 기본 Skill을 직접 제공한다.¹

• figma-use: 캔버스에 직접 쓰기 위한 기반 Skill

• figma-create-new-file: 새 Figma 파일 만들기

• figma-implement-design: 디자인을 코드로 구현하는 흐름 지원

• figma-code-connect-components: 컴포넌트를 Code Connect로 연결

• figma-create-design-system-rules: 디자인 시스템 규칙 파일 만들기

여기서 독자가 기억해야 할 핵심은 두 가지다.

첫째, Skill은 도구 이름이 아니라 작업 절차를 담은 안내서라는 점.
둘째, 좋은 Skill은 팀의 규칙을 담을수록 강해진다는 점.

왜 프롬프트만으로는 일관성이 생기지 않는가

프롬프트만으로도 어느 정도는 된다. 문제는 반복성이다. 팀 안에서 같은 작업을 다섯 번, 열 번, 쉰 번 할수록 매번 같은 설명을 다시 쓰는 비용이 커진다. 더 큰 문제는 사람마다 설명 방식이 다르다는 것이다. 누군가는 "깔끔하게 해 줘"라고 쓰고, 누군가는 "우리 시스템에 맞춰 줘"라고 쓰고, 누군가는 아예 토큰과 컴포넌트 이름까지 구체적으로 적는다. 결과도 당연히 흔들린다.

Skill이 필요한 이유는 바로 여기 있다. 팀이 반복해서 중요하게 여기는 기준을 한 번 정리해 두면, 결과 품질의 바닥선이 올라간다. 엄청난 천재 프롬프트가 없어도, 최소한 엉뚱한 결과가 줄어든다.

특히 디자인 시스템, 핸드오프, 컴포넌트 매핑, AI 코드 생성처럼 작은 일관성 차이가 큰 비용 차이로 이어지는 작업에서는 Skill의 효과가 크다.

좋은 Skill은 정보를 많이 넣는 문서가 아니다

처음 Skill을 만들 때 가장 흔한 실수는 "생각나는 걸 다 적는 것"이다. 하지만 긴 문서가 곧 좋은 Skill은 아니다. 오히려 너무 많은 정보는 에이전트가 무엇을 우선해야 하는지 흐리게 만든다.

좋은 Skill은 보통 다음 여섯 가지가 또렷하다.

1. 적용 상황

이 Skill을 언제 써야 하는가를 먼저 분명히 해야 한다. 예를 들어 "피그마 프레임을 프론트엔드 코드로 구현할 때"처럼 시작점이 명확해야 한다.

2. 입력 조건

어떤 정보가 들어와야 제대로 작동하는지 적어야 한다. Figma URL, 코드베이스 경로, 대상 프레임, 연결된 디자인 시스템 이름 같은 것들이다.

3. 작업 순서

에이전트가 무엇부터 확인해야 하는지 단계로 써 준다. 예를 들면:

1. Figma 링크에서 프레임 문맥 읽기

2. Code Connect 매핑 조회

3. 없으면 디자인 시스템 컴포넌트 탐색

4. 토큰 사용 여부 확인

5. 구현 후 접근성·반응형 검수

이 순서가 있어야 에이전트가 덜 헤맨다.

4. 판단 규칙

여기가 핵심이다. "가능하면"이나 "적당히"보다 절대 규칙과 우선순위 규칙을 분명히 적어야 한다.

• 절대 규칙: raw hex를 직접 쓰지 말 것

• 우선순위 규칙: Code Connect가 있으면 그것을 최우선 사용

• 예외 규칙: 매핑이 없을 때만 공용 UI 컴포넌트 fallback 허용

이런 식이어야 실제 업무에서 쓸 수 있다.

5. 금지 사항

잘못된 산출물을 줄이려면 하지 말아야 할 것도 써야 한다. 예를 들어 "임의 spacing 값 생성 금지", "library에 없는 새 버튼 variant 발명 금지", "placeholder 카피를 최종 문구처럼 확정하지 말 것" 같은 것들이다.

6. 검수 기준

마지막에는 무엇을 확인해야 완료로 볼지 적는다. 예를 들면 컴포넌트 재사용 여부, 토큰 일치 여부, 접근성 속성, 줄바꿈 깨짐, 다크 모드 대응 여부 등이다.

모호한 취향을 실행 가능한 규칙으로 바꾸는 법

팀의 암묵지는 대개 취향의 언어로 존재한다. "너무 답답하지 않게", "좀 더 브랜드답게", "우리답게 정리해" 같은 식이다. 사람끼리는 이런 말이 어느 정도 통하지만, 에이전트에게는 거의 도움이 되지 않는다.

이때 필요한 것은 취향을 없애는 일이 아니라, 취향을 행동 가능한 문장으로 바꾸는 일이다.

예를 들면 이렇게 바꾼다.

• "깔끔하게" → 정보 계층을 3단계 이내로 제한하고, 한 카드 안의 본문 텍스트는 최대 2종까지만 사용한다.

• "브랜드답게" → CTA는 브랜드 기본색의 semantic action token을 사용하고, 보조 버튼은 outline 스타일을 우선 사용한다.

• "답답하지 않게" → 모바일 카드 내부 패딩은 space/16 이상, 제목과 본문 사이 간격은 space/8 이상 유지한다.

좋은 Skill은 이런 번역을 해 주는 문서다.

작은 Skill부터 시작해야 운영된다

처음부터 팀의 모든 디자인 철학을 한 문서에 담으려고 하면 거의 실패한다. 길고 추상적인 원칙집은 읽히지 않고, 읽혀도 실제 작업에서 바로 쓰기 어렵다. 대신 작고 자주 쓰는 작업 하나를 잡아 Skill로 만드는 편이 훨씬 낫다.

예를 들어 이런 식으로 시작할 수 있다.

• "Figma 프레임을 React 화면으로 구현할 때의 규칙"

• "새 컴포넌트를 라이브러리에 추가할 때의 체크리스트"

• "에이전트가 오토 레이아웃을 쓸 때의 기본 규칙"

• "마케팅 랜딩 페이지 카피를 Replace content로 채운 뒤 검수하는 기준"

이렇게 좁게 시작하면 실제로 테스트하고 고치기 쉽다. 실패 로그도 모으기 쉽고, 어떤 규칙이 쓸모 있는지도 금방 보인다.

프로젝트 룰 파일과 Skill은 어떻게 다른가

여기서 독자가 한 번 헷갈릴 수 있다. 프로젝트 안에 있는 guidelines.md, rules/, instructions/ 같은 파일과 Skill은 무엇이 다를까?

실무에서는 경계가 완전히 딱 잘리지는 않는다. 하지만 역할을 나누면 이해하기 쉽다.

• Skill: 특정 작업 흐름을 수행하는 절차와 판단 기준

• 프로젝트 룰 파일: 그 프로젝트 전체에 계속 적용되는 전역 규칙

• guidelines.md 같은 파일: 특히 Figma Make나 코드 생성에서 반복 참조할 스타일·제약·맥락 메모

즉, Skill은 "이 일을 어떻게 할까"에 가깝고, 룰 파일은 "이 프로젝트에서는 무엇을 지켜야 할까"에 가깝다. 둘은 경쟁 관계가 아니라 같이 써야 안정적이다.¹³

Skill 예시를 볼 때 주의할 점

Figma가 제공하는 예시 Skill이나 커뮤니티 Skill은 좋은 출발점이지만, 그대로 가져다 쓰면 팀 현실과 어긋날 수 있다. 왜냐하면 팀마다

• 사용하는 프레임워크가 다르고,

• 컴포넌트 이름이 다르고,

• 토큰 체계가 다르고,

• 접근성 우선순위가 다르고,

• 리뷰 문화가 다르기 때문이다.

그래서 예시 Skill을 볼 때는 문장을 외우기보다 구조를 보는 편이 낫다. 이 Skill이 어떤 입력을 요구하는지, 어떤 순서로 도구를 쓰는지, 어디에서 금지 규칙을 두는지, 완료 판단을 어떻게 하는지를 보는 것이다.

운영 단계에서 꼭 필요한 것들

Skill은 써 놓고 끝나는 문서가 아니다. 실제로는 운영이 더 중요하다.

소유자를 정해야 한다

누가 이 Skill을 관리하는지 분명해야 한다. 대개는 디자인 시스템 담당자, 디자인 옵스, 혹은 프론트엔드와 함께 일하는 제품 디자이너가 적합하다. 소유자가 없으면 금방 낡는다.

실패 로그를 모아야 한다

에이전트가 어디서 자주 틀리는지 모으면 Skill은 빠르게 좋아진다. 예를 들어 계속 raw color를 써 버린다면 규칙이 약한 것이다. 계속 잘못된 버튼을 고른다면 우선순위 규칙이 모호한 것이다.

버전을 남겨야 한다

팀의 컴포넌트 구조나 토큰 체계가 바뀌면 Skill도 바뀌어야 한다. 그래서 변경 이력을 남기는 편이 좋다. 최소한 "왜 바꿨는가" 정도는 기록해야 다음 사람이 이해할 수 있다.

검수 기준을 끝에 명시해야 한다

Skill의 마지막에는 결과를 어떻게 검사할지 적는 편이 좋다. 그래야 에이전트도 스스로 점검하기 쉽고, 사람 리뷰어도 같은 기준으로 볼 수 있다.

결국 Skill은 팀의 판단을 외부화하는 장치다

이 장의 핵심은 복잡하지 않다. 좋은 Skill은 AI를 더 똑똑하게 만드는 비밀 주문이 아니다. 오히려 그 반대에 가깝다. 사람이 이미 알고 있지만 매번 말로 다시 설명하느라 소모되던 기준을 밖으로 꺼내는 일이다.

Figma MCP와 use_figma가 에이전트에게 손을 준다면, Skill은 방향 감각을 준다. 손만 있고 기준이 없으면 빠르게 틀린다. 반대로 기준이 선명하면, 모델이 조금 달라도 결과의 일관성은 훨씬 좋아진다.

그래서 AI 시대의 팀 문서화는 선택이 아니라 생산성 자체다. 잘 만든 Skill 하나는 좋은 프롬프트 여러 개보다 오래 간다. 그리고 그 Skill은 결국 팀이 무엇을 중요하게 여기는지를 가장 또렷하게 드러내는 문서가 된다.

참고

¹Figma skills for MCP – Figma Learn - Help Center

²Guide to the Figma MCP server – Figma Learn - Help Center

³Figma Make FAQs – Figma Learn - Help Center