Claude config — user guide

What is installed on this machine, when to reach for it, and what to avoid.

Everything here lives in the claude-config repo and is symlinked into ~/.claude, so a git pull applies it immediately. Only new MCP servers need ./install.sh re-run.

Path	Applied as
settings.json	~/.claude/settings.json — permissions, theme, hooks
CLAUDE.md	~/.claude/CLAUDE.md — loaded every session
skills/	~/.claude/skills — 42 skills
commands/	~/.claude/commands — slash commands
mcp-servers.json	applied via claude mcp add-json by install.sh
.env	secrets, gitignored, synced with keyway pull

Check state at any time with claude-config-check.

The short version

Two things happen automatically, everything else you ask for.

Automatic: when you work on UI, the UX Patterns guidance in CLAUDE.md is already in context, and design-flow is there to route the task. You do not need to invoke anything for Claude to know that check_accessibility lies about passes.

On request: the 15 Impeccable verbs (/polish, /arrange, …) are focused passes that rewrite code. They only run when you name them. That is deliberate — a skill that rewrote your typography unprompted would be worse than one you invoke.

Start with /design-flow

With ~40 design skills installed, the hard part is picking the right one. design-flow is a router, not a worker: it classifies the request as greenfield, brownfield or motion, names the exact skill sequence, and states the route before running so you can correct it in one line.

Its brownfield track diagnoses before prescribing — audit and critique first, then the fix — which is the opposite of what happens if you guess a skill from its name.

Slash commands

Design data

/ui-search color calm professional saas
/ui-search style admin dashboard
/ui-search ux empty state
/ui-design-system internal analytics dashboard for logistics

Backed by a local database — 84 styles, 192 palettes, 74 font pairings, 98 UX guidelines, 25 chart types, across 22 stacks. Runs offline, no API key.

/ui-design-system writes nothing unless you ask it to persist.

One quirk worth knowing: --stack replaces the domain search rather than filtering it. --domain color --stack vue returns zero results, because stack tables hold framework guidance (component naming, reactivity), not palettes.

Review

/ux-audit src/views/Login.vue

Finds the matching UX pattern, reads the code, reports findings with severities. Writes nothing, files nothing.

Finishing a feature

Run these when a feature works and you want it to feel finished. One pass each, in roughly this order:

/critique     UX evaluation, no changes
/arrange      layout, spacing, visual rhythm
/typeset      typography
/colorize     colour where it is flat
/polish       final detail pass

Others for specific moods: /bolder, /quieter, /distill, /delight, /overdrive, /normalize, /clarify, /onboard, /adapt.

First run in a repo: these 15 skills stop and demand /teach-impeccable if the project has no design context. Run it once per repo; it writes .impeccable.md. members and stackr already have one.

Motion

/animate                      build one animation from scratch
/review-animations            critique motion in a diff
/improve-animations           audit a whole codebase's motion
/find-animation-opportunities what here should move?
/animation-vocabulary         what is that effect called?

Careful: animate (Kowalski's — builds an animation decision by decision, the default) and animate-basic (the Impeccable pack's lighter review-and-enhance pass) are different skills with near-identical names. For new motion, prefer animate.

Engineering

/audit      accessibility, performance, theming, responsive
/optimize   loading, rendering, bundle size
/harden     error handling, i18n, overflow, edge cases
/extract    pull reusable components and tokens into the design system

These four have no teach-impeccable prerequisite.

What is installed

42 skills across three suites plus standalone ones, and ui-ux-pro-max as a plugin.

Suite	Count	Character
Impeccable	20	Focused verbs. Explicit invocation. 15 need design context.
Kowalski	10	Animation depth, plus Apple-style interaction and library choice.
UI/UX Pro Max	plugin	Searchable design database, tokens, brand, slides. Installed via enabledPlugins, not a skill directory.
Standalone	11	ux-audit, frontend-design, stack skills (Vue, Nest, Firebase), dokploy-migrate.

Plus the ux-patterns MCP server: 92 patterns in 11 categories, served from a local build.

ask-sonner is React-specific (Sonner is a React toast library) and will rarely apply here, since most projects on this machine are Vue.

Things that will bite you

design advertises more than it can do. Logo, icon and CIP generation need ai-artist / ai-multimodal and a GEMINI_API_KEY, none of which are installed. Its description says so, and its routing guide lists what is missing. Brand, tokens, slides and banners work.

The UX Patterns MCP is a rubric, not an analyser. check_accessibility reports criteria as passed from markup alone — including contrast and focus-visible, which cannot be judged without rendering. Use its findings, never its passes.

MCP servers cannot live in settings.json. Claude Code silently ignores an mcpServers key there. They go through claude mcp add-json, which is what install.sh does.

Moving the clone breaks everything silently. The symlinks store absolute paths. Re-run ./install.sh after moving it; the SessionStart hook catches it on the next session.

Using this from an autonomous agent

Skills work in headless runs — CLAUDE.md is user-level, so the routing applies to claude -p too.

Safe to run unattended: skills that report. Two state read-only behaviour explicitly — improve-animations is "read-only on source code, it plans improvements, it does not apply them", and find-animation-opportunities is "read-only; it proposes motion with exact values, it does not implement it". ux-audit reports by design but can apply fixes if asked, so pin it with --permission-mode plan.

Check per skill, not per suite: prototype sounds read-only and is not — it builds several working versions of a UI behind a picker, so it writes files.

claude -p "/ux-audit src/views/NewFeature.vue" --permission-mode plan
claude -p "/find-animation-opportunities src/views" --permission-mode plan

Not safe: the taste-driven passes. /polish rewrites working code on subjective grounds, and its diffs are exactly the kind a human has to look at. /animate invents motion nobody asked for when fired automatically. Both belong in an interactive session. And any of the 15 prerequisite skills will simply stall waiting for teach-impeccable in a repo that has no .impeccable.md.

The one built for autonomy is improve-animations: it surveys read-only and emits self-contained implementation plans for other agents — including cheaper models — to execute. Capable model decides, cheap model types.

claude -p "/improve-animations" --model opus > plans.md
claude -p "Implement plan 1 from plans.md" --model sonnet

The useful rule: end-of-feature automation reports; a human invokes the passes that change code.