jakubkrehel/skills instruction manual

Overview, scope and Claude Code classification

`jakubkrehel/skills` is an MIT-licensed, documentation-only collection of Agent Skills for building and reviewing product interfaces. Its documented subjects are UI polish, typography, colors, accessibility, layout, product writing and several procedural workflows. There is no repository build, lint or test tooling.

**Classification:** this repository extends Claude Code through **context injection**, packaged as a **Claude Code plugin** and also distributed as individually installable Agent Skills. The skill files provide task-specific procedures and domain guidance; the supplied files do not document a new executable tool surface, model provider or orchestration service. The plugin and marketplace are both named `interfaces`, and the supplied plugin manifest reports version `1.6.2`.

The collection has two skill shapes. Domain skills hold reusable knowledge, such as color or layout rules. Verb skills define procedures, such as reviewing a change, generating variants or stress-testing a component. Most skills may be selected by the model from their trigger descriptions. Four are explicitly user-invoked: `interface-review`, `variant`, `break` and `explain-interface`. They are not intended to start implicitly. The cross-discipline `better-interface` skill can route work to domain skills, but it cannot invoke a user-only skill such as `interface-review`; it instead asks the user to run that command.

Installation, command names and updates

Choose one of the two documented installation methods. Both install the same skills, but command names differ afterward.

**Skills CLI:** this method works with Claude Code, Codex, Opencode and other agents. It allows selection of individual skills or installation of the full collection. Run:

npx skills add jakubkrehel/skills

Skills installed this way keep plain names. For example, invoke the change reviewer as:

/interface-review

**Claude Code plugin:** run both commands inside Claude Code. This installs every repository skill together:

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

Plugin-installed skills are namespaced. The documented change-review and variant invocations are:

/interfaces:interface-review
/interfaces:variant

To update the installed plugin later, run the documented update command and then restart Claude Code:

/plugin update interfaces@interfaces

Do not mix naming schemes. Use `/interface-review` for the skills-CLI installation and `/interfaces:interface-review` for the plugin. The plugin updates in place as a single collection. The repository also contains `opencode.json` so Opencode discovers `skills/` while the repository itself is open, but distribution to Opencode users is documented through the skills CLI rather than repository-specific command wrappers.

Choosing among the eleven skills

Use the narrowest skill that matches the task.

• **`better-interface`** performs a holistic review by coordinating every available `better-*` domain skill and producing one ranked verdict.
• **`interface-review`** reviews uncommitted work, a branch, range or pull request. It resolves change scope and classifies findings as introduced, regressed or pre-existing.
• **`variant`** builds three genuinely different versions of one UI piece behind a picker, then lets the user choose.
• **`break`** renders one real component under applicable hostile states and leaves a visual report page showing what survived or broke.
• **`explain-interface`** accepts a URL or screenshot plus the effect of interest, finds the layers behind it and explains their roles.
• **`better-ui`** covers visual polish: radius, shadows, optical alignment, icons, transitions, motion and micro-interactions.
• **`better-typography`** covers typeface choice and pairing, type scales, spacing, wrapping and truncation.
• **`better-colors`** covers palettes, ramps, semantic tokens, theming, contrast measurement, gamut and gradients.
• **`better-accessibility`** covers focus, keyboard support, ARIA, forms, screen readers, hit areas and motion requirements.
• **`better-layout`** covers grouping, alignment, reading order, spacing, progressive disclosure, breakpoints, safe areas and RTL layout.
• **`better-writing`** covers labels, terminology, voice, tone, errors, settings, placeholders and empty states.

Choose `better-interface` for a screen, flow or feature as a whole. Choose `interface-review` when the request identifies a change. Choose a domain skill when only that discipline needs review or implementation guidance. Invoke `variant`, `break` or `explain-interface` deliberately; the repository marks these procedural skills as user-only.

Holistic and change-scoped reviews

For a holistic review, `better-interface` first resolves a credible screen, flow, feature or repository scope. It inspects available domains in this order: accessibility, layout, writing, typography, colors and UI polish. Missing owners are reported as `Not reviewed`; their rules are not reconstructed from memory. Findings require evidence, cite `path/to/file:line`, show the current implementation and are consolidated by root cause. The report is capped at 15 findings and uses `HIGH`, `MEDIUM` and `LOW` severity. Confirmed blockers include inaccessible controls, missing visible focus, keyboard gaps, ignored reduced motion, clipping at 320px or 200% zoom, failed required text contrast, color-only meaning, unsafe destructive actions, inaccessible truncated values, hidden content without cues and errors without recovery instructions. Reviews are read-only unless implementation is also requested.

Use `interface-review` for uncommitted work, a current branch, a pull request or an explicit range. With no target, it checks whether `HEAD` is ahead of the default branch merge base, including uncommitted changes; otherwise it uses a dirty working tree. If neither exists, it asks the user to choose the last commit, a named target or a whole-repository audit rather than inventing scope. It excludes lockfiles, snapshots, generated output, vendored code and binaries, then expands changed files to direct consumers, or two hops for tokens and shared primitives. It reads both added and removed lines and classifies each finding as `Introduced`, `Regression` or `Pre-existing`. At most three pre-existing findings are shown, and they do not affect the verdict. The final verdict is `Block` if a relevant `HIGH` remains and `Approve` otherwise.

Design exploration with `variant`

`variant` answers “which of these?” rather than judging whether one design is correct. Scope one UI piece, such as a metric card rather than an entire dashboard. Read the project’s styling system, component library, motion library, tokens, density, voice and surrounding page. If no project exists, the documented fallback is neutral grays, one accent and the system font stack, with that fallback disclosed.

Default to three variants; use five only when requested or when the design space is genuinely broad. Before coding, select one primary axis: structure, density, emphasis, type or voice. Give each option a meaningful name and a distinct position on that axis. Secondary decisions may follow for coherence, but varying every axis prevents useful comparison.

Every candidate must retain accessible names, keyboard reachability, visible focus, 320px resilience and non-color cues. Build the candidates into the real containing page with realistic content and neighbors. Select them through a URL parameter such as `?variant=quiet`, controlled by a floating picker. Render one full-size variant at a time; if no real page can host it, use one self-contained HTML file with the same picker.

Present a neutral tradeoff table with each variant’s axis position, appropriate use and cost. State where the picker runs, which key switches it and the judged viewport width. Do not preselect a winner. After the user chooses, promote that option into production conventions and remove the alternatives and harness. If another round is requested, keep the harness and explore new positions around the preferred direction.

Component stress testing with `break`

`break` tests whether one component survives production-shaped inputs. First narrow the request to one component and restate what it accepts, renders and where it lives. Read its props, slots, states and data, then keep only applicable scenario axes. Record included scenarios and explain dropped axes before building.

Create one throwaway page that imports the real component and renders it once per scenario in a single column. Add only short labels, fixed-width containers and fixture props. Keep the application’s actual layout, fonts, global styles and tokens. Do not rebuild the component, simulate themes, import production state or connect live data. In environments that separate server and client components, the documented Next.js guidance is to make the page client code with `"use client"`. Show width cases in fixed containers so one load displays all widths.

The observation budget is one browser load and one top-to-bottom pass. Report only visible failures, such as text escaping an edge; do not turn predicted failures or aesthetic preferences into findings. If a browser is unavailable or would require launching, window management or debugging, skip observation and hand the page URL to the user. Mark observed breaks beneath their scenario labels so the page itself remains the visual report.

Return a table with `Scenario`, `Observed` and `Owner`. The owner is the relevant domain skill, not `break`, because this skill issues no verdict and owns no repair rules. “Everything survived” plus the scenario list and page location is a complete result. Leave the report page running until the user asks for deletion. Fix only when requested, then re-render failed scenarios to confirm.

Domain guidance: polish, color and layout

**UI polish (`better-ui`).** Preserve project tokens and motion language while applying exact documented recipes. Nested radii follow outer radius = inner radius + padding. Use shadows for elevation and borders for structure. Prefer interruptible CSS transitions for interactive state changes and keyframes for one-time staged sequences. Contextual icons animate from scale `0.25`, opacity `0` and blur `4px` to scale `1`, opacity `1` and blur `0px`. Motion-library springs use `duration: 0.3` and `bounce: 0`; CSS cross-fades use `cubic-bezier(0.2, 0, 0, 1)`. Press feedback uses `scale(0.96)`. Name transitioned properties, avoid `transition: all`, use `will-change` only for transform, opacity or filter when stutter is observed, and keep high-frequency feedback instant or at most `150ms` on color and opacity.

**Colors (`better-colors`).** Reuse the project’s notation and tokens. For a new system, `oklch()` is the preferred default. Build only needed neutral, accent and status ramps. Primitive tokens name hues; semantic tokens name roles and are what components consume. Keep hue stable across a ramp, vary perceived lightness evenly, peak vividness in the middle and avoid pure black or white endpoints. One color should carry one meaning, and filled emphasis should normally identify one primary action per view. Measure the actual rendered foreground/background pair; never estimate contrast. Do not change a failing pair unless asked, and remeasure after any change.

**Layout (`better-layout`).** Group with spacing before backgrounds or separators; inter-group gaps should be at least twice intra-group gaps. Align shared edges, order by importance and use logical properties such as `padding-inline-start`. Give hidden content a visible cue. Derive breakpoints from where content stops fitting, prefer container queries for component adaptation and test extremes first. Avoid fixed text dimensions, plan for translation, protect critical actions from clipping and account for safe areas.

Domain guidance: writing, typography and accessibility

**Writing (`better-writing`).** Inspect nearby copy and existing terminology before editing. Keep one product voice while adjusting tone to stakes: warm for onboarding, neutral for routine settings, calm for errors and serious for security or data loss. Address the reader directly, prefer plain translatable language and use complete localized templates rather than concatenated fragments. Buttons begin with action verbs; consequential confirmations repeat the consequence. Links describe their destinations. Apply one capitalization policy per element type, with sentence case as the safer default. Toggle labels describe the on state. Errors sit beside the problem and explain recovery without blame, jokes or exclamation marks. Empty states orient the reader and offer one next action. Placeholders show formats but never replace visible labels. Source inspection is sufficient for this skill’s verification.

**Typography (`better-typography`).** The supplied documentation identifies this skill as the owner of typeface selection and pairing, type scales, spacing, wrapping, truncation, visual text rendering, font behavior, punctuation and text-level bidirectional behavior. Use it for those concerns rather than substituting layout, writing or UI-polish rules.

**Accessibility (`better-accessibility`).** The supplied documentation identifies this skill as the owner of semantic HTML, focus states, keyboard behavior, accessible names, ARIA, forms, screen-reader support, hit areas, assistive-technology behavior and reduced-motion requirements. It decides when contrast is required and whether a pair fails, while `better-colors` measures and remediates the pair. It owns semantic heading structure while typography owns visual rendering. These boundaries prevent one concern from being reported several times.

Reporting conventions, limitations and repository maintenance

Standalone domain reviews group findings under the violated principle and use rows for `Severity`, `Location`, `Before`, `After` and `Why`. Each location is `path/to/file:line`; one root cause lists every affected location. Unavailable checks are `Not verified`, not defects. Domain reviews end with `Block` when a `HIGH` remains and `Approve` otherwise, but never approve coverage that was not inspected. Clean reports use the documented domain-specific wording, such as “No actionable UI-polish findings,” “No actionable color findings,” “No actionable layout findings,” or “No actionable writing findings.”

The evidence supplied here does not include the full `SKILL.md` bodies for `better-typography`, `better-accessibility` or `explain-interface`, nor all linked reference files. Their descriptions and ownership boundaries can be documented, but undocumented procedures or commands must not be inferred. Results also depend on the target project, available browser access and which skills are installed.

For maintainers, each skill lives at `skills/<skill-name>/SKILL.md`; supporting Markdown sits beside it. The entry file carries matching frontmatter `name`, a description, a plain-name H1, a two-sentence opener, calibration, point-carrying headings, handoffs and domain reporting where applicable. User-invoked skills set both `disable-model-invocation: true` and `policy.allow_implicit_invocation: false`. Every change under `skills/` must bump the plugin version in `.claude-plugin/plugin.json`, because that version is the update signal. The documented validation commands are:

claude plugin validate .
claude plugin validate .claude-plugin/plugin.json

After renaming, update the directory, frontmatter name and OpenAI `display_name`, then search for the old name. Repository prose uses sentence-case headings, straight quotes, no serial comma and sentences no longer than 30 words.