designer-skill-mcp

即插即用的 MCP。为你的 Agent 增添 UI 超能力。

设置 · 工作原理 · 参考资料 · 工具 · 开发

设置

粘贴到你的 Agent 中（Claude Code、Codex、Cursor，或任何 MCP 客户端）。它会安装技能、连接 MCP 并验证工具：

Add designer-skill alongside Niblet Designer UI. The designer core is keyless: it routes requests, loads guidance and runs supplemental static checks. Niblet optionally supplies real screens and licensed materials; the host owns implementation and rendered verification.

1. Install or refresh the skill into the user skill directory (not this project):
npx skills add PyModel/designer-skill --skill designer-skill -g -y

2. Add the local MCP using this client's native MCP configuration, in the user-level (not project-level) config:
Name: designer-skill
Transport: stdio
Command: npx
Args: -y @pymodel/designer-skill-mcp@latest

No API key is needed. Do not add one.

3. Verify: list the designer-skill server's tools and confirm get_preflight_brief, dispatch_intent, review_and_gate are present. Do not run a sample check.

When setup is complete, confirm the skill is installed and the three named tools are exposed. On UI work: call get_preflight_brief, use dispatch_intent and load only relevant guidance. If an unresolved visual question warrants retrieval, use the separately configured niblet server's discovered tools. Prefer its image content for inspection; designer-skill's catalogue wrappers return metadata or routing guidance only. Run review_and_gate as supplemental static evidence, then perform the required rendered, functional and accessibility checks in the host. Never treat static success as UI PASS. Preserve audit/plan scope. Continue an active authorized task; otherwise report designer-skill ready, and report Niblet paired only if its tools were actually observed.

没有 Niblet？请根据本地产品证据继续操作；目录检索是可选的。

也可以选择以下方式：

标准 MCP 配置（mcp.json）：

{ "mcpServers": { "designer-skill": { "command": "npx", "args": ["-y", "@pymodel/designer-skill-mcp@latest"] } } }

@latest 会跟踪 npm 最新版本；团队可固定使用 @pymodel/[email protected]。插件技能内容会单独更新（/plugin update …）。MCP 注册表名称：io.github.PyModel/designer-skill-mcp。需要 Node 22+。

{ "servers": { "designer-skill": { "type": "stdio", "command": "npx", "args": ["-y", "@pymodel/designer-skill-mcp"] } } }

[mcp_servers.designer-skill]
command = "npx"
args = ["-y", "@pymodel/designer-skill-mcp"]

{ "mcp": { "designer-skill": { "type": "local", "command": ["npx", "-y", "@pymodel/designer-skill-mcp"] } } }

flowchart LR
  A[Prompt] --> B[get_preflight_brief]
  B --> C[dispatch_intent]
  C --> D[get_reference]
  D --> E[Build / polish UI]
  E --> F[review_and_gate]
  F -->|FAIL: fix| E
  F -->|static checks pass| G[Rendered checks<br/>by the host]
  classDef start fill:#f8fafc,stroke:#94a3b8,color:#18181b
  classDef route fill:#eff6ff,stroke:#3b82f6,color:#1e3a8a
  classDef know fill:#faf5ff,stroke:#7c3aed,color:#4c1d95
  classDef work fill:#fff7ed,stroke:#e87a3d,color:#7c2d12
  classDef gate fill:#ecfdf5,stroke:#10b981,color:#065f46
  classDef host fill:#fff1f2,stroke:#e11d48,color:#881337
  class A start
  class B,C route
  class D know
  class E work
  class F gate
  class G host

此门禁仅进行静态检查：总体状态为 FAIL 或 NOT_VERIFIED，绝不会通过渲染就绪检查。渲染、无障碍和性能检查会保持 NOT_RUN，直到宿主提供证据。

Niblet 生态系统

请按服务发现工具：designer-skill 上同名的 find_ui_references 是纯文本 REST 封装，并非 Niblet 提供图像的工具。参考资料检查和素材获取优先使用 Niblet MCP。对于同一问题，不要同时调用两个提供方，也不要根据安装情况推断连接状态。有关部署差异、限制和许可，请参阅 niblet-catalogue。

使用以产品为依据的统一设计契约。Niblet 的界面模式（说服、操作、阅读、体验）描述用户的任务；designer-skill 的执行模式（审计、规划、优化、实现、系统）描述允许执行的工作。两者相互独立：操作型界面可以进行只读审计，也可以进行获准的优化。现有产品令牌、组件和真实内容优先于参考风格。检索组件并不授权安装依赖项或写入源码，而且这两个 MCP 都不认证渲染质量。

示例： “使用 designer-skill 重新设计此定价页面，同时确保功能不受影响。” → get_preflight_brief → dispatch_intent → get_reference → 编辑 → review_and_gate。

此外还有 26 个 ux/* 参考资料，源文件位于 skills/ux-designer/，并 vendored 到 skills/designer-skill/reference/ux/（由 node scripts/sync-ux.mjs 生成，并通过测试检查），因此仅安装 designer-skill 也包含全部所需内容。每个 SKILL.md 都是一个简短路由文件，附有一行说明；只有任务需要时才会加载参考资料。

工具

资源： designer://skill · designer://reference/{+name} · 提示词： design（task，可选 aesthetic）

开发

cd designer-skill-mcp
npm ci
npm run build   # syncs skills/ → assets/ (generated, gitignored), compiles TypeScript
npm run typecheck && npm test   # tsc over src + test, then vitest; `npm run smoke` drives the packed tarball

技能稳健性检查

仅在 skills/ux-designer/references/ 中编辑 UX 指南；打包前，npm run sync-skill 会重新生成独立镜像。在仓库根目录运行 node scripts/sync-ux.mjs，以仅通过文件系统进行分发。

运行报告现在使用 v2，并附带由宿主负责的验证计划。验证两个捆绑的 JSON 架构，然后运行无依赖脚本 skills/designer-skill/scripts/validate-report.mjs REPORT PLAN AUTHORIZED_ROOT，检查证据哈希、路径限制、修订版/计划匹配情况以及渲染就绪语义。脚本自身显示 PASS 表示报告验证通过，并不代表 UI 已获认证。旧版 v1 报告会被安全拒绝，必须根据真实证据重新生成；请同时更新宿主端的读取器和写入器。

行为动作计划案例和确定性评分器位于 evals/designer-skill/。合成评分器测试不算模型评估，模型提案也无法证明实际工具使用合规性或渲染质量。评估结果中请保留模型、宿主、技能哈希和重复次数。

HTTP 模式（/mcp 上的 Streamable HTTP）：

node dist/index.js --http --port 3017 --root /abs/project                     # 127.0.0.1
DESIGNER_SKILL_HTTP_TOKEN=… node dist/index.js --http --host 0.0.0.0 --root /abs/project

每个 HTTP 绑定都至少需要一个 --root。环回绑定会验证 Host 标头；非环回绑定还需要 DESIGNER_SKILL_HTTP_TOKEN（Authorization: Bearer …）。

发布： ./scripts/release.sh "notes" 会递增并同步所有版本、执行验证、创建标签并推送；publish.yml 会发布 npm（附带来源证明）、MCP 注册表条目和 GitHub 发布版本。约定详情：docs/HARDENING.md。