Custom Agents & Chat Modes, Explained From Zero

This is the capstone of the customization toolkit: instead of one all-purpose helper, you assemble a small team of focused experts, each tuned for a job and each holding only the tools that job needs.

1 · One assistant, many jobs

By default, your coding assistant is a generalist — one helper trying to do everything: write, review, explain, plan, fix. Convenient, but a jack-of-all-trades is rarely the best tool for a specific job. Doing a careful security review, you want a focused reviewer, not a helper that's also eager to write features. Planning, you want a thoughtful planner that doesn't start editing files. Custom agents — also called custom chat modes — let you build exactly that: specialised versions of the assistant, each with its own personality, instructions, and limited set of tools.

2 · A named mode you can switch to

A custom agent is defined in a file and shows up as a named mode you switch to. You might create a “Reviewer” that only reviews and points out problems, a “Planner” that breaks features into steps without writing code, or a “Test writer” specialised in your testing patterns. Each is a saved preset combining an instruction block that sets its role — essentially a purpose-built system prompt — and a chosen set of tools it's allowed to use. Switch to that mode and the assistant becomes that expert. It's like having colleagues with different specialities and choosing whom to ask — except they're the same model, reshaped by different instructions and permissions.

3 · The key power: limiting tools

The most valuable, often overlooked feature is control over tools. Recall from the security fundamentals that an agent can only do what its tools allow, and that least privilege — granting only the tools a job needs — shrinks the blast radius. Custom agents apply exactly that. A “Reviewer” can be given read-only tools: it can look and comment but cannot edit files or run commands. A “Builder” gets tools to edit and run tests. A “Planner” might get no action tools at all. This is real safety and real focus at once: a reviewer that literally cannot change your code can't accidentally “fix” something, and a planner that can't edit won't build before you've agreed the plan.

4 · A worked example: the Reviewer

You create reviewer.agent.md. Its instructions say: you are a strict, experienced code reviewer; examine the code for bugs, security issues, and style problems; explain each clearly; do not edit anything, only report. And you give it read-only tools. Now, whenever you want a serious review, you switch to Reviewer mode and get a focused critic that behaves consistently and physically cannot alter your code. Compare that to asking your general assistant “review this,” where it might start rewriting things or drift into adding features. The custom agent bottles up exactly the behaviour you want and makes it repeatable and safe — and, committed to the repo, your whole team switches to the same well-tuned Reviewer.

5 · Modes stop the drift

Beyond safety, modes stop the drift. A general assistant, being eager, tends to do more than you asked — you request a review and it starts fixing; you ask for a plan and it starts coding. That over-helpfulness takes actions you hadn't approved and muddles the task. A focused mode with a tight role and limited tools resists that pull: a Planner that can't edit will actually just give you a plan; a Reviewer that can't write code will actually just review. By narrowing both instructions and capabilities, you keep the assistant in the exact lane you wanted — calmer, more predictable, easier to trust. Sometimes the most useful thing you can give an assistant is a clear boundary.

6 · When to build one

Don't rush to build a dozen modes — custom agents earn their keep when a need recurs. Good candidates: a job you do repeatedly and want done consistently (reviewing, test-writing); a job where limiting what the assistant can do genuinely matters (a mode touching production config that should be read-mostly); or a behaviour you've tuned and want to reuse without re-explaining. If you keep setting up the same role in chat by hand — “act as a strict reviewer, don't change anything” — that repetition is the signal to make it a mode. For one-off tasks, just use chat. Capture something as reusable infrastructure once it proves worth repeating, and not before.

7 · It all composes

Custom agents compose with everything else — they're the capstone that ties the toolkit together. A custom agent still reads your always-on and scoped instructions, so your Reviewer already knows your conventions. It can invoke your prompt files, so a Test-writer mode can call your polished “write tests” prompt. And its tools can include the skills you've written, so a Builder mode can reach into your migration skill. So a custom agent isn't a separate thing that ignores the rest — it's a focused package that draws on all the context and tools you've built, aimed at one job with the right permissions. That's the whole picture: instructions for conventions, prompt files for tasks, skills for deep expertise, and custom agents that assemble a focused, safe specialist.

8 · A simple test you can run this week

9 · Glossary — every term, spelled out

Custom agent / chat mode

A named, specialised version of the assistant with its own role, instructions, and allowed tools.

Role instruction

The purpose-built system prompt that defines how a mode behaves.

Tool set

The specific actions a mode is permitted to take — read-only, edit, run commands, and so on.

Least privilege

Granting a mode only the tools its job needs, so it can't do — or break — more than intended.

Drift

An eager general assistant doing more than asked; a focused mode with limited tools resists it.

Composition

A custom agent drawing on your instructions, prompt files, and skills together.