google-labs-code/stitch-skills 딥다이브
— 코드가 아니라 "지침서"를 배포하는 저장소

1한 줄 정체

이 저장소를 열면 서버도, 프론트엔드 앱도, npm start로 띄울 무언가도 없다. 있는 것은 plugins/ 폴더 아래 15개의 SKILL.md 파일과 그것을 뒷받침하는 소수의 스크립트(.sh/.js/.py)뿐이다. 즉 이 레포의 "산출물"은 사람이 아니라 AI 에이전트가 읽는 업무 매뉴얼이다.

Stitch는 텍스트나 이미지로 UI 화면(스크린)을 생성해주는 Google의 디자인 툴이며, MCP(Model Context Protocol) 서버로 코딩 에이전트에 연결된다. 문제는 "Stitch MCP에 연결됐다"는 사실만으로는 에이전트가 디자인 토큰을 지키고, 이미지를 안전하게 올리고, React로 옮길 때 접근성·타입을 지키는 행동을 하지 않는다는 점이다. stitch-skills는 이 간극을, 각 작업 단계마다 강제 규칙(GATE)과 안티패턴 목록을 박아넣은 스킬 문서로 메운다.

2왜 지금 뜨는가

2026년 들어 Claude Code·Codex·Cursor·Gemini CLI 등 코딩 에이전트가 폭발적으로 늘면서, 이들에게 "특정 작업을 어떻게 해야 하는지" 가르치는 표준 포맷인 Agent Skills(agentskills.io)가 여러 벤더에 걸쳐 자리 잡고 있다. stitch-skills는 이 표준을 채택한 초기 사례 중 하나이며, 만든 주체가 google-labs-code라는 점에서 신뢰도 신호가 크다.

① "디자인 → 코드" 자동화가 실전 수요가 됐다

v0·Lovable·Stitch 같은 텍스트/이미지 기반 UI 생성 툴이 늘면서, "생성된 디자인을 실제 프로덕션 코드로 안전하게 옮기는" 중간 단계가 새로운 병목이 됐다. stitch-skills는 이 병목을 정면으로 겨냥해 React·React Native·shadcn/ui·Remotion(동영상)까지 변환 대상을 넓혔다.

② 하나의 스킬로 여러 에이전트 CLI를 동시에 커버

README는 Codex, Antigravity, Gemini CLI, Claude Code, Cursor, (수동 설치로) OpenCode까지 호환된다고 명시한다. npx plugins add ... --target claude-code, npx plugins add ... --target cursor처럼 같은 스킬 소스를 타겟만 바꿔 설치하는 배포 방식은, 특정 벤더에 종속되지 않으려는 최근 흐름과 맞아떨어진다.

③ "그냥 프롬프트"가 아니라 검증 가능한 규율

대부분의 프롬프트 모음은 텍스트일 뿐이라 지켜지는지 확인할 길이 없다. 이 레포는 일부 스킬(react-components, react-native)에 대해 AST 파서로 실제 코드를 검사하는 스크립트와 GitHub Actions CI를 붙여, "말로만 하는 규칙"을 "기계로 확인하는 규칙"으로 바꿨다.

3무엇을 해결하나 — 문제와 해결

AI 에이전트에게 Stitch MCP 접근권만 주고 "디자인을 React로 바꿔줘"라고 하면 실제로 어떤 일이 벌어질까? 소스 코드에 남은 실패 사례에 대한 방어 코드와 경고 문구들을 역추적하면, 이 레포가 막으려는 실제 문제가 선명하게 드러난다.

4전체 구조

스킬 하나의 내부는 Agent Skills 표준이 정한 4단 규격을 따른다(단, 아래에서 보듯 실제로는 지켜지지 않는 스킬도 있다):

5핵심 설계·동작 원리

설계 패턴 ① — "GATE"로 순서를 강제하는 절차형 프롬프트

plugins/stitch-build/skills/react-components/SKILL.md는 작업을 Phase 1~4로 나누고, 각 Phase 앞에 "GATE: … 완료로 간주된다"는 문구를 박아 넣는다. 예를 들어 Phase 1은 fetch-stitch.sh로 모든 화면을 다운로드하고 스크린샷을 육안 감사한 뒤에만 완료로 치고, Phase 2는 현재 프로젝트의 HTML에서 새로 추출한 토큰으로 style-guide.json을 덮어써야만 완료로 친다. 각 Phase 끝에는 "Anti-patterns" 목록이 명시적으로 붙어, 흔한 실수(모놀리식 컴포넌트, 하드코딩 색상, 미변환 href="#")를 나열한다.

설계 패턴 ② — AST 파서로 실제 코드를 기계 검사

말로 된 규칙과 달리 실제로 강제되는 유일한 지점이 plugins/stitch-build/skills/react-components/scripts/validate.js다. @swc/core로 TSX 코드를 파싱해 AST를 만든 뒤, 재귀 walk() 함수로 트리를 훑으며 두 가지를 검사한다.

const HEX_COLOR_REGEX = /#[0-9A-Fa-f]{3,8}\b/;
...
if (node.type === 'TsInterfaceDeclaration' && node.id.value.endsWith('Props')) hasInterface = true;
if (node.type === 'JSXAttribute' && (node.name?.value === 'className' || node.name?.name === 'className')) {
  if (node.value?.value && HEX_COLOR_REGEX.test(node.value.value)) tailwindIssues.push(node.value.value);
}

즉 ① ~Props로 끝나는 TypeScript 인터페이스 선언이 있는지, ② className 안에 하드코딩 hex 색상이 섞여 있는지를 검사해 hasInterface와 tailwindIssues를 채우고, 하나라도 어긋나면 process.exit(1)로 실패 처리한다. 이 검사는 .github/workflows/validate-skills.yml CI에서 examples/gold-standard-card.tsx를 대상으로 실제로 실행된다(Node 18.x, npm ci → node scripts/validate.js).

설계 패턴 ③ — "모델의 출력 토큰 한계"를 우회하는 스크립트

plugins/stitch-design/skills/upload-to-stitch/scripts/upload_to_stitch.py의 docstring은 이 레포에서 가장 흥미로운 설계 근거를 직접 설명한다: MCP 툴 호출 인자는 모델의 출력이므로, 파일을 base64로 통째로 재생성해 인자에 담아야 하는데 모델 출력 토큰 한도(~16K)가 파일의 base64 길이(예: 53KB PNG → 약 71K자)보다 훨씬 작아 중간에 잘리고 요청이 깨진다.

해결책은 모델을 완전히 우회하는 것이다. 스크립트가 직접 파일을 읽어 base64 인코딩하고, BatchCreateScreens REST 엔드포인트(POST /v1/projects/{id}/screens:batchCreate)로 곧장 HTTP 요청을 보낸다. 에이전트는 "이 파일 경로로 스크립트를 실행해라"라고만 지시하면 된다 — 파일 내용을 자기 출력으로 재생성할 필요가 없다.

설계 패턴 ④ — baton(계주봉) 릴레이로 만드는 자율 루프

stitch-loop 스킬은 .stitch/next-prompt.md라는 파일을 다음 실행 회차에 넘기는 계주봉(baton)으로 쓴다. 파일의 YAML 프론트매터 page: 필드가 다음에 만들 페이지명을, 본문이 그 페이지의 프롬프트(디자인 시스템 블록 포함)를 담는다. 한 번의 실행(iteration)은 6단계로 진행된다.

프로젝트·화면 ID는 .stitch/metadata.json에 영속화되어 다음 회차가 이어받는다. 이 루프는 오케스트레이션 방식과 무관하게 설계됐다 — GitHub Actions가 파일 변경을 트리거해도, 사람이 매번 같은 에이전트를 다시 실행해도 동일하게 동작한다.

설계 패턴 ⑤ — "안티-제네릭"을 명문화한 디자인 규율

taste-design 스킬은 "예쁘게 만들어줘" 대신 무엇을 하지 말아야 하는지를 촘촘히 나열한다 — Inter 폰트 금지, 순수 검정(#000000) 금지, 보라/네온 글로우 금지, 균등 3열 카드 금지, 그리고 "99.98% 가동률" 같은 존재하지 않는 통계를 지어내는 것 자체를 금지한다. 이는 LLM이 그럴듯해 보이는 숫자를 환각하는 문제를 디자인 스킬 차원에서 막으려는 시도다.

6기술 스택 · 의존성

레포 루트에는 package.json이 없다. 이는 이 레포가 "빌드해서 실행하는 소프트웨어"가 아니라 "에이전트가 읽는 문서+도구 모음"이라는 정체성을 그대로 보여준다. npm 의존성의 버전 진실원(source of truth)은 개별 스킬 폴더 안의 package.json뿐이다.

7설치 · 요구사항

8실제 사용 흐름

가장 대표적인 흐름은 "Stitch에서 화면을 만들고, 그것을 React 코드로 바꾸는" 경로다. 여러 스킬이 이 한 흐름 안에서 순서대로 호출된다.

자율 사이트 빌드가 목적이면 stitch-loop가 이 흐름을 반복 실행으로 감싼다: baton(.stitch/next-prompt.md)을 읽고 → 위 [2]~[4]에 준하는 생성·통합을 한 페이지만큼 수행하고 → 다음 페이지를 위한 새 baton을 써서 마무리한다. Chrome DevTools MCP가 있으면 Step 4.5에서 렌더링 결과를 스크린샷 비교로 시각 검증하는 선택 단계도 들어간다.

9함정 · 오해 방지

10대안 비교

11정리 — 누가 쓰면 좋은가

stitch-skills는 "소프트웨어"가 아니라 "AI 에이전트를 위한 운영 지침 세트"다. 이미 Google Stitch로 디자인 작업을 하면서 Claude Code·Cursor·Codex 같은 에이전트에게 후속 작업(React 변환, 디자인 시스템 관리, 자율 사이트 빌드)을 맡기고 싶은 사람에게 직접적인 실용 가치가 있다. Stitch를 쓰지 않더라도, "에이전트에게 복잡한 다단계 작업을 어떻게 안전하게 위임할 것인가"를 GATE·Anti-pattern·AST 검증·CI라는 구체적 장치로 보여주는 참고 설계 사례로서 읽을 가치가 크다.

12직접 해볼 수 있는 실습 과제

아래 명령은 모두 로컬에 준비된 stitch-skills 클론의 루트에서 실행한다. 원본 파일은 읽기만 하고, 프롬프트와 설계 답안은 별도 메모로 작성한다. 외부 서비스 연결 없이 진행할 수 있으며, 과제 3의 검증기 실행만 해당 스킬의 npm 의존성이 이미 설치된 환경에서 선택한다.

13관련 기술 심화 학습 로드맵

매주 읽은 내용을 작은 결과물로 남기면, 스킬을 설치하는 방법을 넘어 절차를 설계하는 방법까지 배울 수 있다. 표의 경로는 모두 레포 루트 기준이며, 결과물은 학습자가 작성할 메모와 설계안이다.

마지막에는 “지침에 적힌 규칙”, “스크립트가 검사하는 조건”, “사람이 확인할 결과”를 따로 설명해 본다. 이 구분이 되면 다른 분야의 에이전트 스킬을 읽을 때도 자동화할 부분과 검토할 부분을 판단하기 쉬워진다.

14핵심 키워드 사전