Working with coding agents — Localhost

Meet your new collaborator

Coding agents have transformed software development. This article isn’t about what they are. It’s about the levers that decide how well one works inside a real codebase you didn’t write yourself: scope, AGENTS.md, MCPs, and skills — and the loop that wraps them once your team has the rest set up.

Default scope, and why it matters

When you start a session with a coding agent, the first thing it asks for — implicitly or explicitly — is scope. Scope is the set of files and directories the agent will read from and edit.

The default scope is the repo you opened it in. Most agents aren’t strictly sandboxed — they can usually read other files on your laptop or hit the network if they want — so think of scope as a strong default about where the agent’s attention sits, not a wall.

The agent's attention defaults to the current repo. Other projects on your laptop aren't fenced off, but they're not where the agent is looking either.

In practice you almost never have to configure scope. You open the agent in the repo you want it to work on. Most agents then read a project-specific configuration file to learn how to behave — that’s the next lever.

AGENTS.md

AGENTS.md is a plain markdown file at the root of a repo. Most modern agents read it on startup and treat it as the source of truth for project-level conventions.

A short markdown file the agent reads first. Use it for the rules a teammate would tell a new contributor on day one.

What goes in it:

Architectural facts the agent can’t infer from the code. “This is a monorepo. Each app has its own package.json. Run npm commands from the right one.”
Conventions that are easy to break by accident. “All tests use Vitest, not Jest. Component files are PascalCase.”
Things to never do. “Don’t downgrade dependencies. Don’t add new state libraries. Don’t push directly to main.”
How to verify a change. “Run npm run check before any commit. Browser-test on Safari for SVG-heavy pages.”

Keep it short. ~50 lines is plenty. If your AGENTS.md becomes a novel, the most-load-bearing parts will get ignored. The convention to copy: lead with the rule, follow with one short why.

MCPs

MCP stands for Model Context Protocol. The short version: it’s a standard way to plug external tools into a coding agent.

Without MCPs, an agent sees only the files in your repo. With MCPs, it can also read your Figma designs, query your design system tokens, fetch data from your analytics, or take a screenshot of a running browser. Each MCP is a small server that exposes a set of capabilities; the agent calls them like tool functions.

MCPs are how an agent reaches outside the repo. Add the ones that match your work — Figma, your design system, a screenshot tool.

For a designer, the MCPs worth knowing about:

A Figma MCP — lets the agent read your Figma file (frames, tokens, components) directly, instead of relying on screenshots.
A screenshot / browser MCP — lets the agent open a URL, take a screenshot, and read the rendered DOM. Massively improves visual review tasks.
A design system / token MCP — exposes your team’s tokens so the agent reaches for the right --color-mintfresh-400 instead of inventing a hex.

You don’t need to install MCPs to start. They’re a layer of more capability you add when the friction of doing without them gets annoying.

Skills

Where MCPs add capabilities, skills add playbooks. A skill is a prepared chunk of instructions plus a name. When you invoke a skill (often with a /skill-name syntax in the agent’s chat), the agent follows the playbook for that task.

Skills are named playbooks. Pick the one that matches the task and the agent runs the same recipe every time.

Skills designers benefit from:

/review — run the agent over a diff with a specific checklist (visual regressions, accessibility, design system fidelity).
/plan — turn a vague request (“redo the empty state of this page”) into a concrete file-by-file plan you can review before any code is written.
/simplify — sweep a recently-changed area for over-abstracted code, dead variables, or unnecessary complexity.

You can write your own skills too. They’re just markdown files with a name and instructions. The bar is “if you find yourself asking the agent to do this same multi-step task more than twice, write it down as a skill.”

A workflow that fits a designer

In most established codebases, the AGENTS.md, MCPs, and skills are already in place — that setup is what made the repo agent-ready. Your job is to use them. The loop that actually shows up day to day:

Open the agent in the repo. Cursor, Codex, your agent of choice — point it at the project folder. The agent picks up AGENTS.md and any project skills automatically.
Start the dev server. npm run dev in a terminal (or click the Run button in your editor). The terminal prints a localhost URL — open that in a browser tab and leave it there.
Ask for the change. Plain English in the agent’s chat. “Tighten the gap between the hero headline and the subhead on the marketing page.” Drop in a screenshot or a Figma link if it helps. The agent reads, plans, and edits the files it needs to.
Watch the browser. Hot module reload usually updates the app instantly without you doing anything. Compare what you see to what you wanted.
Refine. The first pass is rarely the final one. “The headline is too tight against the eyebrow above it now — keep the headline change but bring the eyebrow gap back.” The agent applies the next pass; the browser reloads. Repeat until the page looks right, then push the branch.

That’s the whole loop: ask, preview, refine. You don’t need to know how the diff was implemented to know whether the page looks right — and that judgment was always the part designers were best at.

Try it yourself

The loop above is hard to internalize from reading — the cheapest way in is a real codebase that you can break, undo, and try again. That’s exactly what handle-playground is for: a small Vite + React app, public, designed to be edited by an agent.

If you haven’t already, clone and run it (the first article covers the setup). Then point your agent of choice at the repo and try one of these prompts:

“Add a dark mode toggle to the header.”
“Change Mia’s vibe — make her a baker instead of a designer.”
“Add a testimonials section above the footer.”
“Make the project cards more compact.”
“Swap the gradient thumbnails for real images.”

Each one is the kind of ask you’d give a junior teammate. Watch what the agent writes, look at the diff, refresh the browser, decide whether the result matches what you pictured, and refine. Most of the loop happens between your eyes and the running page — which is why it works for designers.

What’s next in Localhost

Future articles will go deeper: design tokens in code, deploying a small change end-to-end, debugging a flaky test without crying. We’re publishing them as we write them.

If you want updates when new articles drop, the Handle GitHub and @handledotai on X are the best places to watch. And if you want to try the workflow this whole series points at, Handle Studio is the macOS app that wires it all together.