Design Skill

Every AI-generated interface has a tell. The identical card grid. The purple-blue gradient. The hero that reads like a template. Two seconds of looking and you know a model made it. This skill exists to make that reaction impossible.

New here? Start with Using the Design Skill, a walkthrough of the skill in practice.

What v2 changes

v1 was a fork of pbakaus/impeccable: 55 reference files, 30 routed commands, a live browser subsystem, and zero measurement. The baseline proved it did not kill slop: with the skill loaded, models still produced gradient heroes and identical card grids, and build-from-brief got worse.

v2 is a rebuild measured by agent-skills-eval: SKILL.md teaches 10 tells with positive direction, five commands, grilling-first planning, and an on-demand eval scorecard. Scorecards live with the dev repo: BASELINE-v1.md and BASELINE-v2.md.

Five commands

| Command | Flags | What it does | |---------|-------|--------------| | detect | (script) | Run node scripts/detector.mjs <target>; report mechanical tells | | audit | --a11y --responsive --interaction --checkup --polish | Two-axis scored audit (Standards x Spec, parallel passes, no reranking) into .design-skill/audit-report.md, with a /24 health score | | deslop | --distill --bolder --quieter --harden | Kill slop tells with positive alternatives, not removals | | shape | (grill) | Interview before building: frontier rounds, every question carries a recommendation; settle register, mode, persona, direction, then a confirmed brief | | craft | --typeset --colorize --layout --animate --document | Brief-confirmed build; flags apply the matching doctrine; --document writes and validates DESIGN.md (google-labs-code/design.md format) |

Abilities are flags, never standalone commands. Say what you want in plain words: "this looks like AI made it" becomes an audit then a deslop; "build me a landing page" becomes a shape grill then a craft.

Two invocation modes

• Model-invoked. When UI is in view (screenshot, artifact, live page), the skill flags visible tells in one line and offers the matching command; when HTML is reachable it runs detect.
• User-invoked. shape and craft grill before building, never assume (the grilling protocol is borrowed from Matt Pocock's skills). audit and deslop accept a target.

The 10 tells

Tech gradient, generic tech hue, feature-tile grid, accent rail, unearned blur, stat monument, icon topper, template hero, default type stack, anti-reference echo. Each tell names why it reads machine-made and what to do instead (positive direction, not bans). The full table lives in SKILL.md.

Design laws in brief

• Modes. Persuade (decide and act), Operate (complete a task), Read (understand), Experience (be inside the work). Choose from the surface, not the category: a tool's landing page still persuades.
• Register. Brand (design IS the product) or product (design SERVES the product). Each has its own slop test, type and color stances, permissions and bans (reference/register.md).
• Type. Body measure 60-76ch, >= 1.25x scale, editorial contrast over flat stacks. Reject the training-data defaults (Inter, Fraunces, Space Grotesk and friends) on greenfield brand work.
• Color. OKLCH-first, hue chosen with reason. Palette is voice on brand surfaces; restrained with a state vocabulary on product surfaces.
• Motion. One authored moment per surface; purpose-gated; 150-250ms in product UI. Reference directions come from the motionsites.ai free gallery before animating.
• Interaction. States everywhere (hover, focus, active, disabled, loading, error, empty), touch targets 44x44px, keyboard paths, no hover-only functionality.
• Copy. The product's own language: controls name their action, errors name the problem and the recovery. No em dashes, no filler, no promotional words.
• Design.md. craft --document writes a DESIGN.md in the google-labs-code/design.md spec (frontmatter tokens + 8 ordered sections) and validates it with node scripts/design.mjs validate DESIGN.md.

Evals

The skill is measured, not assumed. Latest scorecard (2.1.0, merged across iterations 20-36): with_skill 232/239 (97.1%) vs without_skill 64/239 (26.8%), lift +68.4pp, on 66 evals with 53 deterministic detector rules backing the mechanical checks.

The eval suite (evals/, fixtures, harness config, .eval-key.* handling) is dev content and lives on the main branch only — this package ships the runtime skill, not the measurement rig. Run the scorecard from a clone of the repo, never from node_modules. Eval keys are personal and never committed.

Install

With skills.sh (recommended)

npx [email protected] add TudeOrangBiasa/design-skill

Project scope (default) lands in the agent's project skills path (.pi/skills/, .agents/skills/, .claude/skills/, depending on the agent). Add -g for a global install into the agent's user skills root:

| Agent | Global install command | |-------|------------------------| | Pi | npx [email protected] add TudeOrangBiasa/design-skill -a pi -g | | OpenCode | npx [email protected] add TudeOrangBiasa/design-skill -a opencode -g | | Claude Code | npx [email protected] add TudeOrangBiasa/design-skill -a claude-code -g | | Codex | npx [email protected] add TudeOrangBiasa/design-skill -a codex -g | | Cursor | npx [email protected] add TudeOrangBiasa/design-skill -a cursor -g | | Gemini CLI | npx [email protected] add TudeOrangBiasa/design-skill -a gemini-cli -g | | Shared .agents/skills agents | npx [email protected] add TudeOrangBiasa/design-skill -a universal -g |

From a local checkout, the plugin script wraps the same commands and covers omp, which skills.sh has no entry for:

bash plugins/install.sh pi       # global Pi install
bash plugins/install.sh omp      # symlink into ~/.agents/skills/
bash plugins/install.sh project  # into this repo's .agents/skills/

omp (example harness)

omp discovers authored skills one level under a skills/ root: <skills-root>/<skill-name>/SKILL.md. The canonical user-level root is ~/.agents/skills/ (the agents provider, enabled by default). One symlink installs it:

ln -sfn "$PWD" ~/.agents/skills/design-skill   # run from the repo root

From npm

npm install agent-design-skill

Point your agent at node_modules/agent-design-skill/SKILL.md, or symlink it into your agent's skills directory. Restart your agent afterwards.

Tooling

The skill ships zero servers, no MCP, and no browser automation. Every automation is a dependency-free Node CLI script under scripts/, invoked per run: node scripts/detector.mjs <target>, node scripts/load-context.mjs, node scripts/design.mjs validate DESIGN.md, node scripts/concept-seed.mjs. Any harness gets the same tools with nothing to configure beyond Node >= 18.

Sources

| Source | Contribution | |--------|-------------| | pbakaus/impeccable | Detector lineage, craft-floor, modes doctrine | | Emil Kowalski's skills | Mistake-catalog method: tell, why, fix | | CommandCode design | 10-tell slop theory (the teaching core) | | Matt Pocock's skills | Grilling protocol (shape) and two-axis review (audit) | | checklist.design | 703-check audit catalog (datasets/, git clones only) | | lawsofux.com | 30 laws with coverage research folded into audit doctrine | | motionsites.ai | Free-tier gallery as motion reference for craft --animate | | google-labs-code/design.md | DESIGN.md format + validation | | Anthropic's frontend-design skill | Craft and shape flows, production quality bar | | Jakub Krehel's skills | Layout doctrine (order by importance, anti-KPI-monument) and OKLCH palette generation (equal-L steps, consistent C%, accent from a different hue) |

Contributing

Contribution rules, check commands, and repo conventions live in CONTRIBUTION.md on main. This branch is the packaged release; development happens on main.

License

Apache 2.0. Attribution details in NOTICE.md.