The complete kitstarter reference.

/start

Ask-first kickoff. No code until there is an approved plan and a CLAUDE.md.

Used at the very start of any new app, feature, or change, before a single line of code. It interrogates you with clarifying questions until the goal is genuinely clear, then writes a short plan and a CLAUDE.md source-of-truth and gets your approval. The hard rule: no code in this skill. It ends with an approved plan and a written CLAUDE.md, nothing built.

Beginning anything new, or any time you catch yourself about to just start coding. Triggers include /start, "brainstorm", "help me think through this", "plan this", "new project", "let's build", and "I want to make".

• Looks before it asks: reads any existing CLAUDE.md, glances at the project, and says what it sees in one sentence.
• Interrogates one question at a time, each with a recommended default, covering: what it is, who it is for and what they do with it, what done looks like, what is in and out of scope, the stack and where it runs, and the tricky or sensitive parts. It pushes past vague answers.
• Reflects the goal back in plain English and waits for a yes.
• Writes the plan as small, individually checkable steps and gets an explicit go.
• Writes CLAUDE.md from the kit template: what, who, done, stack, scope, and the kitstarter rules.
• Hands off: build one step at a time, prove each one, review the diff.

You say "I want to build a tip-splitting app." Instead of scaffolding a guess, it asks one question at a time until the goal is concrete, then plans it.

An approved step-by-step plan and a written CLAUDE.md in the project root, the file every future session reads first.

/tour

The first-run setup wizard. It onboards you by asking, not by lecturing.

Run it right after installing, or anytime, to get set up. It welcomes you in one line, then asks six questions one at a time, each with a recommended default, to understand your project. There is no feature tour and no list of skills: the asking is the demo, so you feel how the whole tool works.

Right after install, or whenever you want to get oriented. Triggers include /tour, "getting started", "set me up", "how do I start", and "onboard me".

• One line of welcome, then questions one at a time, each with a default.
• Asks: what you are building, who it is for, how much you already know (which sets how much it explains versus assumes), what the first useful version looks like, what is tripping you up most, and how much time a day you have.
• Lets each answer steer the next question, and pushes past a vague answer once.
• Closes the loop: reflects your project back in plain English, fixes anything you correct, then offers the next move: "Want me to run /start?"

Fresh from install, you run /tour. It asks "What are you building?" and proceeds one question at a time until it could restate your project with no gaps.

A shared, gap-free understanding of your project and a natural handoff into /start. It does not write a file.

/step

Build one step of the plan, prove it, checkpoint it, then stop.

After /start has produced an approved plan and a CLAUDE.md, this builds exactly one step at a time, the laziest way that works. It stays safe around destructive commands, hands off to /check for proof, then commits the working step as your undo button. One step, prove it, save it, repeat.

After /start, to actually build. Triggers include /step, "next step", "build the next part", "let's do the next one", and "keep going".

• Reads CLAUDE.md first. If there is no plan, it stops and tells you to run /start. Then it finds the next single step.
• Names the step and what done looks like for that step only.
• Builds just that step using the reuse ladder, stopping at the first rung that holds: does it need to exist, is it already in the project, does the language or standard library do it, is there a native platform feature, does an existing dependency solve it, can it be one line. Only then writes minimal code.
• Stays safe: never runs a destructive command without asking and explaining it in plain English.
• Hands off to /check for proof instead of claiming done itself.
• Once confirmed working, commits with a clear message ("add login form", not "update"). Never commits on top of broken code.

You say "next step." It builds just the login form, the minimal version, then tells you to run /check before saving.

One small, working, committed change: a checkpoint you can always roll back to.

/check

Prove a change works with real evidence. "Should work" is banned.

It actually runs, opens, or clicks the thing and reports what it saw, with its own eyes or the browser's, not what the code should do. It tests the real user action, not just that the code compiles, and it checks the edges too.

After /step, or whenever you want proof a change is real. Triggers include /check, "does it work", "verify this", "is it done", and "test it".

• Picks the real test: the actual thing the change does for the user. A page gets opened and clicked; a script gets run with real input; a data change gets queried back.
• Shows the evidence concretely: what it did and what it saw, not "it should handle that now".
• Checks the edges, not just the happy path: empty input, the wrong password, a slow network, a long name.
• If it is a screen, it also runs /design-check so it does not just work but does not look AI-made either.
• If it is broken, it hands to /fix rather than patching here.
• If it passes, it says so plainly and clears you to checkpoint.

"Opened the page, typed an email, hit submit, saw the success message and the new row in the database. Empty email shows the validation error."

A plain pass or fail report backed by the evidence of what was actually observed, with a clear next move.

/fix

Find the real cause before changing anything. No whacking moles.

It breaks the patch-on-patch cycle. No change until it can say, in one sentence, why it is breaking. One change per hypothesis, then it proves the fix. A pile of "let me try this" is exactly what turns a small bug into a tangle.

Anything broken or behaving wrong. Triggers include /fix, "it's broken", "this isn't working", "there's a bug", "error", or pasting an error message.

• Reproduces the bug on purpose and notes the exact steps. If it cannot reproduce it, it cannot know it fixed it.
• Finds the real cause: reads the whole error, traces back to where it actually goes wrong, and states the cause in plain English.
• Makes one change for one hypothesis, not five things at once.
• Proves the fix through /check: reproduces the original steps, confirms it is gone, and confirms nothing nearby broke.
• The 3-strikes rule: after three real failed attempts, it stops and questions the approach itself rather than patching again.
• Saves it: checkpoints once fixed and checked.

A page errors on load. Instead of a try-this loop, it traces to "the data has not loaded yet when it tries to render," changes that one thing, and re-checks.

A one-line root cause, a single clean change, and a verified, committed fix.

/review

Fresh eyes on the actual diff, against the actual goal, before you accept it.

The AI wrote it, so the AI is the worst judge of it. This is the second pair of eyes you do not have. It reads what actually changed, the real diff and not a summary, holds it against the goal in CLAUDE.md, and catches what is risky, half-done, or off-scope before it lands.

Before you accept, merge, or commit a batch of work. Triggers include /review, "is this good", "should I accept this", and "look this over".

• Gets the diff, the real edits, because summaries hide bugs and diffs do not.
• Holds it against the goal: opens CLAUDE.md and the step's goal, and asks whether the change does that, all of it, and only it.
• Runs the checklist: does it do the job; anything risky (secrets or keys in code, plain-text passwords, deletable data, anything a stranger could abuse) flagged first and loudest; anything half-done (an erroring path, a left-in TODO, a silent failure); did it sneak in scope.
• Sorts findings into must-fix (bugs, risks, half-done) and later (style, polish). Fixes the must-fixes now and surfaces judgment calls instead of deciding silently.
• Hands the decision back: you recommend, the user accepts. It never rubber-stamps.

It catches "this stores the password in plain text, line 14, that has to change" before you merge, rather than saying "looks great!"

A prioritized review, must-fix versus later, with must-fixes fixed and any judgment calls surfaced for your decision.

/lean

Cut AI code slop: the over-building, boilerplate, and 50 lines where 1 would do. Deletion over addition.

The code-side twin of /polish. AI does not just make UIs look generated, it makes code read generated: it wraps a native input in a component, writes an interface for one implementation, adds a dependency for a one-liner. This finds that over-building and cuts it by the root cause, after it understands the flow.

When code feels over-built. Triggers include /lean, "this is over-built", "too much code", "simplify this", "did the AI over-engineer this", and "yagni".

• Understands first: reads the code end to end before removing anything. Lazy about the solution, never about understanding.
• Cuts down the reuse ladder in reverse: speculative work gets deleted; a one-use abstraction gets inlined; "for later" scaffolding gets dropped; a dependency doing a few lines' work gets removed; fifty lines become one; clever becomes boring.
• Lists each over-build with the leaner version beside it, and cuts by the root cause: one guard in the shared function beats a guard in every caller.
• Never simplifies away input validation at trust boundaries, error handling that prevents data loss, security, accessibility basics, or anything you explicitly asked for.
• Proves it still works with /check. Less code that is broken is not lean, it is broken.

"This 40-line cache class becomes one line of lru_cache."

A smaller diff that does the same thing, re-checked to confirm it still works, with a line or two on what was cut and when to add it back.

/ks-loop

Grind a stubborn build-run-fix cycle to working code. Smallest change, run it for real, read the actual output, fix, repeat.

The number one way AI wrecks a project is the one giant guess: a big change, an assumption that it works, and a "done." This runs the opposite. A tight loop of smallest change, run it for real, read what actually happened, fix the real cause, and checkpoint the moment it is green, repeated until the thing genuinely works.

A feature that needs several passes, a stubborn bug, or getting a broken thing or failing tests to pass. Triggers include /ks-loop, "loop on this", "keep going until it works", "get this passing", and "grind this out".

• Smallest next change that moves toward working, not a rewrite.
• Runs it for real and captures the actual output or error. Never assumes it passed.
• Reads what actually happened and diagnoses the real cause, not a guessed one.
• Makes the smallest fix for that cause.
• Checkpoints the moment a step works, so the next loop has an undo button.
• The stop rule: after about three failed attempts at the same thing, it stops, re-reads the goal, and forms a different hypothesis instead of thrashing.

Tests are red. It changes one thing, runs the suite, reads the real failure, fixes the actual cause, re-runs, and commits the moment they go green.

Working code you have watched work, committed, with one line per meaningful loop instead of a wall of every attempt.

/ks-iterate

Improve something that already works, in small reversible passes, without breaking it.

Something already works and you want it better: cleaner, more robust, nicer. The trap is the big rewrite that breaks the thing that worked. This improves in small, reversible passes instead, each one keeping it working.

Refining a design, handling edge cases, tightening code, or polishing something that already runs. Triggers include /ks-iterate, "make this better", "next iteration", "harden it", and "another pass".

• Names the goal of this pass in one sentence: what is better after it.
• Breaks the improvement into small moves it can verify one at a time.
• Makes one change, then confirms it still works and is actually better, before the next.
• Checkpoints each good pass, so the next is safe to try.
• Prefers deleting and simplifying over adding, and reverts a pass that makes it worse.

A working form. One pass adds empty-state handling, verified and committed; the next tightens the spacing, verified and committed.

A still-working, measurably better version, committed pass by pass.

/ship

Get the project live on the internet, set production env vars, and prove the URL actually works.

Putting their thing on the internet is the moment a vibe coder waits for, and the one they most often cannot do alone. This deploys the project, sets production environment variables on the host, and hands back a working URL. It runs /secrets first as a safety gate, and it proves the live site works rather than trusting "deployed".

When you are ready to go live. Triggers include /ship, "deploy", "put it online", "make it live", "go live", and "host it".

• Asks first: where it should live (default Vercel for React or Next, Netlify for a static site), whether it is in git and pushed to GitHub, and what it needs to run in production (keys, database URLs, any .env values).
• Safety gate: runs /secrets first, so it never ships a leaked key or a committed .env.
• Commits and pushes the working state to GitHub, since deploys come from there.
• Connects the repo to the host and lets it auto-detect the framework.
• Sets the production env vars on the host, the number one reason a deploy works locally but breaks live.
• Deploys, gets the URL, then proves it is live: opens the URL and does the real action. A blank page or a 500 is almost always a missing env var or a build error, so it reads the deploy log.

You say "deploy this." It runs /secrets, pushes to GitHub, imports the repo to Vercel, sets the env vars, then opens the live URL and confirms the form submits.

A live, verified URL: "It's live at X. I opened it and Y works."

/secrets

The pre-public safety check for leaked keys, exposed .env files, and the obvious security holes.

The fastest way a vibe coder gets burned is a real API key in a public repo, a committed .env, or a secret key shipped in the frontend. Public is forever, so this runs before anything goes public, and before /ship. It scans the code and the git history, reports worst-first, and gives the fix for each.

Before going public or deploying. Triggers include /secrets, "is this safe to ship", "did I leak a key", "security check", and right before /ship.

• Asks first: is this about to go public or deploy, and what does it handle (logins, payments, user data all raise the bar).
• Scans for leaked secrets in code, grepping the usual shapes (sk-, AKIA, AIza, ghp_, xox, -----BEGIN, password =, secret =).
• Checks git history too, not just current files: a key you deleted still lives in old commits.
• Checks .env exposure (is it gitignored, was it ever committed, is .env.example clean), secrets in frontend or client code that ship to every visitor, plain-text passwords, and wide-open routes (no auth, raw input into SQL or shell, CORS set to * on something private).
• Ranks the findings with a one-line fix each. If a key was ever public or committed, it tells you to rotate it, since deletion does not un-leak it.
• Green-lights only when the real risks are handled, then hands to /ship.

It finds a service key in client-side React and tells you to move it server-side and rotate it before going live.

A ranked risk report with fixes, and a clear green light (or not) before /ship.

/recover

Calmly get back to a working state when git is scary, with the least destructive move that works.

The worst moment: it was working, now it is not, and you are scared to touch git in case you make it worse. This stays calm, finds the last good state, and gets there with the gentlest move. It reassures first and acts carefully, because panic-deleting is what actually loses work.

After something broke badly, work seems lost, or a merge went wrong. Triggers include /recover, "I broke everything", "I lost my work", "undo this", "git is broken", "merge conflict", and "get me back to when it worked".

• Asks one or two quick questions: what happened, and when it last worked.
• Stops making it worse, then looks at where things stand with git status, git log --oneline -10, and git reflog (the safety net that remembers even "lost" states), explained in plain English.
• Picks the gentlest fix: git restore or git stash for messy uncommitted changes; git revert over git reset --hard for a bad commit; git reflog to recover a vanished commit; a file-by-file walkthrough or git merge --abort for a conflict.
• Confirms before anything destructive, explaining exactly what would be lost.
• Lands on a working state, then checkpoints it so this exact moment is safe.

"I lost my last commit." It checks git reflog, finds the state, and gets you back to it, no work thrown away.

A restored working state, committed so the recovered moment is locked in.

/explain

A plain-English readout of what the AI actually built: the shape and the parts that matter, never line-by-line.

A vibe coder ships code they cannot read, then freezes in a review or cannot debug it. This makes you understand it, not by reading every line, but by seeing the shape and the parts that matter, the needle and not the haystack, with jargon defined inline.

When you do not understand the code. Triggers include /explain, "what does this do", "walk me through this", "I don't get this code", and "explain what the AI just wrote".

• Asks first: what to explain (this file, this feature, the whole project, this error) and your level, so it pitches it right.
• Reads the actual code instead of guessing from the filename.
• Gives the shape first: in two or three sentences, what it does and how the pieces fit, what calls what. The map before the streets.
• Speaks plain English and defines jargon inline the first time (a "prop" is just a value you hand a component).
• Points at the parts that matter, the few lines doing the real work and anything risky or surprising, and skips the boilerplate.
• Never narrates line-by-line for anything big; it traces one real path end to end, adds a small analogy if it helps, and checks it landed.

"Explain the auth flow." You get the map (login, then a token, then the protected route) and the two or three lines that actually matter, not a wall of text.

A plain-English mental model of the code and where it could bite, so you could say in your own words what it does.

/design-intake

Decide the look on purpose and write DESIGN.md, before designing anything.

The reason vibe-coded apps look AI-made is that nobody decided how they should look, so the AI reached for its defaults (Inter, a violet gradient, a grid of cards). This is the design twin of /start: it interviews you, then writes a DESIGN.md source-of-truth so every screen after it has a spine.

Before you build UI without a DESIGN.md. Triggers include /design-intake, "set up the design", "what should it look like", and "design system".

• Interviews rather than confirms: 2 to 3 real questions per round, waiting for real answers, never generating a design from the original prompt alone.
• Round 1, what this is: a brand surface (where the design is the pitch) or a product surface (where it gets out of the way), who uses it and to do what, and what they should feel.
• Round 2, the taste: three personality words, named references and anti-references ("not generic SaaS" is the most useful answer), and accessibility or brand constraints.
• Round 3, the tokens, each with a recommendation: a color strategy and anchor hue, a type direction that rejects the reflex picks (Inter, Geist, Roboto), and motion energy (default subtle).
• Writes DESIGN.md from the template: the tokens, the Creative North Star (a one-line metaphor for the feel), the anti-references verbatim, and the Named Rules. Scan mode reads existing colors and fonts first; seed mode marks guesses with <!-- SEED -->. It never overwrites an existing DESIGN.md without asking.

It asks "is this a brand page or a product app?" and pushes for named anti-references, so the result has a deliberate look instead of the default one.

A DESIGN.md you could hand to anyone and get a consistent, non-generic result.

/design-check

An honest, independent design review. Does it look intentional, or AI-made? It reports, it does not edit.

The design reviewer a solo builder does not have. It looks at a real screenshot, pulls intent from DESIGN.md, runs the slop detector plus a holistic look, scores the screen, tags every issue, and names the top fixes. Independence is the whole value, so it reports only; editing is /polish.

After building any screen. Triggers include /design-check, "does this look good", "does it look AI-made", "review the design", and "check the UI".

• Gets a real screenshot, captured at three widths (390 phone, 768 tablet, 1440 desktop) if it can drive a browser, otherwise asks you to paste one. It reviews pixels, not code.
• Pulls the intent and anti-references from DESIGN.md. If there is none, it says so and suggests /design-intake.
• Runs two passes: the slop scan (node bin/detect-slop.mjs <path>, which flags the measurable tells with file:line and exits 1 on any P1) plus the catalog tells a script cannot catch; and the holistic look (the squint test, body contrast at least 4.5:1, rhythmic spacing), optionally sharpened through gemini-vision.
• Scores it honestly out of 40 across hierarchy, type, color, spacing, restraint, and polish. Most real UIs land 20 to 32, and it does not inflate.
• Tags each issue P0 to P3 and lists the top 3 highest-impact fixes, concrete.
• Respects intent: a deliberate, DESIGN.md-confirmed choice is skipped, with a reason.

"The body text is gray on cream, that is 3.1:1, it fails and it reads as AI-default, here is the fix."

An honest 0 to 40 score, P0 to P3 tagged issues, and the top 3 fixes, ending with "Want me to fix these? Run /polish."

/polish

Fix the things that make a screen look AI-made, from DESIGN.md and the detector, by the root cause not by decoration.

/design-check found what is wrong; this fixes it the right way. The trap is decorating a screen that is actually just missing a design system, so it fixes causes, not symptoms, and reaches the result by subtraction more than addition.

After /design-check finds issues. Triggers include /polish, "make it look better", "fix the design", and "make it not look AI-made".

• Before touching a pixel: reads DESIGN.md (and runs /design-intake first if there is none), and does not polish a feature that does not work yet (/check it first).
• Classifies each issue as a missing token (add it to DESIGN.md, then use it), a one-off deviation (snap it back to the token), or a conceptual misalignment (rework it toward the North Star). Fixing the root is what stops the slop coming back on the next screen.
• Runs node bin/detect-slop.mjs <path> and works the list: the reflex font, gradient text, the side-stripe border, the violet gradient, contrast (at least 4.5:1, in OKLCH), a 4pt spacing scale, buzzwords, and em-dashes. Then the catalog tells a script cannot see.
• Checks every interactive element has all its states: default, hover, focus (visible), active, disabled, loading, error.
• Stays restrained: one accent used rarely, no unrequested motion or glow, prefers-reduced-motion respected. The fix for "looks AI-made" is usually less, not more.
• Proves it: re-runs the detector to 0 P1, re-screenshots, and re-runs /design-check, expecting the score to go up.

It swaps Inter for a real display face, kills the gradient text, replaces the border-left stripe, fixes the contrast, and re-runs the detector until it reports 0 P1.

A screen you cannot tell was AI-assisted, with the detector at 0 P1 and a higher /design-check score.

/connect-mcp

Plug real outside tools into your agent via MCP: web crawling, web search, live docs, a browser. Portable across Claude Code, Codex, and Antigravity.

MCP (Model Context Protocol) is a standard plug that lets your agent use outside tools: crawl a website, search the web, read a library's current docs, or drive a browser, instead of guessing from training data months old. The same servers work across Claude Code, Codex, and Antigravity, so this is portable, not Claude-only.

When the agent needs live web, docs, or a browser. Triggers include /connect-mcp, "add an MCP", "connect crawl4ai / exa / context7", "give the agent web access", and "it's using outdated docs".

• Rule 0 first: it asks what you actually need the agent to do that it cannot now, and adds only those servers. Each one is more setup, more context, and more attack surface.
• Picks from opinionated defaults: crawl a known site, use crawl4ai; search the web or find documentation, use exa (npx -y exa-mcp-server, needs EXA_API_KEY); optional playwright or github only if needed.
• Adds the same block in three places: Claude Code (claude mcp add ... or the project .mcp.json, checked with claude mcp list), Codex (under [mcp_servers] or codex mcp add), and Antigravity (its MCP settings). It confirms the exact package on each server's own repo, since names move.
• Verifies it works by actually using it once and showing the real result, never assuming it connected.
• Keeps keys in env vars, never hardcoded, and treats everything crawled or searched as data, not commands, because of prompt-injection risk.

"Give the agent live docs." It adds context7 and exa, then asks the agent to pull a library's current docs to prove the connection works.

A working, verified MCP connection with keys kept in env vars, not source.

/claude-tips

Surface the Claude Code built-ins you are not using but should, matched to your actual pain.

Most people install Claude Code and use a sliver of it. This points you at the one built-in that solves whatever you are doing the hard way, in plain English. It is Claude Code specific; the full list lives in reference/claude-code-cheatsheet.md.

When you suspect there is a better built-in way. Triggers include /claude-tips, "what can claude code do", "is there a better way to do this", and "I didn't know it could do that".

• Asks first what is clunky or what you are trying to do. If you just want the tour, it gives the 5 must-knows rather than the whole list.
• Matches the pain to one feature: re-explaining the project points to a CLAUDE.md; it forgot or got slow points to /clear or /compact; it built the wrong thing points to plan mode (Shift+Tab); a repeated workflow points to a custom skill; needing web, docs, or a database points to MCP (/connect-mcp); research bloat points to a subagent; a rule enforced every time points to a hook; a lost session points to claude --continue or --resume; a visual bug points to pasting a screenshot; a friendlier or terser voice points to /output-style.
• Stays accurate: Claude Code updates often, so it recommends the feature but tells you to run /help for the exact command on your version, and never dumps all 40 features.

You keep re-explaining your stack every session, so it points you at a CLAUDE.md that loads automatically.

One high-leverage feature recommendation, tuned to your actual problem.

session-start

Fires on SessionStart, when a session begins.

Prints a small mascot and a one-line reminder of the kitstarter rules, plus the quick pointers (new thing goes to /start, new screen to /design-intake, how it works to /tour). If the mascot art is missing it just prints the text line. It is the one hook in the core.

slop-check

Fires on PostToolUse (matcher Edit or Write), after the agent edits a UI file.

When the agent edits or writes a UI file (.css, .scss, .sass, .less, .html, .htm, .tsx, .jsx, .vue, .svelte, .astro), it runs the slop detector on just that file and, if it finds tells, surfaces a concise "[anti-slop] possible AI-slop tells, run /polish to fix" note as context for the agent. On a clean file or any error it stays quiet, and it never blocks the edit. This is what makes the design get checked automatically, not only on demand.

safety-guard

Fires on PreToolUse (matcher Bash), before a destructive command runs.

It matches the command against destructive patterns: a recursive delete of a root or home path, a recursive delete with a wildcard, a force-push, git reset --hard, git clean -f, dropping or truncating a database object, and disk-level operations like mkfs or dd. If it matches, it prints a plain-English warning and a reminder to commit a checkpoint first. It warns, it never blocks: a kit that hard-blocks your commands gets uninstalled. The point is "did you mean this, and did you checkpoint first?"

stop-reminder

Fires on Stop, when the agent wraps up.

A single light line so "done" means proven, not promised: did you /check it actually runs, and /review the diff against the goal? One line, no noise.

Teaching

A warm mentor who explains as it goes and checks you understand. Still asks first.

It explains in plain English, defines a technical term the first time it uses it (a "cookie" is a little note the browser keeps so the site remembers you), says in a sentence or two what it is about to do and why before a non-trivial change, and ends with a quick "make sense?" It teaches the why, not just the code, in small clear beats rather than essays. It stays straight about real problems.

Buddy

A relaxed, friendly peer who codes with you. Casual tone, still asks first.

It talks like a teammate leaning over your shoulder: contractions, plain words, the occasional bit of humor. It calls small wins ("nice, that works") and is honest when something is off ("yeah that'll break, here's why"), with no fake-cheery or flattering filler, and it keeps it short.