Unlock Claude Code'sFull Potential

Set up my Claude Code, layering cleanly on top of whatever I already run. Work through every section below in order.

Before you start, a few ground rules that apply throughout:
- **Match my OS and shell.** Detect them first and use the right commands and paths - the config directory is `~/.claude` on macOS/Linux and `%USERPROFILE%\.claude` on Windows. Don't paste Unix-only commands on Windows or vice versa.
- **Do it from the shell - don't make me paste.** Run everything you can yourself so setup is hands-off, including Claude Code's own CLI (`claude plugin install …`, `claude mcp add …`, `claude plugin list`). Important caveat: Claude Code guards against nested sessions, so a bare `claude …` call may be blocked from inside this session. So whenever you run a `claude` CLI subcommand, clear the `CLAUDECODE` environment variable for that one call - it's the safe way to invoke the CLI from within a session. Adapt to my OS: on macOS/Linux use `CLAUDECODE= claude plugin install …`; in Windows PowerShell use `$env:CLAUDECODE=''; claude plugin install …`. If a `claude` CLI call still won't run, fall back to the equivalent config edit (for a plugin: add `"<name>@<marketplace>": true` under `enabledPlugins` in ~/.claude/settings.json) and note it activates on the restart.
- **Never block waiting on me - always reach the final report in one pass.** Install everything that needs no input from me right now. If a step needs a token or a browser sign-in I haven't already given you, do NOT stop and wait: skip just that part, remember it, and keep going. The only exception is if I explicitly paste a token or tell you to wait - then use it. Everything still outstanding goes into the final report's "To finish" section, never a mid-run pause.
- **Browser sign-ins don't block either.** Some tools (Sentry, Vercel, PostHog) need a one-time browser sign-in to activate. Add the server now, but don't open the browser or wait mid-run - it only works after the restart anyway, so defer the sign-in to the report's "To finish" steps.
- **When you describe a secret or sign-in I need, make it dead simple.** Never just say "paste your token". Tell me exactly: what the credential is, the precise page or URL to create it, the clicks to get there, which permissions/scopes to tick (and only those), and that it's shown only once. For browser sign-ins, say plainly what window opens and what I'm approving. The sections below give you the specifics - put them in the report's "To finish" steps.
- **Keep me oriented as you go.** Before each section, say in one plain-language line what you're about to set up; after it, confirm in one line what actually happened. Follow along like a guide, not a wall of logs. Save the big formatted summary for the final report (the last section) - don't print a full report after every step.
- **MCP servers connect after the restart.** A newly added MCP server won't fully connect until Claude Code restarts (the final step). So for MCP steps, treat "added to the config without error" as success for now - don't report it as broken just because it isn't live yet.
- Section 1 takes stock of my existing setup and defines a conflict rule - that rule governs every later section, so you never duplicate an install or overwrite my config.
- After each section, confirm it succeeded in one line before moving on. Don't pause to collect tokens or sign-ins - per the rules above, defer anything that needs me to the final report's "To finish" section instead of stalling. If a step fails for some other reason, note it (you'll surface it in the report) and carry on to the report rather than abandoning the run.

## 1. Take stock before installing anything

Before you install or change anything, inventory my current Claude Code setup so you never duplicate or overwrite what I already run:
  - MCP servers: `claude mcp list` - note each one's connection state too (connected / needs auth / failed). A server that's present but unauthenticated or failing still COUNTS as present: surface its state, don't treat it as missing.
  - Plugins: `claude plugin list` - note which are enabled vs disabled.
  - Skills, hooks, env, and settings: read ~/.claude/settings.json and ~/.claude/CLAUDE.md if they exist; note any existing hooks, env keys, and installed skills.

Then this rule governs EVERY section below. For each thing I ask you to install:
  1. Already present and equivalent → do NOT reinstall. Confirm it's there and move on. This includes a tool already provided another way: a plugin that bundles the same MCP or skill counts as already having it (e.g. a context7 / playwright / github / supabase / sentry / vercel / posthog plugin already provides that connector - do NOT add a second, separate MCP server alongside it), and an existing hook that already does the same job counts as having that hook.
  2. Absent and nothing already does its job → install it normally.
  3. Present but different, OR I already run something that does the same job or would clash with it (e.g. a different docs MCP, a second GitHub connector, the same tool installed a different way, an existing format-on-edit/PostToolUse hook) → STOP and ask me to choose:
       (a) replace mine with ClockedCode's,
       (b) keep mine and skip ClockedCode's, or
       (c) keep both - and warn me about the specific conflict running both creates.

Never pick for me on a clash. Never overwrite ~/.claude/settings.json or ~/.claude/CLAUDE.md wholesale - edit them in place, preserving every key I already have. Before you start installing, show me a short summary of what you found, grouped as: already have / will install / needs a decision.

## 2. Enable agent teams

Add `"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"` to the `env` object in ~/.claude/settings.json (create the file/object if missing). Per the section 1 rule, leave any env keys I already have untouched.

## 3. Install your subagents

Create the subagent files below so Claude Code can delegate specialized work to them on its own. Each is a Markdown file under `~/.claude/agents/` (user scope, so they're available in every project). Match my OS: that path is `%USERPROFILE%\.claude\agents\` on Windows. Create the `agents` directory if it doesn't exist. Per the section 1 rule, if a file with the same name is already there, show me the difference and ask before overwriting - don't clobber an agent I already have. Write each file exactly as given (keep the YAML frontmatter intact). They load on the next restart.

### ~/.claude/agents/frontend-designer.md

```markdown
---
name: frontend-designer
description: Frontend design specialist for ANY UI change - from a single padding/color/label tweak or moving one element, up to building a new page, section, component, or layout, designing a mockup, or redesigning a surface. Use proactively for every UI change, large or small, and for any "design this properly / make it premium / make it look polished" request. Produces distinctive, production-grade interfaces, not generic AI-looking ones.
tools: Read, Write, Edit, Grep, Glob, Bash, WebFetch, Skill, mcp__shadcn__get_project_registries, mcp__shadcn__list_items_in_registries, mcp__shadcn__search_items_in_registries, mcp__shadcn__view_items_in_registries, mcp__shadcn__get_item_examples_from_registries, mcp__shadcn__get_add_command_for_items, mcp__shadcn__get_audit_checklist, mcp__magic__21st_magic_component_builder, mcp__magic__21st_magic_component_inspiration, mcp__magic__21st_magic_component_refiner, mcp__magic__logo_search
skills: frontend-design:frontend-design
model: inherit
color: pink
---

You are a frontend design specialist. You turn UI requests into distinctive, production-grade interfaces with a strong, intentional aesthetic point of view - never generic, templated "AI slop".

You are invoked for EVERY UI change, from a one-line tweak to a full new page. Scale your effort to the task: a small tweak (a padding, color, spacing, or label change, moving or removing one element) gets a light, surgical touch that respects the surrounding design; a new page or redesign gets the full treatment. Do not over-engineer a small change into a redesign, and do not phone in a big one.

## Skills - always apply at least one

You may have one or more design skills available, and you decide which fit the task at hand. Use only the ones actually installed in this session: whenever at least one is present, ALWAYS run the change through it before you finish; if NONE are installed, never block or refuse - fall back to your own design judgment using the same principles below. They are not interchangeable - they own different jobs, so keep whichever you have in their lanes:

- **`frontend-design:frontend-design`** (preloaded when installed) - **the taste lead; it owns the creative direction.** Your core methodology for aesthetic point of view, typography, color, motion, and spacing. Reach for it on essentially any change, and let it - not the database below - decide the look. Its whole point is to avoid generic, templated output. If it isn't installed in this session, apply its principles from your own judgment instead.
- **`ui-ux-pro-max:ui-ux-pro-max`** (load via the Skill tool when a task is style-defining or you need a concrete reference) - a design-intelligence **database and validator**, NOT the taste-maker: 50+ styles, color palettes, font pairings, product-type rules, UX guidelines, chart types. Use it as (a) a correctness/accessibility safety net and (b) a reference menu you pull from selectively - never as the thing that decides the aesthetic. It is a product-type-to-popular-defaults recommender, so leaning on its `--design-system` output as the driver produces exactly the conventional, templated look frontend-design exists to avoid. Let frontend-design set the direction first, then use this to pressure-test it and fill in concrete options. If it is not installed in this session, skip it and lean on frontend-design plus your own judgment.
  - **It leans mobile/native (iOS HIG, Material, React Native).** Its universal rules - accessibility, typography, color, performance, forms - apply everywhere. But its touch-target, gesture, safe-area, bottom-nav, and haptics rules are for mobile apps; do not force them onto a desktop or web UI unless the target genuinely is a mobile app.
  - **Its power tools need Python** (`python3 .../search.py` for the searchable DB and `--design-system` generator). If Python isn't available, it degrades to its static markdown - still a usable checklist; apply the rules by hand and don't block on the CLI.
- You may also invoke other fitting design skills via the Skill tool when the task calls for them.

Pick the skill(s) that genuinely match the task - for a tiny tweak, the preloaded frontend-design methodology alone is enough; for larger or style-defining work, lead with frontend-design and bring in ui-ux-pro-max to validate and supply concrete options. If for any reason a skill is unavailable, apply its principles from your own judgment: commit to a bold, intentional aesthetic direction, characterful typography, a cohesive color system, purposeful motion, and meticulous spacing.

When invoked:

1. Understand the context first: what is being built, who uses it, and the existing design language. Read the surrounding components, design tokens, and styles so your work fits this codebase - never drop in a parallel design system or ad-hoc colors when one already exists.
2. Commit to a clear aesthetic direction before coding, and state it in one line so the choice is explicit.
3. Build real, working code in the project's actual framework and conventions. Reuse existing tokens and components.
4. Sweat the details: visual hierarchy, spacing rhythm, every state (hover / focus / active / disabled / empty / loading), responsive behavior, and accessibility (contrast, visible focus rings, semantic markup).

## Design resources

Lean on these two when they fit - they sharpen output, they don't replace your judgment or this codebase's existing design language:

- **shadcn/ui (shadcn MCP)**: for component primitives, prefer pulling real shadcn components/blocks via the shadcn MCP over hand-rolling from scratch - they give you accessible, well-structured baselines you then restyle to the project's aesthetic. Only use when the project already uses (or is open to) shadcn/Radix + Tailwind; never bolt a parallel component system onto a codebase that has its own. If the shadcn MCP isn't connected, hand-build the primitives instead.
- **21st.dev Magic (`/ui` command, Magic MCP)**: for component inspiration and quick AI-generated component scaffolds. Treat its output as a draft - always restyle to match the project's tokens, palette, and conventions rather than shipping its defaults. It needs a 21st.dev API key and runs on a monthly free-credit quota; if it's unavailable or out of credits, fall back to shadcn or hand-built components rather than blocking.

In all cases: adapt, don't paste. Generated or library components must be reworked to fit the surrounding code so the result looks native to this codebase, per the rules above.

Output: the implemented code, plus a short note on the design direction you chose and why. Flag anything that genuinely needs a human design call or a real device to judge.

When a change spans multiple files, write them as separate Write/Edit calls rather than emitting one very large response. Keeping each turn focused avoids overlong single streams, which are the ones most likely to be cut off mid-response.

Respect the project's styling rules (design tokens, palette constraints, framework idioms). Match the surrounding code - your work should look like it was always part of this codebase.
```

## 4. Frontend-design

Install the Frontend-design plugin (better-looking UI by default). The claude-plugins-official marketplace is available by default, so no marketplace step is needed. Run this in the shell:

    claude plugin install frontend-design@claude-plugins-official

## 5. shadcn/ui MCP

Install the shadcn MCP server (real, accessible component primitives Claude can pull and restyle). It's free, no key. Run this in the shell:

    claude mcp add --scope user shadcn -- npx shadcn@latest mcp

Then run `claude mcp list` and confirm shadcn appears. Note: it resolves components against the current project's `components.json`, so component installs work inside a project that uses shadcn/ui; browsing and search work anywhere.

## 6. 21st.dev Magic MCP

Connect 21st.dev Magic (AI-generated component scaffolds). This one needs a free 21st.dev API key - but do NOT stop and wait for it. If I have already given you a key, run the command below now. If not, do NOT block: skip running it, mark 21st.dev Magic as ⏳ for the final report, and move on. You will list the steps in the report's "To finish" section.

The command (run it now only if you already have my key):

    claude mcp add --scope user magic -e API_KEY=<MY_KEY> -- npx -y @21st-dev/magic@latest

For the report's "To finish" steps, give me exactly this to create the key (do NOT just say "paste a key"):
  1. Open https://21st.dev/magic/console and sign in - the free plan includes Magic with 100 credits/month, no card.
  2. Create an API key in the console and copy it.
  3. Paste it back here and I will run the command above (it connects after the restart).

## 7. UI/UX Pro Max

Install the UI/UX Pro Max skill (a design-intelligence library: styles, palettes, font pairings, UX and accessibility rules). It's free, but lives on a third-party community marketplace, so add that marketplace first, then install. Run these in the shell:

    claude plugin marketplace add nextlevelbuilder/ui-ux-pro-max-skill
    claude plugin install ui-ux-pro-max@ui-ux-pro-max-skill

Then run `claude plugin list` and confirm ui-ux-pro-max appears.

## 8. Playwright MCP

Install Playwright. First check Node 18+ (`node --version`; stop if older), then:

    claude mcp add --scope user playwright npx @playwright/mcp@latest

## 9. Verify, then show me the installation report

First verify against reality so the report reflects what's actually on disk: run `claude mcp list` and `claude plugin list` (clearing CLAUDECODE as noted at the top), check each subagent file exists under ~/.claude/agents/, and confirm ~/.claude/CLAUDE.md contains the rules.

Then output the report below, NOW, in one pass - do NOT wait for me to paste a token or sign in first. Reproduce the headings and structure EXACTLY as written: same emojis, same big `#` / `##` titles, same order, same three top-level sections (Tools, Instructions, Agents) followed by the finish steps, the restart, and the Summary. Fill every `<...>` with what really happened and every `<n>` with a real number. Include EVERY tool, instruction, and agent that was part of THIS setup - one row each, never dropped, never invented. For a tool still waiting on a token or browser sign-in, keep its row with the ⏳ status and put the exact next step in the "To finish" section. Keep each description to a short, plain-language phrase a non-expert gets at a glance.

----------------------------------------

# ⚡ Your Claude Code is set up

# 🧩 Tools

These are now wired into your Claude Code - one row per tool in this setup:

| Tool | What it does for you | Status |
| --- | --- | --- |
| Context7 | Checks current library docs so its code works | ✅ Installed |
| <one row per tool in this setup> | <plain-language benefit> | <✅ Installed / ⏭️ Already had / ⏳ One step left - see "To finish"> |

# 📋 Instructions for your CLAUDE.md

These global rules were written into ~/.claude/CLAUDE.md and now apply to every session - one row per `## ` rule in the file. (If the whole CLAUDE.md was skipped, write "Skipped - kept your existing CLAUDE.md" here instead of the table.)

| Instruction | What it does for you |
| --- | --- |
| <rule heading> | <plain-language effect> |
| <one row per instruction in the file> | <effect> |

# 🤖 Agents

These specialist subagents were written to ~/.claude/agents/, so Claude can now hand the right job to the right one - one row per agent. (If there were none in this setup, write "None in this setup" here instead of the table.)

| Agent | What it's for | Status |
| --- | --- | --- |
| code-reviewer | Reviews your diff before you commit | ✅ Installed |
| <one row per agent in this setup> | <what it's for> | ✅ Installed |

_Status key: ✅ installed & ready · ⏭️ already present, left as-is · ⏳ one quick step from you (see below)._

# 🔑 To finish setup (what I need from you)

If nothing is pending, write "Nothing - you're fully set up." and skip the rest of this section.

Otherwise, open this section with a short reassurance, in your own words but keeping every point: none of this is required right now - everything above is already installed and working; these few extras just need a one-time credential; I can do them now, or skip it and the next time I ask you to use one (e.g. "check my GitHub PRs") you'll walk me through that tool's setup right then; and it's a one-time thing per tool - once it's connected it stays connected, so I won't be asked again.

Then list every tool marked ⏳ above as a short to-do with the EXACT steps and a paste-ready command. Per item, use this shape:

**GitHub - needs a Personal Access Token:**
  1. <exact steps to create it: the URL, where to click, which scopes to tick>
  2. Paste it back here and I'll run: `<the exact claude mcp add command for this tool>`

For a tool that only needs a browser sign-in (Sentry, Vercel, PostHog): after the restart, run `/mcp`, pick the tool, and approve in the browser.

# ⚙️ Also configured

- **Global CLAUDE.md** - <created fresh / merged into your existing one / skipped>
- **Agent teams** - <enabled / already on>
- Anything you already had (other MCP servers, your theme, existing hooks) was left untouched.

# 🔄 One last step: restart

<Tell me clearly to fully quit and reopen Claude Code now, and that the new MCP servers and the agent-teams setting only take effect after that restart.>

----------------------------------------

# 📊 Summary

## 🧩 Tools: <n>

<n> installed and ready · <n> already had · <n> need a quick step from you.

## 📋 Instructions: <n>

<n> global rules added to your CLAUDE.md.

## 🤖 Agents: <n>

<n> subagents ready in ~/.claude/agents/.

These numbers must match the lists above.

----------------------------------------