shadcn-ui-%26-blocks by masonjames/shadcnblocks-skill
npx skills add https://github.com/masonjames/shadcnblocks-skill --skill 'Shadcn UI & Blocks'此技能支持使用 shadcn/ui 组件和高级 ShadcnBlocks 模板构建精美的前端界面。其主要能力是智能推荐最适合的区块或组件以满足任何 UI 需求——不仅仅是正确的类别,还包括该类别中正确的变体——然后处理设置和安装。
在以下情况下激活此技能:
| 区块 | 组件
---|---|---
是什么 | 完整的页面区块 | 可复用的 UI 元素
大小 | 英雄区、定价区、页脚等 | 按钮、输入框、对话框等
数量 | 71 个类别共 1,338 个 | 60+ 个组别共 1,189 个
访问权限 | 高级版(需要 API 密钥) | 免费
安装命令 | @shadcnblocks/<名称><编号> | @shadcnblocks/<类型>-<样式>-<编号>
使用区块来通过预构建的区块组合完整的页面布局。使用组件用于自定义代码中的独立 UI 元素。
推荐区块时,遵循此渐进式披露流程:
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
cta_pattern: form_capture)绝不要问超过 2 个问题。 如果仍然模糊,选择最好的 2-3 个选项并解释其权衡。
步骤 1 — 从请求中推断(始终首先执行此操作)
在询问任何问题之前,尽可能提取约束条件:
步骤 2 — 提出有针对性的问题(仅在需要时)
使用 AskUserQuestion 进行结构化的多项选择细化。请查阅 references/block-index.md → selection_prompts 以获取每个区块预定义的问题和选项。
具有预定义提示的区块类型: hero, feature, pricing, testimonial, cta, faq, navbar, footer, contact, stats。
功能区块请求示例:
AskUserQuestion:
question: "您希望如何展示您的功能?"
options:
- "卡片网格(3-4 列带图标)" — 经典的带图标和描述的卡片功能网格
- "交替的图片 + 文本行" — 带有大型视觉效果的深度展示,非常适合产品导览
- "Bento / 非对称网格" — 混合大小卡片的现代编辑布局
- "简单的图标列表或清单" — 紧凑、可快速浏览的优势列表
如果 AskUserQuestion 不可用,请使用带编号的选项内联询问相同的问题。
步骤 3 — 匹配标签并返回 2-3 个最佳选择
将用户的答案映射到标签过滤器,然后与 references/block-index.md 中的条目进行匹配。按照以下格式返回恰好 2-3 个推荐:
以下是您 [区块类型] 的最佳匹配:
1. **[区块-id]** — [1 行“为什么选择这个”]
布局: [布局] · 风格: [风格] · [关键区别点]
2. **[区块-id]** — [1 行“为什么选择这个”]
布局: [布局] · 风格: [风格] · [关键区别点]
3. **[区块-id]** — [1 行“为什么选择这个”]
布局: [布局] · 风格: [风格] · [关键区别点]
哪一个最适合?我将安装并设置它。
用户选择后,提供安装命令并将其组合到页面中。
这些是 references/block-index.md 中用于区分区块的关键维度:
| 维度 | 它告诉你什么 | 示例值 |
|---|---|---|
layout | 视觉排列 | centered, split_right_media, grid_cards, bento, alternating |
tone | 美学感受 | minimal, modern, bold, enterprise, elegant, playful |
goal | 商业目的 | awareness, explain, trust, convert, capture_leads, compare |
cta_pattern | 行动类型 | single_primary, primary_secondary, form_capture, multi_action |
media | 视觉内容 | screenshot, illustration, video, icons, avatars, logos |
interaction | 动态行为 | static, accordion, tabs, carousel, toggle, hover |
items_count | 显示的项目数量 | few, moderate, many |
content_density | 内容量 | minimal, standard, rich |
complexity | 实现工作量 | low, medium, high |
| 场景 | 使用 |
|---|---|
| 推荐最佳匹配区块(默认) | references/block-index.md — 带有选择提示的带标签选项 |
| 用户想要特定的编号变体 | references/block-catalog.md — 包含所有变体编号的完整目录 |
| 区块类型不在 block-index 中(例如,blog, gallery) | references/block-catalog.md — 回退到类别默认值 |
| 用户想要浏览所有选项 | 直接指向 https://shadcnblocks.com/explorer/blocks |
| 需要单个 UI 元素 | references/component-catalog.md — 免费组件 |
对于尚未在 block-index.md 中的区块类型,请使用以下默认值:
| 需求 | 类别 | 从...开始 |
|---|---|---|
| 博客列表 | blog (22 个变体) | blog1 |
| 博客文章页面 | blogpost (7 个变体) | blogpost1 |
| 更新日志 | changelog (7 个变体) | changelog1 |
| 代码片段 | code-example (5 个变体) | code-example1 |
| 需求 | 类别 | 从...开始 |
|---|---|---|
| 关于区块 | about (17 个变体) | about1 |
| 团队页面 | team (14 个变体) | team1 |
| 公司时间线 | timeline (15 个变体) | timeline1 |
| 职位列表 | careers (9 个变体) | careers1 |
| 需求 | 类别 | 从...开始 |
|---|---|---|
| 产品卡片 | product-card (10 个变体) | product-card1 |
| 产品列表 | product-list (10 个变体) | product-list1 |
| 产品详情 | product-detail (10 个变体) | product-detail1 |
| 购物车 | shopping-cart (11 个变体) | shopping-cart1 |
| 结账 | checkout (6 个变体) | checkout1 |
| 订单历史 | order-history (5 个变体) | order-history1 |
| 需求 | 类别 | 从...开始 |
|---|---|---|
| 仪表板图表 | chart-card (27 个变体) | chart-card10 |
| 数据表格 | data-table (32 个变体) | data-table1 |
| 应用侧边栏 | sidebar (21 个变体) | sidebar1 |
| 应用外壳布局 | application-shell (14 个变体) | application-shell1 |
| 用户资料 | user-profile (12 个变体) | user-profile1 |
| 需求 | 类别 | 从...开始 |
|---|---|---|
| 图片库 | gallery (48 个变体) | gallery1 |
| 项目列表 | projects (25 个变体) | projects1 |
| 项目详情 | project (33 个变体) | project1 |
| 案例研究 | case-studies (6 个变体) | case-studies1 |
| 需求 | 类别 | 从...开始 |
|---|---|---|
| 背景图案 | background-pattern (40 个变体) | background-pattern1 |
| 动画着色器 | shader (10 个变体) | shader1 |
| Bento 网格布局 | bento (8 个变体) | bento1 |
| 需求 | 类别 | 从...开始 |
|---|---|---|
| 公告栏 | banner (7 个变体) | banner1 |
| 促销栏 | promo-banner (7 个变体) | promo-banner1 |
| 合作伙伴徽标 | logos (13 个变体) | logos1 |
| 对比 | compare (10 个变体) | compare1 |
请查阅 references/component-catalog.md 获取完整目录。关键组别:
| 需求 | 组件组 | 示例 |
|---|---|---|
| 表单布局 | Form (86) | form-signin-1 |
| 带标签的输入框 | Field (38) | field-standard-1 |
| 带附加内容的输入框 | Input Group (39) | input-group-standard-1 |
| 可搜索选择器 | Combobox (42) | combobox-standard-1 |
| 文件上传 | File Upload (44) | file-upload-standard-1 |
| 日期选择器 | Date Picker (8) | date-picker-standard-1 |
| 警告消息 | Alert (25) | alert-error-1 |
| 确认对话框 | Alert Dialog (39) | alert-dialog-standard-1 |
| 加载骨架屏 | Skeleton (30) | skeleton-standard-1 |
| Toast 通知 | Sonner (24) | sonner-standard-1 |
| 空状态 | Empty (22) | empty-standard-1 |
| 模态对话框 | Dialog (17) | dialog-standard-1 |
| 侧边面板 | Sheet (29) / Drawer (22) | sheet-standard-1 |
| 手风琴 | Accordion (21) | accordion-standard-1 |
| 数据图表 | Chart (70) | chart-standard-1 |
| 命令面板 | Command (21) | command-standard-1 |
| 下拉菜单 | Dropdown Menu (30) | dropdown-menu-standard-1 |
| 键盘快捷键 | KBD (39) | kbd-standard-1 |
验证项目是否已初始化 shadcn/ui。如果没有:
npx shadcn@latest init
这将在项目根目录创建 components.json。
检查 components.json 是否已包含 @shadcnblocks 注册表。如果没有,运行:
bash "${CLAUDE_PLUGIN_ROOT}/skills/shadcn-ui/scripts/setup-shadcnblocks.sh" .
这将向 components.json 添加 @shadcnblocks 注册表,并在 .env 中设置 SHADCNBLOCKS_API_KEY。
如果脚本无法运行(例如,缺少 jq),请手动配置:
添加到 .env:SHADCNBLOCKS_API_KEY=<密钥>
向 components.json 添加注册表:
{
"registries": {
"@shadcnblocks": {
"url": "https://shadcnblocks.com/r/{name}",
"headers": {
"Authorization": "Bearer ${SHADCNBLOCKS_API_KEY}"
}
}
}
}
使用智能选择流程(上文)推荐最佳区块,然后安装:
# 区块(完整页面区块)
npx shadcn add @shadcnblocks/hero125
npx shadcn add @shadcnblocks/pricing3
# 组件(UI 元素)
npx shadcn add @shadcnblocks/accordion-standard-1
npx shadcn add @shadcnblocks/file-upload-standard-1
在页面布局中导入并组合区块:
import { Navbar1 } from "@/components/navbar1";
import { Hero125 } from "@/components/hero125";
import { Feature3 } from "@/components/feature3";
import { Footer1 } from "@/components/footer1";
export default function LandingPage() {
return (
<>
<Navbar1 />
<Hero125 />
<Feature3 />
<Footer1 />
</>
);
}
区块是完全可编辑的源代码,不是锁定的依赖项。安装后可以自定义属性和内容。
对于典型的营销落地页,对每个区块使用智能选择流程。常见的组装方式:
npx shadcn add @shadcnblocks/navbar1 # 带有 CTA 的简单导航
npx shadcn add @shadcnblocks/hero125 # 现代居中英雄区
npx shadcn add @shadcnblocks/logos1 # 信任徽标条
npx shadcn add @shadcnblocks/feature3 # 3 列功能卡片
npx shadcn add @shadcnblocks/stats1 # 指标栏
npx shadcn add @shadcnblocks/testimonial1 # 社交证明网格
npx shadcn add @shadcnblocks/pricing3 # 3 层定价卡片
npx shadcn add @shadcnblocks/faq1 # 手风琴 FAQ
npx shadcn add @shadcnblocks/cta1 # 最终行动号召
npx shadcn add @shadcnblocks/footer1 # 多列页脚
这些区块中的每一个都是为“现代 SaaS”风格而选择的。对于不同的风格(企业、简约、大胆、活泼),选择流程将推荐不同的变体。
ShadcnBlocks API 密钥可以通过多种方式提供(按顺序检查):
.env 文件中设置 SHADCNBLOCKS_API_KEYop read 来检索密钥。将 OP_SHADCNBLOCKS_REF 设置为您的 1Password 引用路径,否则默认为 op://Platform Infra/ShadcnBlocks API Key/credential使用辅助脚本检索密钥:
bash "${CLAUDE_PLUGIN_ROOT}/skills/shadcn-ui/scripts/get-api-key.sh"
安全性: 切勿在源文件中硬编码 API 密钥。始终使用带有 SHADCNBLOCKS_API_KEY 的 .env 文件,并确保 .env 在 .gitignore 中。
| 问题 | 解决方案 |
|---|---|
| 安装时认证错误 | 验证 .env 中设置的 SHADCNBLOCKS_API_KEY 是有效的密钥 |
| 注册表未找到 | 检查 components.json 中是否存在 registries 键 |
components.json 缺失 | 运行 npx shadcn@latest init |
| 1Password 访问 | 运行 op signin;使用 op vault list 验证保险库 |
| 区块未找到 | 在 https://shadcnblocks.com 检查区块名称 |
references/block-index.md — 带有选择提示的带标签选项,用于智能区块推荐(主要来源)references/block-catalog.md — 71 个类别共 1,338 个区块的完整目录,包含变体编号和安装命令references/component-catalog.md — 60+ 个组别共 1,189 个组件的完整目录,包含安装语法references/setup-guide.md — 详细的逐步设置指南,包含故障排除scripts/setup-shadcnblocks.sh — 自动化项目设置(检索密钥,配置注册表)scripts/get-api-key.sh — 检索 API 密钥(环境变量或 1Password)每周安装次数
–
代码仓库
GitHub 星标数
11
首次出现
–
This skill enables building polished frontends using shadcn/ui components and premium ShadcnBlocks templates. Its primary capability is intelligently recommending the best block or component for any UI need — not just the right category, but the right variant within that category — then handling setup and installation.
Activate this skill when:
| Blocks | Components
---|---|---
What | Full page sections | Reusable UI elements
Size | Hero, pricing, footer, etc. | Buttons, inputs, dialogs, etc.
Count | 1,338 across 71 categories | 1,189 across 60+ groups
Access | Premium (API key required) | Free
Install | @shadcnblocks/<name><number> | @shadcnblocks/<type>-<style>-<number>
Use blocks to compose full page layouts from pre-built sections. Use components for individual UI elements inside custom code.
When recommending blocks, follow this progressive disclosure flow:
cta_pattern: form_capture)Never ask more than 2 questions. If still ambiguous, pick the best 2-3 and explain the tradeoffs.
Step 1 — Infer from the request (always do this first)
Extract as many constraints as possible before asking anything:
Step 2 — Ask targeted questions (only if needed)
Use AskUserQuestion for structured multiple-choice refinement. Consult references/block-index.md → selection_prompts for the pre-defined questions and options per section.
Sections with pre-defined prompts: hero, feature, pricing, testimonial, cta, faq, navbar, footer, contact, stats.
Example for a feature section request:
AskUserQuestion:
question: "How do you want to showcase your features?"
options:
- "Card grid (3-4 columns with icons)" — Classic feature grid with icon + description per card
- "Alternating image + text rows" — Deep-dive with large visuals, great for product tours
- "Bento / asymmetric grid" — Modern editorial layout with mixed-size cards
- "Simple icon list or checklist" — Compact, scannable benefit list
If AskUserQuestion is unavailable, ask the same question inline with numbered options.
Step 3 — Match tags and return 2-3 best picks
Map the user's answer to tag filters, then match against references/block-index.md entries. Return exactly 2-3 recommendations in this format:
Here are the best matches for your [section type]:
1. **[block-id]** — [1-line "why this one"]
Layout: [layout] · Tone: [tone] · [key differentiator]
2. **[block-id]** — [1-line "why this one"]
Layout: [layout] · Tone: [tone] · [key differentiator]
3. **[block-id]** — [1-line "why this one"]
Layout: [layout] · Tone: [tone] · [key differentiator]
Which one works best? I'll install it and set it up.
After the user picks, provide the install command and compose it into the page.
These are the key dimensions from references/block-index.md used to differentiate blocks:
| Dimension | What it tells you | Example values |
|---|---|---|
layout | Visual arrangement | centered, split_right_media, grid_cards, bento, alternating |
tone | Aesthetic feel | minimal, modern, bold, enterprise, elegant, playful |
goal | Business purpose | awareness, explain, trust, convert, capture_leads, compare |
cta_pattern | Action type | single_primary, primary_secondary, form_capture, multi_action |
media |
| Scenario | Use |
|---|---|
| Recommending best-fit blocks (default) | references/block-index.md — tagged picks with selection prompts |
| User wants a specific numbered variant | references/block-catalog.md — full catalog with all variant numbers |
| Section not in block-index (e.g., blog, gallery) | references/block-catalog.md — fall back to category defaults |
| User wants to browse all options | Direct to https://shadcnblocks.com/explorer/blocks |
| Need an individual UI element | references/component-catalog.md — free components |
For sections not yet in block-index.md , use these defaults:
| Need | Category | Start With |
|---|---|---|
| Blog listing | blog (22 variants) | blog1 |
| Blog post page | blogpost (7 variants) | blogpost1 |
| Changelog | changelog (7 variants) | changelog1 |
| Code snippets | code-example (5 variants) |
| Need | Category | Start With |
|---|---|---|
| About section | about (17 variants) | about1 |
| Team page | team (14 variants) | team1 |
| Company timeline | timeline (15 variants) | timeline1 |
| Job listings | careers (9 variants) |
| Need | Category | Start With |
|---|---|---|
| Product cards | product-card (10 variants) | product-card1 |
| Product listing | product-list (10 variants) | product-list1 |
| Product detail | product-detail (10 variants) | product-detail1 |
| Shopping cart | (11 variants) |
| Need | Category | Start With |
|---|---|---|
| Dashboard charts | chart-card (27 variants) | chart-card10 |
| Data tables | data-table (32 variants) | data-table1 |
| App sidebar | sidebar (21 variants) | sidebar1 |
| App shell layout | application-shell (14 variants) |
| Need | Category | Start With |
|---|---|---|
| Image gallery | gallery (48 variants) | gallery1 |
| Project listing | projects (25 variants) | projects1 |
| Project detail | project (33 variants) | project1 |
| Case studies | case-studies (6 variants) |
| Need | Category | Start With |
|---|---|---|
| Background patterns | background-pattern (40 variants) | background-pattern1 |
| Animated shaders | shader (10 variants) | shader1 |
| Bento grid layout | bento (8 variants) | bento1 |
| Need | Category | Start With |
|---|---|---|
| Announcement bar | banner (7 variants) | banner1 |
| Sale/promo bar | promo-banner (7 variants) | promo-banner1 |
| Partner logos | logos (13 variants) | logos1 |
| Comparisons | compare (10 variants) |
Consult references/component-catalog.md for the full catalog. Key groups:
| Need | Component Group | Example |
|---|---|---|
| Form layout | Form (86) | form-signin-1 |
| Labeled input | Field (38) | field-standard-1 |
| Input with addon | Input Group (39) | input-group-standard-1 |
| Searchable select | Combobox (42) | combobox-standard-1 |
| File upload | File Upload (44) | file-upload-standard-1 |
Verify the project has shadcn/ui initialized. If not:
npx shadcn@latest init
This creates components.json in the project root.
Check if components.json already has the @shadcnblocks registry. If not, run:
bash "${CLAUDE_PLUGIN_ROOT}/skills/shadcn-ui/scripts/setup-shadcnblocks.sh" .
This adds the @shadcnblocks registry to components.json and sets SHADCNBLOCKS_API_KEY in .env.
If the script can't run (e.g., jq missing), configure manually:
.env: SHADCNBLOCKS_API_KEY=<key>components.json:{
"registries": {
"@shadcnblocks": {
"url": "https://shadcnblocks.com/r/{name}",
"headers": {
"Authorization": "Bearer ${SHADCNBLOCKS_API_KEY}"
}
}
}
}
Use the intelligent selection flow (above) to recommend the best blocks, then install:
# Blocks (full page sections)
npx shadcn add @shadcnblocks/hero125
npx shadcn add @shadcnblocks/pricing3
# Components (UI elements)
npx shadcn add @shadcnblocks/accordion-standard-1
npx shadcn add @shadcnblocks/file-upload-standard-1
Import and compose blocks in the page layout:
import { Navbar1 } from "@/components/navbar1";
import { Hero125 } from "@/components/hero125";
import { Feature3 } from "@/components/feature3";
import { Footer1 } from "@/components/footer1";
export default function LandingPage() {
return (
<>
<Navbar1 />
<Hero125 />
<Feature3 />
<Footer1 />
</>
);
}
Blocks are fully editable source code, not locked dependencies. Customize props and content after installation.
For a typical marketing landing page, use the intelligent selection flow for each section. A common assembly:
npx shadcn add @shadcnblocks/navbar1 # Simple nav with CTA
npx shadcn add @shadcnblocks/hero125 # Modern centered hero
npx shadcn add @shadcnblocks/logos1 # Trust logos strip
npx shadcn add @shadcnblocks/feature3 # 3-column feature cards
npx shadcn add @shadcnblocks/stats1 # Metrics bar
npx shadcn add @shadcnblocks/testimonial1 # Social proof grid
npx shadcn add @shadcnblocks/pricing3 # 3-tier pricing cards
npx shadcn add @shadcnblocks/faq1 # Accordion FAQ
npx shadcn add @shadcnblocks/cta1 # Final call to action
npx shadcn add @shadcnblocks/footer1 # Multi-column footer
Each of these was selected for a "modern SaaS" tone. For different tones (enterprise, minimal, bold, playful), the selection flow will recommend different variants.
The ShadcnBlocks API key can be provided in multiple ways (checked in order):
SHADCNBLOCKS_API_KEY in your shell or .env fileop read to retrieve the key. Set OP_SHADCNBLOCKS_REF to your 1Password reference path, or it defaults to op://Platform Infra/ShadcnBlocks API Key/credentialRetrieve the key using the helper script:
bash "${CLAUDE_PLUGIN_ROOT}/skills/shadcn-ui/scripts/get-api-key.sh"
Security: Never hardcode the API key in source files. Always use .env with SHADCNBLOCKS_API_KEY and ensure .env is in .gitignore.
| Issue | Resolution |
|---|---|
| Auth error on install | Verify SHADCNBLOCKS_API_KEY is set in .env with a valid key |
| Registry not found | Check registries key exists in components.json |
components.json missing | Run npx shadcn@latest init |
| 1Password access | Run op signin; verify vault with |
references/block-index.md — Tagged picks with selection prompts for intelligent block recommendation (primary source)references/block-catalog.md — Full catalog of 1,338 blocks across 71 categories with variant numbers and install commandsreferences/component-catalog.md — Full catalog of 1,189 components across 60+ groups with install syntaxreferences/setup-guide.md — Detailed step-by-step setup with troubleshootingscripts/setup-shadcnblocks.sh — Automated project setup (retrieves key, configures registry)scripts/get-api-key.sh — Retrieve API key (env var or 1Password)Weekly Installs
–
Repository
GitHub Stars
11
First Seen
–
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
107,800 周安装
| Visual content |
| screenshot, illustration, video, icons, avatars, logos |
interaction | Dynamic behavior | static, accordion, tabs, carousel, toggle, hover |
items_count | Number of items displayed | few, moderate, many |
content_density | How much content | minimal, standard, rich |
complexity | Implementation effort | low, medium, high |
code-example1 |
careers1 |
shopping-cartshopping-cart1 |
| Checkout | checkout (6 variants) | checkout1 |
| Order history | order-history (5 variants) | order-history1 |
application-shell1 |
| User profile | user-profile (12 variants) | user-profile1 |
case-studies1 |
compare1 |
| Date picker | Date Picker (8) | date-picker-standard-1 |
| Alert message | Alert (25) | alert-error-1 |
| Confirm dialog | Alert Dialog (39) | alert-dialog-standard-1 |
| Loading skeleton | Skeleton (30) | skeleton-standard-1 |
| Toast notification | Sonner (24) | sonner-standard-1 |
| Empty state | Empty (22) | empty-standard-1 |
| Modal dialog | Dialog (17) | dialog-standard-1 |
| Side panel | Sheet (29) / Drawer (22) | sheet-standard-1 |
| Accordion | Accordion (21) | accordion-standard-1 |
| Data chart | Chart (70) | chart-standard-1 |
| Command palette | Command (21) | command-standard-1 |
| Dropdown menu | Dropdown Menu (30) | dropdown-menu-standard-1 |
| Keyboard shortcuts | KBD (39) | kbd-standard-1 |
op vault list| Block not found | Check block name at https://shadcnblocks.com |