The Problem

Building a polished interface — typography, color systems, accessibility, spacing — is knowledge that lives in designers' heads, not in codebases. When an AI coding agent works on UI, it produces output that is technically correct but visually mediocre, because the agent has no framework for what "good" means. This repo encodes that design judgment as machine-readable skill definitions so agents can apply it consistently.

What This Does

A collection of 11 Claude-style agent skills, each a folder under skills/ containing a SKILL.md (the instruction file an agent loads), an agents/openai.yaml (agent metadata), and topic-specific markdown references. better-typography covers type scale, variable fonts, and OpenType features; better-colors covers palette generation and contrast; better-interface combines all the better-* skills into one review pass. Three skills are user-invoked tools: interface-review (multi-category audit), explain-interface (reverse-engineer existing UI), and break (stress-test a component across states).

The content is original writing from the author's design engineering magazine, Interfaces. This fork is a verbatim copy of jakubkrehel/skills (4,892 stars upstream) with no modifications visible in the file structure.

How It Is Wired

There is no executable code. The "runtime" is the agent framework that loads these markdown files. Entry points are the SKILL.md files — an agent reads one, follows its instructions, and applies them to the user's codebase. The agents/openai.yaml files define how each skill presents itself to the agent. Distribution is handled by three config files: .claude-plugin/marketplace.json and plugin.json register the collection with Claude Code's plugin marketplace, and opencode.json does the same for OpenCode. The skills.sh badge in the README suggests compatibility with the skills.sh registry.

The blast radius is concentrated in the SKILL.md files — each is the single instruction set that drives an entire skill's behavior. The better-* skills are modular; better-interface and interface-review depend on all of them, so changing a shared topic file (e.g., contrast.md) ripples through both. There is no hub-and-spoke cycle to worry about: dependencies are one-directional, and no code paths exist to trace.

How To Use It

Install via the documented commands:

npx skills add jakubkrehel/skills

For Claude Code:

/plugin marketplace add jakubkrehel/skills
/plugin install interfaces@interfaces

No environment variables, build steps, or configuration beyond the plugin install. The skills activate when an agent invokes them by name. For a fork of this repo, the installation commands would need the fork's owner/path substituted.

Real-World Use

A developer asks Claude to improve a dashboard's UI. The agent invokes interface-review, which routes through the better-* skills: better-typography checks the type scale, better-colors verifies contrast ratios against WCAG thresholds, better-accessibility flags missing ARIA semantics, better-writing reviews the product copy. The agent returns a categorized findings list, then applies fixes directly to the project files.

Code Health & Issues

Static analysis flags two SDLC gaps, both expected for a content-only repo:

  • Med - No test files detected — repository-wide. No test harness exists, but the repo contains no executable logic to test; validation happens when agents apply the skills.
  • Med - No CI/CD pipeline detected — .github/ absent. No automated gate on markdown linting or skill formatting, so broken links or malformed YAML would ship silently.

No license concerns: LICENSE is present. The repo's quality risk is content drift — the skills encode opinionated design guidance that will age as accessibility standards and browser capabilities change.

The Bottom Line

A well-organized, high-quality skills collection that turns design expertise into agent-invokable instructions, and the upstream star count reflects real demand. There is nothing to change in code because there is no code — the value is in the writing. Anyone building UI with an agent should install the upstream version; forking this repo only makes sense if you intend to maintain a customized design standard.