https://github.com/pythoughts-labs/designer-skill

Plug-and-play MCP that gives your coding agent UI superpowers. One-line install, zero config. Claude Code, Codex, Cursor, VS Code, and more.
https://github.com/pythoughts-labs/designer-skill

ai-agent claude claude-code codex coding-agent cursor design-system designer-skill frontend-design mcp model-context-protocol npm plug-and-play typescript ui ui-design ux

Last synced: 1 day ago
JSON representation

Plug-and-play MCP that gives your coding agent UI superpowers. One-line install, zero config. Claude Code, Codex, Cursor, VS Code, and more.

Host: GitHub
URL: https://github.com/pythoughts-labs/designer-skill
Owner: Pythoughts-labs
License: mit
Created: 2026-06-09T18:25:54.000Z (about 1 month ago)
Default Branch: main
Last Pushed: 2026-07-13T19:42:40.000Z (11 days ago)
Last Synced: 2026-07-13T21:24:19.961Z (10 days ago)
Topics: ai-agent, claude, claude-code, codex, coding-agent, cursor, design-system, designer-skill, frontend-design, mcp, model-context-protocol, npm, plug-and-play, typescript, ui, ui-design, ux
Language: JavaScript
Homepage: https://pythinker.com
Size: 876 KB
Stars: 22
Watchers: 0
Forks: 2
Open Issues: 6
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md

Awesome Lists containing this project

README

          







**Plug-and-play MCP. UI superpowers for your agent.**




[![plug_and_play](https://img.shields.io/badge/plug_&_play-zero_config-10b981?style=for-the-badge)](#setup)

[![npm](https://img.shields.io/npm/v/designer-skill-mcp?style=for-the-badge&logo=npm&logoColor=white&color=0ea5e9)](https://www.npmjs.com/package/designer-skill-mcp)

[![downloads](https://img.shields.io/npm/dt/designer-skill-mcp?style=for-the-badge&logo=npm&logoColor=white&color=c9a84c&label=DOWNLOADS)](https://www.npmjs.com/package/designer-skill-mcp)

[![license](https://img.shields.io/badge/license-MIT-10b981?style=for-the-badge)](LICENSE)




[![agents](https://img.shields.io/badge/agents-8-7c3aed?style=for-the-badge)](#setup)

[![references](https://img.shields.io/badge/references-15-e11d48?style=for-the-badge)](#reference)

[![tools](https://img.shields.io/badge/MCP_tools-10-0ea5e9?style=for-the-badge)](#tools)

[![detector](https://img.shields.io/badge/detector-44_rules-f59e0b?style=for-the-badge)](#tools)




[Overview](#overview) · [Setup](#setup) · [Reference](#reference) · [Tools](#tools) · [Development](#development)

```bash

npm i designer-skill-mcp

```






### Route

`dispatch_intent` maps vague requests like "make it pop" or "it feels off" to the right design verb and reference files.

### Know

15 reference files cover type, color, motion, a11y, anti-slop, and redesign loops. Your agent reads the right file before writing UI code.

### Check

A 44-rule deterministic detector plus `anti_slop_checklist` runs before shipping. Generic UI gets caught before it lands.






[![overview](https://img.shields.io/badge/Overview-18181b?style=for-the-badge)](#overview)



**designer-skill-mcp** is a small [MCP](https://modelcontextprotocol.io) server you add in one line. Your agent gets design tools, reference docs, and a ship gate so UI work stops looking generic.

```mermaid

flowchart LR

  A[Your prompt] --> B[dispatch_intent]

  B --> C[get_reference]

  C --> D[Build / polish UI]

  D --> E[anti_slop_checklist]

  E --> F[Ship]

  style A fill:#f8fafc,stroke:#94a3b8,color:#18181b

  style B fill:#eff6ff,stroke:#3b82f6,color:#1e3a8a

  style C fill:#faf5ff,stroke:#7c3aed,color:#4c1d95

  style D fill:#fff7ed,stroke:#e87a3d,color:#7c2d12

  style E fill:#ecfdf5,stroke:#10b981,color:#065f46

  style F fill:#f1f5f9,stroke:#64748b,color:#0f172a

```

Add the server. Ask in plain language. The agent handles the rest.



[![skill](https://img.shields.io/badge/design_skill-15_refs-7c3aed?style=flat-square)](skills/designer-skill/)

[![mcp](https://img.shields.io/badge/MCP-10_tools-0ea5e9?style=flat-square)](designer-skill-mcp/)

**Built with it:** [pythinker.com](https://pythinker.com) — a live production site designed end-to-end with this skill.










[![setup](https://img.shields.io/badge/Setup-0ea5e9?style=for-the-badge)](#setup)



### Plugin (recommended)



[![claude](https://img.shields.io/badge/Claude_Code-plugin-7c3aed?style=flat-square)](#setup)

[![codex](https://img.shields.io/badge/Codex-plugin-10b981?style=flat-square)](#setup)

[![cursor](https://img.shields.io/badge/Cursor-plugin-18181b?style=flat-square)](#setup)



One install gets both the skill and the MCP server:

```

/plugin marketplace add Pythoughts-labs/designer-skill

/plugin install designer-skill@pythoughts-labs

```

Codex CLI:

```bash

codex plugin marketplace add Pythoughts-labs/designer-skill

```

Then install **designer-skill** from the **pythoughts-labs** marketplace in `/plugins`. The skill appears as `designer-skill:designer-skill`.

**Cursor:** install from the marketplace (or open this repo). Plugin ships `mcp.json`, skills, and `/designer-setup` · `/designer-status` commands.

### Plug in (any client)

Same one-liner everywhere. No API key. Repo-root `mcp.json` is the canonical MCP config (plugins reference it too):

```json

{

  "mcpServers": {

    "designer-skill": {

      "command": "npx",

      "args": ["-y", "designer-skill-mcp@latest"]

    }

  }

}

```

**Updates:** `@latest` for newest npm; pin @0.11.0 for teams. Plugin skill content updates separately (`/plugin update …`). Registry: `io.github.pythoughts-labs/designer-skill-mcp` (publish via `mcp-publisher` after npm release).



[![pythinker](https://img.shields.io/badge/Pythinker-0ea5e9?style=flat-square)](docs/blog/integrating-designer-skill-with-pythinker.md)

[![codex](https://img.shields.io/badge/Codex_CLI-10b981?style=flat-square)](https://github.com/openai/codex)

[![claude](https://img.shields.io/badge/Claude_Code-c15a3c?style=flat-square)](https://claude.ai/code)

[![cursor](https://img.shields.io/badge/Cursor-18181b?style=flat-square)](https://cursor.com)

[![vscode](https://img.shields.io/badge/VS_Code-007ACC?style=flat-square&logo=visualstudiocode&logoColor=white)](https://code.visualstudio.com)

[![kilo](https://img.shields.io/badge/Kilo_Code-7c3aed?style=flat-square)](https://kilocode.ai)

[![opencode](https://img.shields.io/badge/Open_Code-e11d48?style=flat-square)](https://opencode.ai)

[![pi](https://img.shields.io/badge/Pi-f59e0b?style=flat-square)](https://github.com/earendil-works/pi-coding-agent)



Client

Quick install

Pythinkerpythinker mcp add --transport stdio designer-skill -- npx -y designer-skill-mcp · guide

Codex CLIcodex mcp add designer-skill -- npx -y designer-skill-mcp

Claude Codeclaude mcp add designer-skill -- npx -y designer-skill-mcp

CursorCursor plugin or copy mcp.json → .cursor/mcp.json

VS Code.vscode/mcp.json ("servers" + "type": "stdio")

Kilo CodeMCP Settings → mcp_settings.json

Open Codeopencode.json (key "mcp")

PiMCP config or native skill path

Per-client config snippets

**Pythinker** (`~/.pythinker/mcp.json`)

```json

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

```

Verify: `pythinker mcp test designer-skill` · TUI: `/mcp` lists the server, `/tools` shows `mcp_designer-skill_*`.

**Codex CLI** (`~/.codex/config.toml`)

```toml

[mcp_servers.designer-skill]

command = "npx"

args = ["-y", "designer-skill-mcp"]

```

**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`)

```json

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

```

**Cursor** (`.cursor/mcp.json` — same shape as repo-root `mcp.json`)

**VS Code** (`.vscode/mcp.json`, requires 1.99+ or MCP extension)

```json

{

  "servers": {

    "designer-skill": {

      "type": "stdio",

      "command": "npx",

      "args": ["-y", "designer-skill-mcp"]

    }

  }

}

```

**Kilo Code** (MCP Settings → Edit MCP Settings)

```json

{

  "mcpServers": {

    "designer-skill": {

      "command": "npx",

      "args": ["-y", "designer-skill-mcp"],

      "disabled": false,

      "alwaysAllow": []

    }

  }

}

```

**Open Code** (`opencode.json` or `~/.config/opencode/config.json`)

```json

{

  "mcp": {

    "designer-skill": {

      "type": "local",

      "command": ["npx", "-y", "designer-skill-mcp"]

    }

  }

}

```

**Pi** (MCP config, same JSON as Pythinker, or register the skill natively):

```json

{ "skills": [{ "path": "/path/to/skills/designer-skill/SKILL.md" }] }

```

### Skill-only



[![skill_copy](https://img.shields.io/badge/skill--only-no_MCP-71717a?style=flat-square)](#setup)



```bash

cp -r skills/designer-skill/ ~/.claude/skills/designer-skill/   # Claude Code

cp -r skills/designer-skill/ ~/.codex/skills/designer-skill/     # Codex

```

Invoke with the Skill tool or `$designer-skill` on design tasks.

### Invoke






Use designer-skill to redesign this pricing page without breaking functionality.





get_design_system → dispatch_intent → get_reference → work → anti_slop_checklist












[![reference](https://img.shields.io/badge/Reference-e11d48?style=for-the-badge)](#reference)



### Files

File

Use when

Tier

design-principles.mdTypography, spacing, color, layout, hierarchy (neutral baseline)core

differentiation-playbook.mdHow to be distinctive: inverse test, layout menu, one weird thing, named referencescore

aesthetic-systems.mdPicking a look: 5 systems with palettes, fonts, shadowscore

motion-and-interaction.mdAnimation timing, springs, scroll, reduced-motioncore

engineering-and-performance.mdTokens, a11y, responsive, Core Web Vitals, real-data hardeningcore

avoid-ai-slop.mdBan-list, category-reflex checks, output-completeness contractcore

refactor-and-redesign.mdAudit → diagnose → redesign without breaking behaviorcore

command-playbook.mdIntent → verb dispatch (build, finish, amplify, ship, …)core

interaction-design.mdFitts/Hick/Miller, forms, navigation, errors, loading statesextended

visual-critique.mdSeven-dimension critique instrumentextended

design-systems.mdToken architecture, component specs, themingextended

project-init.mdDiscovery interview, PRODUCT.md, DESIGN.md setupextended

craft-flow.mdShape-then-build pipeline with user gatesextended

live-mode.mdBrowser variant mode: element select, HMR, poll/steer/acceptextended

css-techniques.mdModern CSS cookbook: resets, centering, selectors, logical props, container queries, :has(), clamp()extended



[![core](https://img.shields.io/badge/core-8-0ea5e9?style=flat-square)](#reference)

[![extended](https://img.shields.io/badge/extended-7-e11d48?style=flat-square)](#reference)



### Intent → verb

Phrase

Verb(s)

Read

"make it pop"amplify · coloraesthetic-systems, design-principles

"it feels off"check · layoutrefactor-and-redesign, avoid-ai-slop

"production-ready"ship · checkengineering-and-performance

"add some motion"motionmotion-and-interaction

"it looks AI-made"review · brandavoid-ai-slop, aesthetic-systems

"redesign this"check · refreshrefactor-and-redesign, command-playbook

### Preflight

1

Scope the surface: brand register (distinctiveness) vs product register (earned familiarity).

2

Commit to one aesthetic system; never mix two signatures on one surface.

3

Run the category-reflex check in avoid-ai-slop.md.

4

Build on design-principles.md + engineering-and-performance.md; add motion last.

5

For existing UI, audit → diagnose → redesign. Do not rebuild from scratch.

6

Run the ship gate (anti_slop_checklist) before declaring done.






[![tools](https://img.shields.io/badge/MCP_Tools-0ea5e9?style=for-the-badge)](#tools)



Tool

Purpose

get_design_systemSKILL.md router (call first)

load_project_contextRead PRODUCT.md / DESIGN.md from the project

get_referenceOne of fifteen reference files by name

list_commandsAll design verbs with descriptions

get_commandFull guidance + references for a specific verb

dispatch_intentMap a request → verb(s) + files to read

detect_antipatternsDeterministic scan (44 rules), no LLM, no API key

get_palette_seedOKLCH brand-seed for greenfield palette work

anti_slop_checklistShip gate: run before finishing any UI work



[![resources](https://img.shields.io/badge/resources-designer://skill-7c3aed?style=flat-square)](#tools)

[![prompt](https://img.shields.io/badge/prompt-design-10b981?style=flat-square)](#tools)



**Resources:** `designer://skill` · `designer://reference/{name}`

**Prompt:** `design` (args: `task` required, `aesthetic` optional)






[![development](https://img.shields.io/badge/Development-f59e0b?style=for-the-badge)](#development)



```bash

cd designer-skill-mcp

npm install

npm run build   # syncs skills/designer-skill/ → assets/skill/, compiles TypeScript

npm test

```

**HTTP mode** (remote clients):

```bash

node dist/index.js --http --port 3017             # 127.0.0.1 (default)

node dist/index.js --http --port 3017 --host 0.0.0.0  # public: add auth/proxy

```

Endpoint: `http://127.0.0.1:3017/mcp` (Streamable HTTP). Includes Origin guard against DNS-rebinding; no built-in auth for public exposure.

**Local checkout:** replace `npx` with `"command": "node", "args": ["/abs/path/to/designer-skill-mcp/dist/index.js"]` in any config above.






[![MIT](https://img.shields.io/badge/license-MIT-10b981?style=flat-square)](LICENSE)

[![package](https://img.shields.io/badge/designer--skill--mcp-0ea5e9?style=flat-square)](designer-skill-mcp/)

[![skill](https://img.shields.io/badge/designer--skill-7c3aed?style=flat-square)](skills/designer-skill/)

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/pythoughts-labs/designer-skill

Awesome Lists containing this project

README