convez.ai
MCP ServerDesign & UIIntermediário
Pythoughts-labs

Designer Skill MCP

Pythoughts-labs/designer-skill

Vocabulário de design production-grade para agentes de código via MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que fornece a agentes de código um vocabulário de design em nível de produção, cobrindo tipografia, estética, movimento, performance e anti-slop. Integra-se com Claude Code, Cursor, Codex CLI e outros clientes MCP para elevar a qualidade visual e técnica do código gerado.

Instalação

$npx convez-ai Pythoughts-labs/designer-skill

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
53
Forks
5
Acompanhando
0
Saúde
25%
Último commit
há 4 dias
Versão
v0.27.0
Issues abertas
1
Contribuidores
1

Casos de uso

  • Elevar qualidade visual de interfaces geradas por agentes IA
  • Aplicar sistemas de design consistentes em projetos automatizados
  • Auditar e refatorar UI sem quebrar funcionalidade existente
  • Evitar padrões genéricos e 'AI slop' em código frontend

Veredito

Ferramenta sólida e bem estruturada para quem quer que agentes IA produzam design digno de produção. Reduz decisões genéricas e fornece referências concretas — útil em pipelines de geração de código, mas requer integração explícita com cliente MCP.

README

A tradução para o português deste README ainda está na fila.

Production-grade design skill for coding agents, delivered as an MCP server.

npm version license node tiers agents

Architecture · Claude Code Plugin · Codex Plugin · Skill Setup · Quick Setup · Full MCP Configs · Env Vars

npm i designer-skill-mcp

What this is

designer-skill is a composite design reference for coding agents — a lightweight router (skills/designer-skill/SKILL.md) that dispatches to seven specialist reference files covering visual fundamentals, aesthetic systems, motion and interaction, engineering and performance, anti-AI-slop discipline, refactor/redesign loops, and a verb-driven command playbook. Any coding agent that reads these files gains an opinionated, production-grade design vocabulary before touching a single line of UI code.

designer-skill-mcp is the Model Context Protocol server that exposes designer-skill to any MCP-compatible client — Claude Code, Codex CLI, Cursor, VS Code, Kilo Code, Open Code, Pi, and pythinker. It ships in two tiers: a Guidance tier (no API key required) that hands the skill to your agent via tools, resources, and a prompt; and an Active tier (requires ANTHROPIC_API_KEY) that adds apply_designer — a Claude-backed tool that runs the full skill and returns a streamed audit, redesign, or build result.


Routing Map

The 7 Reference Files

These are design surfaces, not client platforms. The 8 supported agent clients are listed separately in MCP Setup.

Open thisWhen the task is about
reference/design-principles.mdVisual fundamentals — typography, spacing & rhythm, color & contrast, layout & grid, hierarchy, depth. The aesthetic-neutral baseline.
reference/aesthetic-systems.mdChoosing or executing a specific look — 5 opinionated design languages (Minimalist, Brutalist, Soft, High-end-Stitch, Brand-identity) with concrete palettes, fonts, and shadow tokens.
reference/motion-and-interaction.mdWhat to animate, how fast, which curve; springs, micro-interactions, gestures, scroll, perceived performance, reduced-motion.
reference/engineering-and-performance.mdComponent architecture, design tokens/CSS vars, hardware acceleration, responsive/fluid, accessibility, Core Web Vitals, framework-honest output, real-data hardening.
reference/avoid-ai-slop.mdNot looking "AI-made" — the cross-register ban-list, category-reflex checks, and the output-completeness contract.
reference/refactor-and-redesign.mdImproving existing UI without breaking it — audit, diagnose generic patterns, the redesign loop, image/reference-to-code.
reference/command-playbook.mdWhich verb/move maps to the user's intent (build, polish, bolder, quieter, animate, harden, redesign, …).

Intent → Verb Dispatch

The dispatch_intent tool maps a natural-language request to the design verb(s) and reference files an agent should load before acting.

Intent phraseVerb(s)Files to read
"make it pop"bolder · colorizeaesthetic-systems, design-principles
"it feels off"audit · diagnoserefactor-and-redesign, avoid-ai-slop
"production-ready"harden · a11yengineering-and-performance
"add some motion"animatemotion-and-interaction
"it looks AI-made"de-slop · differentiateavoid-ai-slop, aesthetic-systems
"redesign this"audit · redesignrefactor-and-redesign, command-playbook

Session Preflight Order

Run this sequence before writing any UI code:

  1. Scope the surface and register — landing page, dashboard, component, form? Decide register: brand (distinctiveness is the bar) vs product (earned familiarity is the bar).
  2. Commit to one aesthetic system from reference/aesthetic-systems.md — one language per surface, never mix two systems' signatures.
  3. Run the category-reflex check in reference/avoid-ai-slop.md before committing to a palette or type direction.
  4. Build on the neutral baseline (design-principles.md) + engineering layer (engineering-and-performance.md), add motion last.
  5. For existing UI, follow the audit → diagnose → redesign loop in reference/refactor-and-redesign.md instead of rebuilding from scratch.
  6. Run the ship gate (anti_slop_checklist tool or reference/avoid-ai-slop.md) before declaring work done.

Two-Tier Model

Guidance tier — no API key neededActive tier — requires ANTHROPIC_API_KEY
get_design_system — returns the SKILL.md routerAll guidance tools, plus:
get_reference — returns any of the 7 reference filesapply_designer — runs Claude loaded with the full skill
dispatch_intent — maps intent phrase → verbs + filesStreams a complete audit, redesign, critique, or build result
anti_slop_checklist — ship-gate checklistModel override via DESIGNER_MCP_MODEL env var
designer://skill and designer://reference/{name} resourcesNo partial output — bound by the output-completeness contract
design prompt (bundles task + relevant skill context)Default model: claude-opus-4-8

Zero config to start. Omit the env block from any MCP config below to run guidance-only. Your agent does the design work; the skill files guide it. Add ANTHROPIC_API_KEY only when you want Claude to do the work directly via apply_designer.


Claude Code Plugin (recommended)

This repo is a plugin and its own marketplace — for both Claude Code and Codex. One install gets you both the designer-skill skill and the designer-skill MCP server:

/plugin marketplace add Pythoughts-labs/designer-skill
/plugin install designer-skill@pythoughts-labs

What the plugin ships:

  • Skill — skills/designer-skill/ (router + 7 reference files), invocable as designer-skill.
  • MCP server — designer-skill-mcp via npx (.mcp.json), guidance tier with zero config. Add ANTHROPIC_API_KEY to your environment to unlock the apply_designer active tier.

To verify after install: /plugin lists the plugin, /mcp shows the designer-skill server, and the skill appears in the Skill tool list.

Codex Plugin

The same repo doubles as a Codex plugin (.codex-plugin/plugin.json); Codex reads .claude-plugin/marketplace.json as a legacy-compatible marketplace. In the Codex CLI:

codex plugin marketplace add Pythoughts-labs/designer-skill

Then open /plugins in Codex, select the pythoughts-labs marketplace, and install designer-skill. Plugin-installed skills are namespaced, so it appears as designer-skill:designer-skill.

Skill-only alternative — install just the skill into your local Codex setup:

Use $skill-installer to install the designer-skill skill from https://github.com/Pythoughts-labs/designer-skill (skills/designer-skill)

or copy it manually:

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

Restart Codex after installing; invoke with $designer-skill or let it trigger on design tasks.


Skill Setup

For agents that support native skill or prompt-file loading (not MCP).

Claude Code (manual copy)

Prefer the plugin install above. To install just the skill by hand, copy skills/designer-skill/ into your Claude Code skills directory:

# Option A — copy into project skills
cp -r skills/designer-skill/ .claude/skills/designer-skill/

# Option B — copy into global skills
cp -r skills/designer-skill/ ~/.claude/skills/designer-skill/

Claude Code picks up the skill via the name: designer-skill frontmatter in SKILL.md. Invoke it with the Skill tool:

Use the designer-skill to [your task]

No API key required for skill-only use — your Claude Code session supplies the model.

Pi (@earendil-works/pi-coding-agent)

Register the skill by pointing Pi at the SKILL.md entry point. Pi reads the name and description frontmatter for routing, so no additional config is needed beyond the file path:

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

Pi will route design-intent prompts to the skill automatically based on the description field in the frontmatter.


Quick Setup

For AI agents reading this repo: All commands below are copy-paste ready. Package: designer-skill-mcp — https://www.npmjs.com/package/designer-skill-mcp Repo: https://github.com/Pythoughts-labs/designer-skill

The four configs below cover the most common agent runtimes. Full reference for all 8 clients ↓


Pythinker

Pythinker and Codex CLI use the same setup — an identical command / args / env server definition. Pythinker writes it as YAML (mcpServers:), Codex as TOML ([mcp_servers.*]). Configure Pythinker once and the Codex config below is the same thing in a different file format.

Add to ~/.pythinker/config.yaml:

Guidance-only:

mcpServers:
  designer-skill:
    command: npx
    args: ["-y", "designer-skill-mcp"]
mcpServers:
  designer-skill:
    command: npx
    args: ["-y", "designer-skill-mcp"]
    env:
      ANTHROPIC_API_KEY: sk-ant-...

Codex CLI

Same server definition as Pythinker above, managed via the codex CLI (or as TOML in ~/.codex/config.toml):

Guidance-only:

codex mcp add designer-skill -- npx -y designer-skill-mcp
codex mcp add designer-skill --env ANTHROPIC_API_KEY=sk-ant-... -- npx -y designer-skill-mcp

Or edit ~/.codex/config.toml directly:

[mcp_servers.designer-skill]
command = "npx"
args = ["-y", "designer-skill-mcp"]
env = { ANTHROPIC_API_KEY = "sk-ant-..." }

Claude Code

Guidance-only:

claude mcp add designer-skill -- npx -y designer-skill-mcp

Active tier:

claude mcp add designer-skill -e ANTHROPIC_API_KEY=sk-ant-... -- npx -y designer-skill-mcp

Pi

Add to Pi's MCP server config:

Guidance-only:

{
  "mcpServers": {
    "designer-skill": {
      "command": "npx",
      "args": ["-y", "designer-skill-mcp"]
    }
  }
}
{
  "mcpServers": {
    "designer-skill": {
      "command": "npx",
      "args": ["-y", "designer-skill-mcp"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

# designer-skill-mcp — structured config reference
# Source: https://github.com/Pythoughts-labs/designer-skill
# Package: https://www.npmjs.com/package/designer-skill-mcp
# Command (all clients): npx -y designer-skill-mcp

agents:
  # pythinker and codex_cli share the same command/args/env server shape;
  # only the file format differs (YAML mcpServers vs TOML [mcp_servers.*]).
  pythinker:
    config_file: ~/.pythinker/config.yaml
    format: yaml
    key: mcpServers
  codex_cli:
    cli_command: "codex mcp add designer-skill -- npx -y designer-skill-mcp"
    config_file: ~/.codex/config.toml
    format: toml
    key: mcp_servers
  claude_code:
    cli_command: "claude mcp add designer-skill -- npx -y designer-skill-mcp"
    active_tier: "claude mcp add designer-skill -e ANTHROPIC_API_KEY=<key> -- npx -y designer-skill-mcp"
  pi:
    format: json
    key: mcpServers

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

active_tier:
  command: npx
  args: ["-y", "designer-skill-mcp"]
  env:
    ANTHROPIC_API_KEY: "<your-anthropic-api-key>"

MCP Setup — All 8 Clients

Add the designer-skill server to your agent's MCP config. Each block below shows two variants:

  • Guidance-only — no env block, no API key required.
  • Active — adds ANTHROPIC_API_KEY to enable apply_designer.

Pythinker first, Codex right behind — both use the same server definition (command / args / env). Pythinker writes it as YAML under mcpServers:; Codex writes the identical shape as TOML under [mcp_servers.*]. Learn one, you know both.

Config file: ~/.pythinker/config.yaml

Guidance-only:

mcpServers:
  designer-skill:
    command: npx
    args:
      - "-y"
      - designer-skill-mcp

Active (with apply_designer):

mcpServers:
  designer-skill:
    command: npx
    args:
      - "-y"
      - designer-skill-mcp
    env:
      ANTHROPIC_API_KEY: sk-ant-...

Same server shape as Codex CLI (below) — only the file format differs. Restart pythinker after saving.

Config file: ~/.codex/config.toml (or project-scoped .codex/config.toml in trusted projects). The fastest path is the CLI:

codex mcp add designer-skill -- npx -y designer-skill-mcp

Guidance-only:

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

Active (with apply_designer):

[mcp_servers.designer-skill]
command = "npx"
args = ["-y", "designer-skill-mcp"]
env = { ANTHROPIC_API_KEY = "sk-ant-..." }

Same server shape as Pythinker (above), in TOML. Restart Codex after editing config.toml; verify with /mcp inside the Codex TUI.

Config file: ~/Library/Application Support/Claude/claude_desktop_config.json

Guidance-only:

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

Active (with apply_designer):

{
  "mcpServers": {
    "designer-skill": {
      "command": "npx",
      "args": ["-y", "designer-skill-mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

Restart Claude Desktop after saving. The server appears in the tools panel as designer-skill.

Project-level (.cursor/mcp.json at repo root):

Guidance-only:

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

Active (with apply_designer):

{
  "mcpServers": {
    "designer-skill": {
      "command": "npx",
      "args": ["-y", "designer-skill-mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

Global: Open Cursor Settings → Features → MCP → + Add new MCP server, then enter the command and args above. The global config is stored at ~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp/mcp.json on macOS.

Config file: .vscode/mcp.json at workspace root. Requires VS Code 1.99+ (built-in MCP agent mode) or the MCP extension.

Guidance-only:

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

Active (with apply_designer):

{
  "servers": {
    "designer-skill": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "designer-skill-mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

Note the VS Code-specific format: servers (not mcpServers) and the required "type": "stdio" field. Reload the VS Code window after saving.

Kilo Code stores MCP servers at: ~/Library/Application Support/Code/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json (macOS)

The fastest path is via the UI: open the Kilo Code panel → MCP Servers → Edit MCP Settings, then add:

Guidance-only:

{
  "mcpServers": {
    "designer-skill": {
      "command": "npx",
      "args": ["-y", "designer-skill-mcp"],
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Active (with apply_designer):

{
  "mcpServers": {
    "designer-skill": {
      "command": "npx",
      "args": ["-y", "designer-skill-mcp"],
      "disabled": false,
      "alwaysAllow": [],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

The server activates immediately — no VS Code restart needed.

Config file: opencode.json at project root, or ~/.config/opencode/config.json for global config.

Guidance-only:

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

Active (with apply_designer):

{
  "mcp": {
    "designer-skill": {
      "type": "local",
      "command": ["npx", "-y", "designer-skill-mcp"],
      "environment": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

Open Code uses mcp (not mcpServers) and environment (not env) for its MCP server definitions. Restart Open Code after saving.

Pi can use the skill natively (see Skill Setup) or via MCP. For MCP, add to Pi's server config:

Guidance-only:

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

Active (with apply_designer):

{
  "mcpServers": {
    "designer-skill": {
      "command": "npx",
      "args": ["-y", "designer-skill-mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

See ~/pi_setup.md for the full Pi config, extensions, and audit log.


Tools Reference

ToolRequires key?Purpose
get_design_systemnoReturns the SKILL.md router — call first (preflight order, precedence rule, routing map, ship gate).
get_referencenoReturns one of the 7 reference files by name (e.g. "aesthetic-systems", "avoid-ai-slop").
dispatch_intentnoMaps a natural-language request phrase to design verb(s) and the reference files to read.
anti_slop_checklistnoReturns the ship-gate checklist from avoid-ai-slop.md — run before declaring any UI work done.
apply_designeryesRuns Claude loaded with the full designer-skill and streams a complete audit, redesign, or build result.

Resources: designer://skill (the full SKILL.md) and designer://reference/{name} (any of the 7 reference files).

Prompt: design — accepts task (required) and aesthetic (optional) arguments; bundles the relevant skill context with your task into a single ready-to-run prompt.


Environment Variables

VariableRequiredDefaultPurpose
ANTHROPIC_API_KEYActive tier only—Enables the apply_designer tool. Omit to run guidance-only.
DESIGNER_MCP_MODELNoclaude-opus-4-8Override the model used by apply_designer.

Build & Dev

npm install
npm run build   # syncs skills/designer-skill/ → assets/skill/, compiles TypeScript to dist/
npm test        # 20 unit tests — no API calls, no key required

HTTP mode (for hosting or remote clients):

node dist/index.js --http --port 3017             # binds 127.0.0.1 (safe default)
node dist/index.js --http --port 3017 --host 0.0.0.0  # expose publicly — add your own auth/proxy

Point HTTP clients at http://127.0.0.1:3017/mcp (Streamable HTTP transport). The HTTP server includes an Origin guard against DNS-rebinding; there is no built-in auth layer for public exposure.

Local checkout (instead of npx): replace "command": "npx", "args": ["-y", "designer-skill-mcp"] in any config block above with "command": "node", "args": ["/abs/path/to/designer-skill-mcp/dist/index.js"].


MIT License · designer-skill-mcp · designer-skill

Ver o original no GitHub

Bom para

Relacionados