디자인 워크플로를 SKILL.md로 만드는 법 Claude Code와 Codex에서 재사용하기
디자인과 접근성 검토처럼 반복하는 작업을 재사용 가능한 스킬로 정리해요.
같은 팀에서 비슷한 화면을 여러 번 만들다 보면 매번 같은 설명을 하게 됩니다. 기존 프로젝트부터 읽고, 이미 쓰는 버튼과 색 토큰을 확인하고, 키보드 조작과 좁은 화면까지 점검하라는 이야기죠. 이 절차를 매 프롬프트에 복사하는 대신 SKILL.md에 적어두면, Claude Code나 Codex가 필요할 때 읽어 재사용할 수 있습니다.
스킬은 모델을 대신해 디자인 결정을 내리는 파일이 아닙니다. 팀이 반복하는 판단 과정과 완료 기준을 명확히 전달하는 작업 안내서입니다.
SKILL.md와 Agent Skills 구조
Agent Skills 표준에서 스킬은 SKILL.md를 중심으로 한 폴더입니다. 파일 앞부분의 YAML 메타데이터에는 필수 항목인 name과 description을 적고, 본문에는 언제 쓰는지와 구체적인 절차를 씁니다. 필요한 경우 예시, 체크리스트, 스크립트 같은 보조 파일을 같은 폴더에 둘 수 있습니다.
Claude Code와 Codex는 각자 스킬을 찾는 위치와 확장 기능이 다르지만, SKILL.md에 재사용 가능한 지침을 둔다는 개념은 공유합니다. Claude Code의 공식 문서는 스킬 본문이 사용될 때 로드된다고 설명하며, Codex도 이름과 설명을 보고 관련성을 판단한 뒤 전체 지침을 읽는 흐름을 안내합니다. 그러므로 설명에는 스킬의 이름만 적지 말고, 어떤 요청에서 써야 하는지 분명히 써야 합니다.
디자인 스킬 적용 대상
한 번만 하는 작업이나 아직 기준이 합의되지 않은 탐색에는 스킬이 과합니다. 다음 조건을 만족하면 만들어 둘 가치가 있습니다.
- 여러 화면이나 프로젝트에서 같은 검수 순서를 반복한다.
- 팀원이 자주 놓치는 접근성·반응형·상태 기준이 있다.
- 결과물보다 작업 방식과 완료 조건을 일관되게 하고 싶다.
- 그 절차가 매일 바뀌지 않고, 현재 팀의 기준으로 설명 가능하다.
예를 들어 ‘멋진 카드 UI를 만들어라’는 너무 넓습니다. 반면 ‘기존 디자인 토큰을 먼저 확인하고, 카드의 기본·로딩·오류 상태를 정의한 다음 모바일 폭과 키보드 포커스를 검토하라’는 재사용 가능한 절차입니다.
SKILL.md 작성 구성
1. 스킬 실행 조건
description에는 사용자가 어떤 종류의 요청을 했을 때 이 스킬을 고려해야 하는지 씁니다. “UI를 잘 만든다”처럼 넓게 쓰면 엉뚱한 과업에도 걸리고, 너무 좁으면 필요한 때 선택되지 않습니다.
2. 프로젝트 사전 조사
프로젝트의 프레임워크, 기존 컴포넌트, 토큰, 접근성 요구사항, 화면 크기 같은 선행 맥락을 구체적으로 적습니다. 새 화면을 만들기 전에 이미 있는 패턴을 찾도록 하면 불필요한 중복을 줄일 수 있습니다.
3. 디자인 작업 순서
행동할 수 있는 동사로 절차를 씁니다. “일관성을 지킨다”보다 “기존 버튼 변형과 색 토큰을 검색하고, 재사용 가능한 것이 있으면 우선 적용한다”가 실행하기 쉽습니다.
4. 검증과 완료 기준
완료 조건은 결과의 검토 기준이어야 합니다. 예를 들어 화면 폭을 바꾸어도 주요 동작이 가능하고, 필수 입력의 오류 상태가 표시되며, 키보드만으로 주요 흐름을 완료할 수 있는지 확인할 수 있습니다.
디자인 스킬 작성 예시
다음은 기존 제품의 UI를 확장할 때 사용할 수 있는 간단한 디자인 구현 스킬입니다. 프로젝트에 맞춰 이름과 검수 항목을 바꾸세요.
---
name: product-ui-workflow
description: 기존 웹 제품의 화면이나 컴포넌트를 추가·수정할 때 사용한다. 프로젝트의 UI 규칙을 먼저 확인하고 접근성, 반응형, 상태를 검토한다.
---
## 제품 UI 작업 절차
1. 시작 전에 프로젝트의 프레임워크, 기존 컴포넌트, 토큰, 화면 구조와 관련 UX 요구사항을 확인한다.
2. 이미 있는 패턴을 재사용할 수 있는지 살펴본다. 새 패턴이 필요하면 어떤 사용자 문제를 해결하는지 한 문장으로 정리한다.
3. 구현에 들어가기 전에 기본, 로딩, 빈 화면, 오류, 비활성 상태 중 해당되는 상태를 정의한다.
4. 기존 토큰과 문구 스타일을 우선 적용한다. 임의의 색상·간격·컴포넌트 변형을 추가하면 이유를 설명한다.
5. 좁은 화면과 넓은 화면에서 콘텐츠가 잘리고 동작이 가려지지 않는지 확인한다.
6. 키보드 포커스, 조작 순서, 접근 가능한 이름, 오류 안내를 점검한다.
7. 완료 시 바뀐 화면과 동작, 실행한 확인 절차, 남은 한계를 짧게 정리한다.
이 파일은 완성된 UI를 보장하지 않습니다. 어떤 컴포넌트를 선택할지, 오류를 어떤 말투로 설명할지, 좁은 화면에서 정보를 어떻게 우선할지는 여전히 제품 맥락에 맞춰 판단해야 합니다. 스킬은 기준을 상기시키고 확인 절차를 반복하는 데 도움을 줍니다.
Claude Code와 Codex 스킬 경로
Claude Code의 공식 문서에서 프로젝트 스킬은 저장소의 .claude/skills/<스킬이름>/SKILL.md, 개인 스킬은 ~/.claude/skills/<스킬이름>/SKILL.md에 둡니다. 폴더 이름은 /skill-name으로 직접 부를 때 쓰이는 명령 이름과 연결됩니다.
Codex는 저장소에서 공유할 스킬을 .agents/skills/<스킬이름>/SKILL.md에, 개인용을 ~/.agents/skills/<스킬이름>/SKILL.md에 둘 수 있습니다. Codex 앱에서 스킬을 만들고 관리할 수도 있습니다. 두 제품 모두 저장소에 포함한 파일은 팀원이 같은 작업 지침을 가져가는 방법이 될 수 있지만, 개인 디렉터리에 설치한 스킬은 그 사람의 환경에 남습니다.
프로젝트별 차이가 큰 절차라면 저장소에 넣고 변경 이력을 함께 관리하세요. 한 디자이너의 실험용 기준이라면 우선 개인 범위에서 다듬어도 됩니다. 제품별 설치 경로와 인식 범위는 업데이트될 수 있으므로 팀 문서로 배포하기 전 각 공식 안내를 다시 확인하는 편이 안전합니다.
디자인 스킬 지침 유지관리
- 사실과 절차를 나눕니다. 색상 토큰표처럼 자주 찾는 기준은 별도 참조 파일에 둘 수 있지만, 스킬 본문에서 언제 그 파일을 읽을지 알려야 합니다.
- 근거 없이 프로젝트 상태를 단정하지 않습니다. “이미 버튼 컴포넌트가 있다” 대신 “기존 버튼을 검색하고, 있으면 재사용한다”고 씁니다.
- 실행할 수 없는 지시를 넣지 않습니다. 디자인 도구나 저장소 접근이 제공되지 않았다면 그 맥락을 요청하거나 사용자가 제공한 자료에 한정하라고 안내합니다.
- 예외를 다룹니다. 기존 토큰이 요구사항을 충족하지 못할 때는 무조건 따르라고 하기보다 이유를 기록하고 검토할 기준을 정합니다.
- 작업 후 스킬 자체를 점검합니다. 반복해서 건너뛴 단계, 모호했던 조건, 지나치게 많은 범용 지침을 실제 사용 사례에 맞춰 고칩니다.
스킬 공유 전 체크리스트
- 이름과 설명만 읽어도 어떤 요청에 쓰는지 알 수 있는가?
- 첫 단계가 기존 프로젝트의 실제 상태를 확인하도록 되어 있는가?
- 각 절차가 구체적인 행동으로 표현되어 있는가?
- 시각적 완성도뿐 아니라 상태·키보드·반응형 검수가 포함되어 있는가?
- 스킬이 접근할 수 없는 파일이나 도구를 있다고 가정하지 않는가?
- 다른 팀원이 같은 저장소에서 읽고 개선할 수 있도록 버전 관리할 것인가?
반복되는 설명을 스킬로 옮기면 디자이너가 매번 긴 프롬프트를 쓰는 부담은 줄어듭니다. 대신 어떤 결과가 좋은지 합의하고, 예외를 판단하고, 실제 화면에서 검수하는 일은 더 분명해집니다.