# Skill
URL: /ai-integration/skill
Source: https://github.com/daangn/seed-design/blob/dev/docs/content/ai-integration/skill/index.mdx

SEED 통합 스킬. 공통 디자인 지식과 React·Lynx 구현 문서를 구분해 안내하고, 플랫폼별 진단 절차를 수행합니다.

`seed-design` 스킬은 AI 에이전트가 SEED를 쓰는 프로젝트를 도울 때 로드하는 가이드입니다.

**문서에 이미 있는 것은 스킬에 옮겨 적지 않습니다.** 셋업 절차나 컴포넌트 목록, 토큰 이름은 공식 문서와 `docs` CLI가 원본이고 복사본은 원본보다 먼저 낡습니다. 스킬은 질문을 다음 세 층으로 나눠 필요한 원본을 찾습니다.

1. **공통 디자인 지식** — 컴포넌트 Anatomy·Properties·Guidelines와 색상·타이포그래피·스페이싱 같은 Foundations
2. **플랫폼 구현** — React 또는 Lynx의 API, 설치, 스니펫, 코드 작성
3. **적응형 Doctor** — `seed-design.json`과 직접 의존성으로 워크스페이스 맥락을 찾고, 설정·호환·셋업·Foundations·컴포넌트·라이브러리 중 적용 가능한 건강검진을 실행

공통 컴포넌트 스펙과 Foundations는 프로젝트나 플랫폼을 확인하지 않고 바로 조회합니다. 구현·설치·Doctor처럼 결과가 달라지는 요청만 **사용자 명시 → 대상 워크스페이스의 `seed-design.json.framework` → 직접 의존성** 순으로 플랫폼을 판별합니다. 모노레포에서 React와 Lynx가 함께 발견되거나 단서가 없으면 에이전트가 React를 추측하지 않고 사용자에게 확인합니다.

## Documentation routing

스킬은 문서 목록이나 플랫폼 지원표를 갖지 않고 아래 인덱스를 현재 상태의 단일 원천으로 사용합니다.

- [SEED 전체 문서 인덱스](https://seed-design.io/llms.txt)
- [React 문서 인덱스](https://seed-design.io/react/llms.txt)
- [Lynx 문서 인덱스](https://seed-design.io/lynx/llms.txt)

전체 인덱스에서 공통 Components·Foundations와 플랫폼 진입점을 찾고, 선택된 플랫폼 인덱스에서 필요한 leaf 문서를 찾습니다. 경로·CLI id·지원 capability를 기억으로 조합하지 않습니다. 문서나 registry 항목이 없으면 다른 플랫폼으로 대체하지 않고 현재 인덱스에서 확인한 부재를 안내합니다.

Doctor도 같은 관계를 사용합니다. 공통 룰은 고정하되 현재 인덱스가 공식 계약을 제공하는지에 따라 실행 시점에 `pass | fail | not-applicable | not-verified`를 정합니다. 자세한 내용은 [Doctor](/ai-integration/skill/doctor)를 참고하세요.

## Installation

`seed-design` 스킬을 설치하려면 다음 명령어를 사용하세요.

- npm: npx skills add https://github.com/daangn/seed-design --skill seed-design
- pnpm: pnpm dlx skills add https://github.com/daangn/seed-design --skill seed-design
- yarn: yarn dlx skills add https://github.com/daangn/seed-design --skill seed-design
- bun: bun x skills add https://github.com/daangn/seed-design --skill seed-design

## File Structure

<File name="SKILL.md" />

<File name="migration.md" />

<File name="upgrade.md" />

<File name="doctor.md" />

<File name="doctor-react.md" />

<File name="doctor-lynx.md" />

<File name="project-config.md" />

<File name="package-compatibility.md" />

<File name="project-setup.md" />

<File name="snippet-compatibility.md" />

<File name="foundation-contract.md" />

<File name="library-authors.md" />

<File name="outdated-version.md" />

<File name="snippet-generation.md" />

<File name="no-deprecated-component.md" />

<File name="component-guidelines.md" />

<File name="doctor-report.schema.json" />

<File name="report-template.html" />

| 파일                           | 언제 읽는가                                            |
| ---------------------------- | ------------------------------------------------- |
| `SKILL.md`                   | 진입점. 프로젝트 상태를 파악하고 아래로 분기합니다                      |
| `references/migration.md`    | 현재 인덱스의 CLI 문서로 스니펫 호환·파일 충돌 절차를 구성               |
| `references/upgrade.md`      | 현재 인덱스의 upgrade·changelog로 마이그레이션 경로를 구성          |
| `references/doctor.md`       | 플랫폼 판별, 인덱스 기반 capability 발견, 공통 실행 절차와 리포트 계약    |
| `references/doctor-react.md` | React 인덱스·패키지·registry 탐색 시작점                     |
| `references/doctor-lynx.md`  | Lynx 인덱스·패키지·registry 탐색 시작점                      |
| `rules/*.md`                 | 선택된 Doctor 프로필과 적용 조건으로 실행되는 공통 판정 기준이자 코드 작성 가이드 |

## SKILL.md

````md
---
name: seed-design
description: SEED Design 통합 가이드. 공통 컴포넌트 스펙과 파운데이션을 공식 문서에서 찾고, React·Lynx 프로젝트의 구현·설치·CLI·마이그레이션을 대상 플랫폼에 맞게 안내하며, 지원되는 플랫폼의 사용 상태를 Doctor로 진단한다. SEED Design 관련 질문, 컴포넌트 사용법, 색상·타이포·스페이싱, 셋업, 스니펫, 업그레이드, "잘 쓰고 있나?", "뭘 고쳐야 하나?" 같은 요청이면 이 스킬을 사용한다.
user-invocable: true
argument-hint: "[질문 또는 주제]"
---

# SEED Design

SEED Design의 공식 문서와 CLI를 단일 원천으로 사용합니다. 이 스킬에는 문서 내용을 복사하지 않고, **공통 디자인 지식 → 플랫폼 구현 → 플랫폼별 Doctor**로 이어지는 탐색·판정 절차만 둡니다.

## 1. 요청을 먼저 분류

프로젝트를 조사하기 전에 요청을 다음 중 하나로 분류합니다.

| 분류 | 예 | 플랫폼 판별 |
|---|---|---|
| 공통 컴포넌트 스펙·Foundations | Anatomy, Properties, Guidelines, 색상, 타이포그래피, 스페이싱 | 불필요 |
| 플랫폼 구현 | 사용법, Props, 설치, 셋업, 스니펫, 코드 작성, CLI 실행 | 필요 |
| Doctor·마이그레이션 | 사용 상태 진단, deprecated, 호환성, 업그레이드 | 필요 |

공통 스펙이나 Foundations만 묻는다면 프로젝트가 없어도 바로 공통 문서를 읽습니다. 구현 코드까지 함께 묻는다면 공통 문서를 먼저 읽은 다음, 플랫폼을 판별하고 해당 플랫폼 문서를 결합합니다.

## 2. 플랫폼 판별

플랫폼에 따라 결과가 달라지는 요청에만 아래 순서를 적용합니다.

1. **사용자가 명시한 플랫폼**: React 또는 Lynx
2. **대상 워크스페이스의 설정**: `seed-design.json.framework`
3. **대상 워크스페이스의 직접 의존성**
   - React: `@seed-design/react`, `@seed-design/css`
   - Lynx: `@seed-design/lynx-react`, `@seed-design/lynx-css` 또는 `@lynx-js/react`

높은 순위의 명확한 단서를 낮은 순위의 단서로 덮어쓰지 않습니다. 단, 같은 대상 안에서 설정과 의존성이 충돌한다면 설정이 낡았을 수 있으므로 사용자에게 확인합니다.

모노레포에서는 루트 `package.json`만 보지 말고 요청 대상 워크스페이스를 먼저 찾습니다. 루트 요청에서 React와 Lynx 워크스페이스가 함께 발견되거나 대상 경로가 불명확하면, 구현·설치·Doctor를 시작하기 전에 어느 워크스페이스 또는 플랫폼인지 묻습니다.

단서가 없거나 한 단계에서 여러 플랫폼이 동시에 잡혀도 사용자에게 묻습니다. **불확실한 상황에서 React를 기본값으로 사용하지 않습니다.** 이는 에이전트의 문서 라우팅 규칙이며, 기존 CLI의 공개 동작이나 `seed-design.json` 기본값을 바꾸는 규칙이 아닙니다.

플랫폼 판별 뒤에는 다음 프로젝트 정보도 필요할 때만 수집합니다.

- `seed-design.json`의 `path`와 해당 디렉토리의 `@file` 헤더 파일 → 스니펫 설치 여부
- 설치된 `@seed-design/*` 버전
- 번들러 설정 (`vite.config`, `rsbuild.config`, `webpack.config` 등)
- lock 파일로 판별한 패키지 매니저 (`bun` → `pnpm` → `yarn` → `npm`)

## 3. 공식 문서 라우팅

문서 목록과 지원 범위를 스킬에 복사하지 않습니다. 요청할 때마다 아래 인덱스를 먼저 읽고, 인덱스가 제공한 링크를 그대로 따라갑니다.

- 전체 문서 인덱스: `https://seed-design.io/llms.txt`
- React 문서 인덱스: `https://seed-design.io/react/llms.txt`
- Lynx 문서 인덱스: `https://seed-design.io/lynx/llms.txt`

한 요청 실행 안에서는 URL을 정규화한 문서 풀을 유지합니다. 전체 인덱스, 선택된 플랫폼 인덱스, 각 leaf 문서는 URL마다 한 번만 읽고 이후 단계와 룰에서 같은 내용을 재사용합니다. 리포트 `references`에 같은 URL을 반복하는 것은 출처를 보존하는 것이며 다시 읽으라는 뜻이 아닙니다. HTTP 캐시를 가정하지 않습니다.

다음 순서를 지킵니다.

1. 전체 문서 인덱스에서 공통 Components·Foundations·Patterns 또는 선택된 플랫폼의 현재 진입점을 찾습니다.
2. 플랫폼 구현 요청이면 선택된 플랫폼 인덱스를 읽고, 제목·category·설명으로 필요한 문서를 찾습니다.
3. 인덱스가 제공한 leaf URL을 열어 실제 계약을 읽습니다. 기억한 경로나 URL 조합으로 leaf 문서를 만들지 않습니다.
4. 인덱스를 정상적으로 읽었는데 관련 항목이 없으면 현재 공식 문서가 없다고 판단합니다. 인덱스 자체를 읽지 못했으면 부재로 확정하지 않습니다.

CLI의 `docs` 명령을 사용할 때도 먼저 인덱스에서 문서와 id를 확인합니다. URL 경로와 CLI id가 같다고 가정하지 말고, id를 확정할 수 없으면 인덱스의 URL을 직접 읽습니다.

### 컴포넌트 답변 순서

1. 스펙 질문이면 공통 컴포넌트 문서만 읽습니다.
2. 구현 질문이면 플랫폼을 판별하고 해당 플랫폼 문서를 읽습니다.
3. 스펙과 구현을 함께 묻는다면 공통 문서를 먼저 읽고, 판별된 플랫폼 문서를 이어서 읽습니다.
4. 공통 문서 id와 구현 문서 id가 다르면 공통 문서의 Platform 표와 선택된 플랫폼 인덱스로 실제 id를 찾습니다.
5. 선택한 플랫폼 문서나 registry 항목이 없으면 그 플랫폼의 구현·문서가 없다고 알립니다. 다른 플랫폼 문서로 대체하지 않습니다.

스니펫이 필요하면 선택한 플랫폼 registry만 사용합니다.

```text
https://seed-design.io/__registry__/{react|lynx}/{registryId}/index.json
https://seed-design.io/__registry__/{react|lynx}/{registryId}/{itemId}.json
```

개별 스니펫 경로는 `{itemId}/index.json`이 아니라 `{itemId}.json`입니다.

### CLI 문서

전체·플랫폼 인덱스에서 `CLI`, `Commands`, `Configuration`에 해당하는 현재 링크를 찾고 내용을 읽습니다. 문서가 어느 플랫폼 트리 아래에 있는지만으로 지원 플랫폼이나 옵션을 추론하지 않습니다. 명령·플래그·설정 필드는 연결된 문서 또는 설치한 CLI 소스가 명시한 값만 사용합니다.

## 4. 판단이 필요한 절차

| 요청 | 읽을 참조 |
|---|---|
| 스니펫 버전 맞추기, 파일 충돌, 패키지 호환 | [migration.md](references/migration.md) |
| changelog 해석과 업그레이드 경로 | [upgrade.md](references/upgrade.md) |
| 코드 사용 상태 진단 | [doctor.md](references/doctor.md) |

마이그레이션과 업그레이드도 플랫폼을 먼저 판별합니다. 참조 파일의 React 전용 옵션이나 호환표를 Lynx에 적용하지 말고, 선택된 플랫폼의 패키지와 changelog만 대조합니다.

Doctor 요청은 [doctor.md](references/doctor.md)의 적응형 탐색 절차를 먼저 따릅니다.

1. 사용자 지정 경로
2. `node_modules`, `.git`, `.claude/worktrees`를 제외한 `seed-design.json`
3. 설정 발견 여부와 관계없이 직접 `@seed-design/*` 의존성이 있는 workspace
4. 두 후보를 package 경계로 중복 제거
5. 사용자 명시 → `framework` → 직접 의존성 순의 플랫폼 확정
6. 공개 진입점과 앱·라이브러리 빌드 증거에 따른 비배타적 역할 판정

- React Doctor: [doctor-react.md](references/doctor-react.md)를 함께 읽습니다.
- Lynx Doctor: [doctor-lynx.md](references/doctor-lynx.md)를 함께 읽습니다.

플랫폼 프로필은 문서 지원 현황을 복제하지 않고 인덱스·패키지·registry 탐색의 시작점만 제공합니다. 일반 진단은 공통 룰 전체를 scope에 넣고, 현재 인덱스에서 발견한 공식 계약과 각 룰의 적용 조건으로 검사 여부를 정합니다. 사용자가 config·setup·foundations·components·compatibility·library 중 범주를 지정했다면 그 범주만 실행합니다. 여러 workspace의 전체 진단은 리포트를 workspace별로 따로 만듭니다.

Doctor는 문제를 찾는 진단이고, `upgrade.md`는 실제로 버전을 올리는 절차입니다. 진단이 버전 격차를 알려도 사용자가 수정을 요청하기 전에는 업그레이드를 실행하지 않습니다.

## 5. 코드 작성과 기존 코드 진단

`rules/`의 룰은 SEED 코드를 작성할 때 지키는 계약이자 Doctor의 판정 기준입니다. Doctor에서는 선택된 플랫폼 프로필과 각 룰의 적용 조건을 함께 사용합니다.

- [project-config](rules/project-config.md): 현재 CLI 설정 계약, framework 충돌, snippet path·alias 연결
- [package-compatibility](rules/package-compatibility.md): 플랫폼 패키지 설치본 조합
- [project-setup](rules/project-setup.md): 선택된 플랫폼 문서가 요구하는 앱 설치·스타일 연결
- [snippet-compatibility](rules/snippet-compatibility.md): 현재 패키지와 설치 스니펫의 CLI `compat` 결과
- [foundation-contract](rules/foundation-contract.md): 토큰 존재·공개성·내부 스타일 API 의존
- [library-authors](rules/library-authors.md): 공식 저자 문서가 있는 플랫폼의 peer·external·CSS·배포 계약
- [outdated-version](rules/outdated-version.md): 직접 설치한 패키지의 최신 세대 격차만
- [snippet-generation](rules/snippet-generation.md): 설치 스니펫과 registry의 최신 세대 차이만
- [no-deprecated-component](rules/no-deprecated-component.md): 플랫폼에 유효한 출처가 있는 deprecated 항목만
- [component-guidelines](rules/component-guidelines.md): 공통 디자인 문서와 매핑 가능한 플랫폼 구현의 대조

토큰은 문서·CSS·플랫폼 API에서 표기가 달라질 수 있습니다. 공통 Foundations 문서에서 의미와 토큰을 확인한 뒤, 코드 표기는 선택된 플랫폼 구현 문서에서 확인합니다. 한 플랫폼의 코드 표기를 다른 플랫폼에 복사하지 않습니다.

## 6. 응답과 실행 원칙

- 공식 문서를 실제로 읽고 근거 링크와 함께 답합니다.
- 설치·실행 명령은 대상 프로젝트의 패키지 매니저에 맞춥니다.
- read-only 진단과 실제 수정 요청을 구분합니다.
- Doctor 결과는 schema v2 YAML을 단일 원천으로 임시 디렉토리에 기록하고, 사용자가 "YAML만"을 명시하지 않으면 같은 디렉토리에 HTML 리포트도 함께 생성합니다. 대상 프로젝트에는 쓰지 않습니다.
- 각 finding의 `remediation`에는 대상·문제·요구사항·제약·근거·검증을 포함한 복사 가능한 수정 프롬프트를 기록합니다. 프롬프트를 만드는 것은 진단이며, 사용자가 별도로 수정을 요청하기 전에는 실행하지 않습니다.
- 없는 경로나 API를 추측하지 않습니다.
- 작업이 끝나면 현재 맥락에 맞는 다음 단계만 짧게 제안합니다.
````

## References

### migration.md

스니펫이 요구하는 버전과 설치된 패키지가 맞는지, 현재 CLI 문서가 제공하는 방식으로 커스터마이징을 어떻게 보존할지 다룹니다.

```md
# Migration (스니펫)

스니펫을 현재 프로젝트 패키지와 맞추고 로컬 파일 충돌을 안전하게 해결하는 절차입니다. 패키지 업그레이드 경로는 [upgrade.md](upgrade.md), 읽기 전용 진단은 [doctor.md](doctor.md)를 사용합니다.

## 문서 발견

1. `https://seed-design.io/llms.txt`를 읽습니다.
2. 선택된 플랫폼의 `llms.txt`에서 현재 CLI·Commands·Configuration·registry 문서를 찾습니다.
3. 인덱스가 연결한 문서에서 호환 검사, 버전 선택, 파일 충돌 처리에 관한 현재 명령과 옵션을 읽습니다.

명령·플래그·아카이브 registry 주소를 이 파일에 유지하지 않습니다. 문서 위치가 다른 플랫폼 트리 아래에 있더라도 본문이 선택된 플랫폼 지원을 명시할 때만 사용합니다.

## 절차

1. lockfile로 패키지 매니저를 정하고 실제 설치본 패키지 버전을 읽습니다.
2. 현재 CLI 문서가 안내하는 읽기 전용 호환 검사로 설치 스니펫의 `@requires`와 패키지 버전을 대조합니다.
3. 패키지끼리의 호환은 설치본 peerDependencies와 플랫폼 인덱스가 연결한 호환 문서로 별도 확인합니다. 스니펫 검사 결과로 패키지 조합까지 통과했다고 판단하지 않습니다.
4. 현재 CLI 문서가 대상 버전용 스니펫이나 registry 선택 방식을 제공하면 그 문서의 방식만 사용합니다.
5. 파일이 달라 충돌하면 문서가 제공하는 backup·overwrite·skip 동작을 확인합니다. 로컬 커스터마이징이 있으면 복구 가능한 backup 방식을 우선 제안하고 실제 변경 전 사용자 요청을 확인합니다.
6. 작은 컴포넌트 단위로 갱신하고 동작·스타일을 검증한 뒤 다시 호환 검사를 실행합니다.

## 판정 경계

- 스니펫의 현재 패키지 호환: CLI 호환 검사
- 패키지끼리의 호환: 설치본 metadata + 현재 공식 호환 문서
- 최신 스니펫 세대와의 차이: canonical registry와 현재 공식 세대 근거
- 로컬 코드 차이: 자동 덮어쓰기 근거가 아니라 merge 대상

문서·registry를 읽지 못하면 현재 명령이나 지원 버전을 추측하지 않습니다.
```

### upgrade.md

현재 버전에서 목표 버전까지의 변경사항을 읽고 마이그레이션 경로를 제시합니다. CLI는 데이터를 가져오기만 하고 해석과 판단은 스킬이 합니다.

```md
# Upgrade & Compatibility

설치된 SEED 패키지와 스니펫의 현재 상태를 공식 upgrade·changelog 문서에 연결해 업그레이드 경로를 구성합니다. CLI와 registry는 데이터를 제공하고, 이 절차는 프로젝트 영향과 순서를 해석합니다.

## 문서 발견

1. `https://seed-design.io/llms.txt`에서 선택된 플랫폼 진입점을 찾습니다.
2. 선택된 플랫폼의 `llms.txt`에서 현재 upgrade·migration·changelog·CLI 문서를 찾습니다.
3. 공유 라이브러리이면 같은 인덱스에서 Library Authors 또는 같은 역할의 배포 계약 문서를 추가로 찾습니다.
4. 인덱스가 제공한 leaf URL과 문서가 안내한 CLI id만 사용합니다. 버전 경계·changelog 경로·호환표를 이 파일에 복사하지 않습니다.

인덱스를 정상적으로 읽었는데 업그레이드 문서가 없으면 공식 경로 부재를 알리고 다른 플랫폼 문서를 이식하지 않습니다. 인덱스나 연결 문서를 읽지 못하면 부재로 확정하지 않습니다.

## Workflow

### 1. 대상과 버전 확정

- 플랫폼과 워크스페이스를 먼저 확정합니다.
- package.json 선언 범위가 아니라 hoist를 고려한 실제 설치본 버전을 읽습니다.
- node_modules와 lockfile을 읽을 수 없을 때만 선언 범위 하한을 임시 입력으로 쓰고 과다 보고 가능성을 밝힙니다.
- 목표 버전이 없으면 현재 registry latest와 사용자가 원하는 업그레이드 범위를 확인합니다.

### 2. 현재 호환 진단

- 구현·스타일 패키지 조합은 실제 설치본 peerDependencies를 먼저 봅니다.
- 현재 버전 구간에 별도 호환표가 필요하다고 upgrade 문서가 명시하면 인덱스가 연결한 그 표를 읽습니다.
- 스니펫 호환은 현재 CLI 문서가 안내하는 읽기 전용 검사로 분리합니다.
- 문서와 metadata가 충돌하면 둘 다 근거로 남기고 임의로 버전 규칙을 만들지 않습니다.

### 3. 변경사항 수집

- 플랫폼 인덱스가 연결한 changelog에서 현재 설치본 이후 목표 버전까지의 항목을 가져옵니다.
- 문서가 제공하는 package slug·버전 조회 방식을 그대로 사용합니다.
- 목표 버전보다 높은 항목은 SemVer로 필터링합니다.
- breaking, 재설치 필요, 동작 변경, updated dependencies를 구분합니다.

### 4. 프로젝트 영향 분석

- 변경된 컴포넌트·prop·토큰·API를 실제 코드에서 찾습니다.
- 패키지·스니펫·내부 스타일 API 영향을 분리합니다.
- 사용하지 않는 변경은 영향 없음으로, 코드 밖 확인이 필요한 항목은 미검증으로 남깁니다.

### 5. 경로와 순서 제시

1. 공식 호환 계약에 맞는 패키지 조합
2. breaking 변경 대응
3. 현재 CLI 문서가 지목한 스니펫 갱신
4. 호환 검사와 프로젝트 테스트

설치 명령은 대상 프로젝트의 패키지 매니저로 제시하되 사용자가 실제 수정을 요청하기 전에는 실행하지 않습니다. 공유 라이브러리는 현재 저자 문서가 요구하는 peer·external·CSS 배포 계약도 함께 반영합니다.

## 보고 형식

- 현재/목표 패키지와 근거 문서
- 즉시 수정할 호환 오류
- 버전 경계별 breaking과 영향 파일
- 스니펫 재설치·merge 대상
- 미적용·미검증 항목과 이유
- 단계별 실행·검증 순서
```