shadcn

shadcn skill 개요

shadcn skill은 무엇에 쓰이나요

shadcn skill은 AI 어시스턴트가 실제 shadcn/ui 프로젝트 안에서 정확하게 작업하도록 돕습니다. 컴포넌트를 찾고, 올바른 CLI로 설치하고, 이미 있는 프리미티브를 조합해 화면을 구성하며, 프리셋과 컴포넌트 계열마다 달라지는 흔한 API 실수를 피하게 해줍니다. 단순히 “버튼 하나 만들어줘” 수준이 아니라, components.json, 현재 설치된 레지스트리 항목, 사용 중인 템플릿, 그리고 base와 radix의 차이까지 반영한 결과가 필요할 때 특히 유용한 shadcn skill입니다.

어떤 사람이 이 shadcn skill을 써야 하나요

특히 잘 맞는 사용자는 다음과 같습니다:

• 이미 shadcn/ui를 쓰고 있는 개발자
• 프리셋 또는 레지스트리 중심 UI 워크플로를 도입하는 팀
• AI에게 폼, 다이얼로그, 설정 페이지, 대시보드, 테마 작업의 추가나 리팩터링을 맡기려는 사람
• JSX를 쓰기 전에 먼저 프로젝트 맥락을 확인하길 원하는 사람

반대로 shadcn/ui, components.json, shadcn CLI를 쓰지 않는다면 이 skill은 다소 지나치게 특화되어 있을 수 있습니다.

실제로 해결하는 일

사용자가 원하는 것은 단순한 저장소 요약이 아닙니다. 실제로는 어시스턴트가 다음을 해주길 원합니다:

1. 프로젝트의 shadcn 구성을 감지하고,
2. 새 컴포넌트를 지어내기 전에 기존 컴포넌트를 먼저 선택하고,
3. 정확한 CLI 명령과 문서화된 플래그만 사용하고,
4. 라이브러리가 권장하는 패턴으로 UI를 조합하고,
5. 잘못된 trigger 조합, 빠진 group wrapper, 틀린 form validation 연결처럼 눈에 잘 안 띄는 문제를 피하는 것.

바로 이 지점에서 shadcn skill은 일반적인 UI 프롬프트보다 더 큰 가치를 제공합니다.

shadcn이 일반 프롬프트와 다른 점

shadcn skill의 차별점은 실제 작업 흐름에 바로 도움이 된다는 점입니다:

• npx shadcn@latest info --json으로 프로젝트 컨텍스트부터 확인합니다
• 커스텀 구현에 들어가기 전에 search, view, docs를 우선합니다
• rules/composition.md, rules/forms.md, rules/styling.md, rules/base-vs-radix.md 같은 파일의 프로젝트 규칙을 반영합니다
• 단순한 컴포넌트 스니펫이 아니라 테마와 프리셋 전환까지 다룹니다
• 레지스트리 검색과 설치 워크플로를 위한 MCP 가이드도 포함합니다

즉, shadcn skill은 “React를 작성해라”보다 “이 shadcn 구성에 맞는 올바른 React를 작성해라”에 더 가깝습니다.

도입 전에 알아둘 제약 사항

이 skill에 의존하기 전에 다음 제약은 꼭 알아두어야 합니다:

• 프로젝트의 패키지 실행기인 npx, pnpm dlx, bunx --bun을 통해 shadcn CLI에 접근할 수 있다고 가정합니다
• 문서화된 CLI 플래그 범위 안에서만 동작하며, 없는 플래그를 만들어내면 안 된다고 명시합니다
• 좋은 결과물 상당수는 유효한 components.json이 있어야 가능합니다
• API 세부사항은 프리셋과 base/radix에 따라 달라질 수 있으므로, 예제를 무작정 재사용하면 틀릴 수 있습니다

shadcn skill 사용 방법

shadcn skill을 쓸 때 필요한 설치/실행 맥락

디렉터리의 표준 설치 방식으로 AI 환경에 skill을 추가한 뒤, 실제로 shadcn 구성이 있거나 앞으로 들어갈 저장소에서 사용하세요. 실무에서는 skill 설치 명령 자체보다 저장소 쪽 조건이 더 중요합니다. 어시스턴트가 프로젝트 파일에 접근할 수 있어야 하고, shadcn CLI 명령도 실행할 수 있어야 합니다.

대상 프로젝트 안에서 핵심적으로 쓰는 명령은 다음과 같습니다:

• npx shadcn@latest info --json
• npx shadcn@latest search <query>
• npx shadcn@latest view <item>
• npx shadcn@latest docs <component>
• npx shadcn@latest add <component>

프로젝트의 패키지 매니저가 다르다면 pnpm dlx shadcn@latest 또는 bunx --bun shadcn@latest로 바꿔 쓰면 됩니다.

결과를 요청하기 전에 먼저 읽어야 할 파일

빠르고 정확하게 shadcn skill을 활용하려면 대략 다음 순서로 파일을 확인하는 것이 좋습니다:

1. SKILL.md
2. cli.md
3. rules/composition.md
4. rules/base-vs-radix.md
5. rules/forms.md
6. rules/styling.md
7. customization.md
8. mcp.md

이 순서가 잘 작동하는 이유는 다음과 같습니다:

• SKILL.md는 언제 이 skill을 트리거해야 하는지와 기본 워크플로를 정의합니다
• cli.md는 추측성 명령어나 잘못된 플래그 사용을 막아줍니다
• rules/ 파일들은 일반 코드 생성이 자주 내는 실수를 구체적으로 담고 있습니다
• customization.md는 단순한 Tailwind 색상 꼼수가 아니라 테마에 안전한 스타일링이 필요할 때 중요합니다
• mcp.md는 셸 명령 대신 MCP로 레지스트리를 탐색할 수 있는 환경에서 특히 중요합니다

모든 shadcn 작업은 프로젝트 탐색부터 시작하세요

가장 효과적인 첫 단계는 단 하나입니다:

npx shadcn@latest info --json

이 명령은 현재 무엇이 설정되어 있는지, 컴포넌트와 프로젝트 맥락을 포함해 어시스턴트에게 알려줍니다. 특히 다음 상황에서 유용합니다:

• components.json 존재 여부 확인
• 설치된 컴포넌트 식별
• 어떤 코드 선택이 유효한지 바꾸는 구성 세부사항 감지
• 패키지 실행기를 확인해 잘못된 명령 예시를 피하기

이 단계를 건너뛰면 shadcn skill은 일반 프롬프트와 크게 다르지 않게 됩니다.

막연한 요구를 좋은 shadcn 프롬프트로 바꾸는 법

약한 프롬프트:

Build me a profile dialog with shadcn.

더 좋은 프롬프트:

In this existing shadcn/ui app, inspect components.json and run npx shadcn@latest info --json first. We use the radix setup and lucide-react. Create a profile edit dialog using existing shadcn components only where possible. Include avatar, name, bio, Save/Cancel actions, accessible title, semantic tokens, and no raw color classes. If a component is missing, tell me the exact shadcn add command before generating code.

왜 이 프롬프트가 더 강한가:

• 프로젝트 탐색을 강제합니다
• 프리셋에 민감한 동작을 지정합니다
• 아이콘과 스타일링 제약을 분명히 합니다
• 필요한 의존성이 없을 때 설치 단계부터 안내하도록 만듭니다

커스텀 코드를 쓰기 전에 search와 docs를 먼저 사용하세요

품질 좋은 shadcn 워크플로는 보통 다음 순서입니다:

1. 레지스트리에서 기존 컴포넌트를 검색하고,
2. 문서와 예제를 확인하고,
3. 부족한 항목을 추가한 뒤,
4. 화면을 조합합니다.

실전 명령 예시는 다음과 같습니다:

npx shadcn@latest search dialog
npx shadcn@latest docs dialog
npx shadcn@latest view @shadcn/dialog

이 순서는 특히 form, overlay, navigation, empty state에서 중요합니다. 이 영역에서는 임시방편 div 구조보다 라이브러리 패턴을 우선하라는 shadcn skill의 규칙이 강하게 작동합니다.

화면은 기존 빌딩 블록으로 조합하세요

shadcn skill은 거대한 커스텀 UI를 한 번에 만드는 것보다, 조합 중심으로 요청할 때 가장 강합니다. 좋은 작업 프레이밍 예시는 다음과 같습니다:

• “settings page = Tabs + Card + form controls”
• “dashboard = Sidebar + Card + Chart + Table”
• “empty state = Empty component, not a custom centered div”
• “callout = Alert, not hand-rolled border boxes”

이 방식은 shadcn skill이 선호하는 흐름과도 맞습니다. 먼저 기존 컴포넌트를 쓰고, 정말 필요할 때만 variant나 wrapper를 조정하세요.

base와 radix의 차이를 반드시 존중하세요

shadcn 도입 시 가장 자주 막히는 지점 중 하나는 모든 shadcn 예제가 서로 바꿔 써도 된다고 가정하는 것입니다. 실제로는 그렇지 않습니다.

shadcn skill에는 base와 radix 차이에 대한 명시적인 가이드가 포함되어 있으며, 다음 항목들을 다룹니다:

• asChild vs render
• trigger 조합 방식 차이
• 특정 base 전용 상황의 nativeButton={false}
• Select, ToggleGroup, Slider, Accordion 같은 컴포넌트 API 차이

프롬프트에 어떤 구성을 쓰는지 없으면, 어시스턴트에게 npx shadcn@latest info 결과로 감지하라고 요청하세요.

테마를 망치지 않는 스타일링 가이드를 쓰세요

UI Design 관점의 shadcn 작업에서는 하드코딩된 Tailwind 색상보다 semantic token과 CSS 변수 기반 테마가 훨씬 좋은 결과를 냅니다.

권장:

• bg-background
• text-foreground
• text-muted-foreground
• text-destructive

가급적 피할 것:

• bg-red-500
• text-gray-400
• 과도한 수동 dark: 오버라이드

이게 중요한 이유는 customization.md에서 컴포넌트가 CSS 변수를 상속받는다고 설명하기 때문입니다. 어시스턴트가 semantic token을 쓰면 라이트/다크 테마와 여러 프리셋에 걸쳐 디자인이 훨씬 안정적으로 확장됩니다.

폼은 shadcn 방식으로 다루세요

평가와 규칙을 보면 폼 품질은 이 skill이 특히 신경 쓰는 영역입니다. shadcn skill로 좋은 폼 결과를 얻으려면 보통 다음이 포함되어야 합니다:

• 단순히 div를 쌓는 대신 제공된 필드 레이아웃 패턴 사용
• data-invalid와 aria-invalid로 잘못된 상태 표시
• 서로 독립적인 on/off 설정에는 Switch 사용
• 규칙에서 요구할 때 space-y-*보다 gap-* 간격 선호

작업에 validation이 포함된다면 프롬프트에 명확히 적어주세요. 그렇지 않으면 많은 어시스턴트가 겉보기에는 그럴듯하지만 라이브러리 방식과 어긋나는 폼을 생성합니다.

에디터가 지원한다면 MCP를 활용하세요

환경이 MCP를 지원한다면 shadcn skill은 레지스트리 작업에서 더 신뢰할 수 있게 됩니다. mcp.md에는 다음을 위한 도구가 문서화되어 있습니다:

• 프로젝트 레지스트리 목록 조회
• 레지스트리 항목 검색
• 항목 상세와 파일 내용 보기
• 예제 가져오기
• 항목 설치

이 방식은 CLI 출력에만 의존하지 않고, 어시스턴트가 대화형으로 레지스트리를 탐색하길 원할 때 유용합니다. 다만 프로젝트 설정 확인용 info --json을 대체하는 것은 아닙니다.

shadcn skill을 잘 쓰기 위한 실전 프롬프트 템플릿

더 나은 결과가 필요하다면 아래 템플릿을 사용하세요:

Use the shadcn skill for this task. First inspect the project with `npx shadcn@latest info --json` and read `components.json` if present. Confirm whether this project uses `base` or `radix`. Search for existing components before building custom UI. If something is missing, give the exact documented `shadcn add` command. Then generate the component using semantic tokens, correct composition rules, and the project’s icon library.

Goal: [what you want to build]
Screen context: [page/dialog/form/dashboard/etc.]
Existing components: [if known]
Framework/template: [Next.js/Vite/Astro/etc.]
Constraints: [icons, validation, dark mode, accessibility, no raw colors, no guessed APIs]
Output needed: [component code, install commands, explanation, refactor diff]

shadcn skill FAQ

이 shadcn skill은 컴포넌트 설치용인가요?

아니요. shadcn install 작업도 일부이긴 하지만 범위는 더 넓습니다. 프로젝트 점검, 레지스트리 검색, 컴포넌트 조합, 테마 작업, 디버깅, 프리셋 전환, API를 정확히 지키는 리팩터링까지 모두 shadcn skill의 대상입니다.

shadcn skill은 초보자도 쓰기 쉬운가요?

네, React와 패키지 매니저 사용에 이미 익숙하다면 충분히 접근하기 쉽습니다. 이 skill은 어시스턴트를 올바른 명령과 규칙으로 유도해 추측을 줄여줍니다. 다만 React, Tailwind, 디자인 시스템을 처음부터 전부 배워야 하는 상황이라면 초보자 친화적이라고 보긴 어렵습니다.

언제 shadcn이 일반 프롬프트보다 낫나요?

정확성이 프로젝트 맥락에 달려 있을 때는 shadcn skill을 쓰는 편이 낫습니다:

• 기존 components.json
• 현재 설치된 컴포넌트와의 일치
• base와 radix의 동작 차이
• 문서화된 CLI 플래그만 사용해야 하는 조건
• 테마 토큰과 라이브러리 조합 규칙을 유지해야 하는 경우

일반 프롬프트도 그럴듯한 JSX는 만들 수 있지만, 설치 단계가 빠지거나 컴포넌트 API를 잘못 사용할 가능성이 더 큽니다.

언제는 shadcn skill을 쓰지 않는 편이 좋은가요?

다음이라면 굳이 쓰지 않아도 됩니다:

• 프로젝트가 shadcn/ui를 사용하지 않을 때
• 일반적인 HTML/CSS 목업만 필요할 때
• 특정 디자인 시스템에 얽매이지 않는 답변을 원할 때
• 어시스턴트가 파일을 확인하거나 명령을 실행할 수 없고, 필요한 컨텍스트도 수동으로 제공하기 어려울 때

이런 경우에는 더 범용적인 프론트엔드 skill이 더 잘 맞을 수 있습니다.

이 skill은 UI Design 관점의 shadcn 의사결정에도 도움이 되나요?

네. 특히 조합과 테마 측면에서 유용합니다. 재사용 가능한 프리미티브, semantic color token, 올바른 overlay 패턴, 그리고 일회성 수제 레이아웃보다 유지보수하기 쉬운 컴포넌트 구조로 어시스턴트를 유도합니다.

AI 출력에서 shadcn 사용이 주로 어디서 깨지나요?

흔한 실패 사례는 다음과 같습니다:

• 지원되지 않는 CLI 플래그를 지어내는 경우
• base와 radix에 맞지 않는 trigger 조합 사용
• 기존 레지스트리 컴포넌트를 두고 굳이 커스텀 UI를 만드는 경우
• 테마 시스템과 충돌하는 원시 색상으로 스타일링하는 경우
• title, group, fallback 같은 필수 하위 컴포넌트를 빼먹는 경우

이런 부분이 바로 shadcn skill이 가장 단단하게 보정하려는 영역입니다.

shadcn skill 개선 방법

빠진 컨텍스트를 처음부터 shadcn skill에 주세요

가장 효율이 큰 개선은 입력 정보를 더 잘 주는 것입니다. 다음을 포함하세요:

• 프레임워크 또는 템플릿 (next, vite, astro 등)
• components.json 존재 여부
• 이미 알고 있다면 base 또는 radix
• 현재 사용하는 아이콘 세트
• 대상 컴포넌트 또는 화면
• 작업이 설치, 리팩터링, 버그 수정 중 무엇을 포함하는지

구체적인 맥락 한두 문장만 있어도 어시스턴트가 잘못된 API를 고르는 일을 크게 줄일 수 있습니다.

컴포넌트가 없을 수 있다면 코드보다 명령을 먼저 요청하세요

프로젝트에 필요한 컴포넌트가 아직 설치되지 않았을 수 있다면, 이런 식으로 프롬프트를 주세요:

Before writing code, check whether the required shadcn components are already present. If not, give me the exact add command and wait.

이 접근이 좋은 이유는 환경 변경과 구현을 분리해주기 때문입니다. 그래서 결과를 더 신뢰하기 쉽고 바로 적용하기도 수월합니다.

깨지기 쉬운 컴포넌트 유형에는 규칙 준수를 강제하세요

폼, 다이얼로그, 드롭다운, 시트, 드로어, 셀렉트 같은 컴포넌트는 어시스턴트에게 규칙 파일을 따르라고 명시하는 것이 좋습니다. 예를 들면:

Follow the shadcn rules for composition, forms, and base-vs-radix differences. Do not simplify structure if it changes the component API.

이게 중요한 이유는 품질이 낮은 결과물 상당수가 겉보기엔 멀쩡해도 접근성이나 조합 계약을 깨뜨리기 때문입니다.

디자인 제약을 구체적으로 적어 shadcn 활용도를 높이세요

좋은 UI 프롬프트는 단순히 “modern하게 만들어줘”가 아닙니다. 다음 같은 제약을 함께 적으세요:

• semantic token만 사용
• raw palette 유틸리티 금지
• 수동 오버라이드 없이 dark mode가 동작해야 함
• 커스텀 클래스보다 기존 variant 우선
• 라이브러리의 empty state, alert, separator, badge, skeleton 우선 사용

이런 디테일은 UI Design용 shadcn 작업에서 첫 결과물의 품질을 실제로 크게 끌어올립니다.

전체 재작성보다, 정확한 수정 지시로 반복하세요

첫 번째 결과를 받은 뒤에는 “다시 해봐”라고만 하지 마세요. 대신 이렇게 말하는 편이 낫습니다:

• “Refactor this to use installed shadcn components only.”
• “Make this valid for base, not radix.”
• “Replace raw color classes with semantic tokens.”
• “Add the missing title/fallback/group wrappers required by shadcn.”
• “Show the exact shadcn add commands for anything assumed.”

이렇게 하면 잘된 부분은 살리고, 틀리기 쉬운 부분만 정확히 고칠 수 있습니다.

저장소에서 가장 강한 신호와 대조해 검증하세요

신뢰도를 높이려면 결과를 다음과 비교해 보세요:

• 명령과 플래그는 cli.md
• 구조는 rules/composition.md
• API 정확성은 rules/base-vs-radix.md
• validation과 레이아웃 패턴은 rules/forms.md
• 테마 안전한 스타일링은 rules/styling.md와 customization.md
• 실전에서의 “좋은 결과” 기준은 evals/evals.json

이 방법이야말로 shadcn skill이 일반적인 UI 코드가 아니라 저장소 기준에 맞는 결과를 내고 있는지 가장 빠르게 판단하는 방법입니다.