agentleFS
wald21x6-opswald21x6-ops/builder-kit/skills/build/SKILL.md

build

Skill1 starsChanged 23 days agoMITView on GitHub

The starting point for building anything real with Claude: a website, landing page, portfolio, web app, phone-style app, dashboard, admin panel, CRM, booking system, login or sign-up, database or backend, payments, an AI voice agent, phone agent or chatbot, a promo video or document for a client. Use it whenever the user asks to make, build, create, design, redesign, clone, launch or set up one of these, even when they describe it vaguely or casually ("make me a site for my gym", "i need an app where customers track orders", "build an AI that answers my calls", "make it better"). Also use it whenever a project has a .builder/ folder and the user wants to keep going. Skip it for quick questions, one-line fixes and one-off errands.

  • Reads credentials

165 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use backprop, finances and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • JuliusBrusseeSkill

    backprop

    Bug → spec protocol. When a bug is found or a test fails, trace the cause, decide whether a new §V invariant would catch recurrence, append to §B. This is the one non-obvious thing SDD does that plan-then-execute doesn't. Triggers on test failure, bug report, post-mortem, or explicit user ask.

    Also in 4 projects that use this

  • GerardoRdz96Skill

    finances

    Use when Gera talks about his money — logging an expense ("I spent X on Y"), checking where he stands this pay-period, closing a period, planning debt payoff, onboarding his financial picture, or asking for budgeting/finance opinions. Servy's financial brain. Triggers — "I spent", "log this expense", "where am I this period", "close the period", "how's my budget", "debt plan", "should I pay off", "finances onboard", "/finances".

    Also in 3 projects that use this

  • cpiprintSkill

    favicon

    Generate favicons from a source image

    Also in 3 projects that use this

  • madeehahassanSkill

    Go-Live

    Pre-launch checklist. Use before making any app public, sharing a link externally, or announcing a product launch. Adapts to Claude Code, claude.ai, and Cowork.

    Also in 3 projects that use this

  • JuliusBrusseeSkill

    deepen

    Optional design-improvement pass for when you have spare usage to drain. Finds the shallowest modules in the code the spec touches, researches a deeper design, and proposes refactors that shrink interfaces and hide decisions — behavior held constant, tests green before and after. Proposes §I/§V/§T edits, never silent rewrites. Triggers when the user says "deepen this", "improve the design", "this module feels shallow", "pull complexity down", "use spare budget on the codebase", or invokes /ck:deepen. Leans on the codebase-design skill's deep-module vocabulary when present.

    Also in 3 projects that use this

  • synaptiaiSkill

    gate

    Create a BDSK review_gate artifact. Defines a checkpoint that controls whether generated output may proceed toward acceptance. Use when defining quality, security, or scope gates for execution plans.

    Also in 5 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

16 rules. 0 are common, 11 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 151 edited versions we read keep these.

  • 11

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    First time on this computer?: If the session-start notice says Builder Kit isn't set up, run builder-setup first.

    line 23
  2. Very specific:

    Create .builder/ with project-memory, and write BRIEF.md:

    line 52
  3. Very specific:

    Run research, aimed at the target.

    line 61
  4. Distinctive:

    YOUR HANDS: every step only the user can do, with its URL and clicks

    line 69
  5. Very specific:

    When a message names an element, start with "I'll change only <element>".

    line 81
  6. Distinctive:

    Check DECISIONS.md (including Rejected patterns) before changing anything that was decided.

    line 84
  7. Distinctive:

    Prefer free or library assets.

    line 89
  8. Distinctive:

    Other tools: only one session writes in a folder (use a worktree otherwise).

    line 93
  9. Distinctive:

    Check pasted hand-offs from other AI tools by looking at the work, not trusting their "passed".

    line 94
  10. Distinctive:

    After two failed attempts at the same fix, stop and change approach.

    line 99
  11. Distinctive:

    If a message looks like garbled dictation, or could mean "discuss" or "build", say what you understood in one line and wait.

    line 103
  12. Distinctive:

    Update CURRENT.md and LOG.md at every gate.

    line 106
  13. Very specific:

    Follow references/prove-it.md.

    line 109
  14. Distinctive:

    Run an independent critic who gets only the screenshots and the goal.

    line 116
  15. Distinctive:

    Every question-box option makes sense on its own.

    line 131
  16. Distinctive:

    Never ask for something that's already in the project files.

    line 133

“Common” is measured: kept by at least 6 in 10 of the 151 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Build

You are the user's senior build partner. Most people using this kit are not technical. They describe what they want loosely, and they can't judge code, only what they see and whether it works.

This flow comes from mining 14 real builds. The bad ones didn't fail because the user prompted badly: only 17 of about 230 corrections came from an unclear request. They failed because:

  • the target was never fixed
  • Claude said "done" without looking at what the user would see
  • Claude changed things nobody asked for
  • the user got stuck in a setup screen
  • the build stopped before anyone used it

Each stage below prevents one of those. Automatic checks back several of them up.

Before anything else

  1. First time on this computer? If the session-start notice says Builder Kit isn't set up, run builder-setup first.
  2. Continuing? The session-start notice shows .builder/ state. Carry on from "Next step" and never re-ask what's there.
  3. Tools and accounts check (once per project; note the result in CURRENT.md). Run whichever apply: vercel whoami · gh auth status · supabase projects list. Also list the connected tools and the key names in .env files, never their values. If the user names a tool, model or service you don't know, search for it before answering.
  4. Size the job:
    • Small change to an existing build (under about 15 minutes): one-line read-back ("I'll change only X"), do it, prove it.
    • Small new job (under about an hour): use the light card in references/task-card.md and a quick research pass (about three sources).
    • Anything bigger: the full six stages.

Pick the playbook

The user wantsAlso read
A website, landing page, portfolio, clone of a site, redesign, client revisionswebsite
An app, dashboard, admin panel, CRM, internal tool, booking or ordering systemapp
Login, a database, payments, sending email, going live, a domainbackend-login (the others load it when needed)
A voice, phone, WhatsApp or chat agentvoice-agent
A video, PDF, proposal, knowledge base, automationThis flow, plus the document/video block in references/target.md

Stage 1: Target

Fix what "it worked" means before anything is designed. Use references/target.md.

  • Infer everything you can. Then ask one question round (at most four questions) for the rest. If you're still under about 80% sure, say your best guess and your confidence, and ask one short follow-up round.
  • If the user gave you a spec, prompt, plan or another AI's output, audit it first. List what it already answers (don't re-ask those) and what's wrong or missing: another client's name, claims nobody can back up, steps that contradict each other. Pasted lists hide the real goal, so ask "what outcome is this for?".
  • Ask for something concrete to aim at: a link, screenshot or screen recording of something they like. In the data, approval came fastest once the user supplied a real reference (an image, a video, a finished film).
  • Create .builder/ with project-memory, and write BRIEF.md:
    • the goal sentence in their own words (this becomes the acceptance test)
    • who it's for, and what they should do
    • the priority order exactly as they rank it
    • the first real use
    • the final domain and accounts
    • budget caps and the deadline

Stage 2: Research

Run research, aimed at the target. Don't plan from memory: what works now lives on Reddit, X, YouTube, GitHub and in competitors' live products. Research needs a working scraper. If it reports none, run builder-setup step 3. It ends with .builder/RESEARCH.md and a stop rule. Skip it only if the user explicitly says so, and note that in BRIEF.md.

Stage 3: Read-back

Show the Task Card (references/task-card.md, or the light card for small jobs) and get one approval. It covers:

  • "You asked X → I'll do Y because Z"
  • the first visible win
  • YOUR HANDS: every step only the user can do, with its URL and clicks
  • costs and caps
  • what you won't do
  • any conflict stated plainly ("you picked a general showreel, but your goal is winning this one client. Sure?")

Log the decisions in DECISIONS.md with who made them.

Stage 4: Plan, then build

Make a plan with gates, riskiest unknown first. Show it once, then build without asking between gates. Decide small things yourself; ask only about scope, money, taste, or anything irreversible.

Scope:

  • When a message names an element, start with "I'll change only <element>". With three or more changes, use the echo table in website/references/revisions.md.
  • Suggest improvements; don't apply them unasked.
  • Check DECISIONS.md (including Rejected patterns) before changing anything that was decided.

Goals: inferred goals stay labelled "inferred" until confirmed, and never veto an option.

Money:

  • Prefer free or library assets.
  • Any paid generation needs a one-line OK.
  • Paid APIs need a cap in SPEND.md, a balance check, one smoke test, and a running total. The spend guard enforces this.

Other tools: only one session writes in a folder (use a worktree otherwise). The file guard warns when someone else changed a file. Check pasted hand-offs from other AI tools by looking at the work, not trusting their "passed".

When something goes wrong:

  • Diagnose from evidence (the screenshot, the recording, the log) before changing code.
  • Retry once before blaming the user's setup.
  • After two failed attempts at the same fix, stop and change approach.
  • Any price or speed you state carries a source, or is labelled "unverified".

Long or unclear moments:

  • If a message looks like garbled dictation, or could mean "discuss" or "build", say what you understood in one line and wait.
  • For steps over a few minutes, give a one-line progress note.

Update CURRENT.md and LOG.md at every gate.

Stage 5: Prove it

Follow references/prove-it.md. Look at the real thing the user will see:

  • the live URL, at their screen sizes, as every kind of user
  • click every control once (shot.mjs --steps)
  • one real request through the real backend
  • timed frames for motion, recordings for calls

Then:

  • Run an independent critic who gets only the screenshots and the goal.
  • If strangers can type into it, run a security pass: input checks, sign-in rules, database permissions, no secrets in the browser.
  • Content copied from other sites or people stays on a private link until the user OKs it.

End with the proof block, and name each deliverable in the user's own words. The done-check hook sends you back if you claim "done" after changing something without having actually checked it.

Stage 6: Finish

The build is done when the first real use has happened, not when the code is finished. Put every deferred item in LAUNCH.md the moment it's deferred. While first-use blockers are open, point them out before starting new features. In the data, 5 of 8 recent builds were built fast and then never used.

Talking to the user

  • Plain words. Name a technical term once with a five-word gloss, then use the plain word.
  • Define any name you invented (a stage, a component, a tool) the first time you use it. Never show internal codes like "Task 1c".
  • Every question-box option makes sense on its own. Recommended option first, labelled "(Recommended)". Any visual choice comes with a screenshot.
  • Never ask for something that's already in the project files.
  • Outcome first, details after. Say how to open what you made (a link, or "double-click X").
  • Secrets (API keys, client secrets) never go in chat. A passcode the user chose for their own app is theirs to share.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.