Modifying Agents
A guide for changing an automation agent you already have — fixing what it proposes, retuning a rule, rescheduling it, or switching its model. Describe what's wrong (or what you want changed) in plain words; Claude reads the live agent, reproduces the problem on real data, proposes a fix, and simulates the new behavior against the old before anything goes live. Also clarifies what only humans can do (approve, activate).
What is this?
You already have an automation agent running (you built one with Adding Agents). Over time you'll want to change it — "it keeps proposing the wrong thing," "run it an hour earlier," "only flag it when the signal is strong," "post to a different Slack channel."
Your part is the same as before: describe what's wrong (or what you want changed) in plain words and hand it to Claude. Claude then works through it by following the /maintain-platform-agent skill — with one crucial discipline: it looks at the live agent and real data first, and it shows you the new behavior next to the old one before anything goes live.
Symbols on this page:
- 🤖 = a step you hand to your Claude (copy-paste the prompt)
- 👤 = a step you do by hand
- 🛠= a step only an admin / owner can do (ask one if you can't)
This assumes the agent already exists and Claude is connected to the platform via MCP. Building a new one? See Adding Agents first. MCP not connected? Do Connect Claude (MCP).
Two kinds of requests (both are fine)
There are two ways you'll ask for a change — and it helps to know Claude treats them differently:
| You say… | Example | How Claude treats it |
|---|---|---|
| A problem | "The agent keeps flagging rooms that don't need it" | Finds the root cause on real data first |
| A fix | "Change the window from 7 to 14 days" | Treats it as a hypothesis to test, not an order |
Why test a fix you already decided on? Your proposed fix might not solve the real cause — or it might fix your case but drag in things you didn't want. So Claude checks it against real data before shipping it. You lose nothing; you just find out before it's live instead of after.
How big is the change? (three "rungs")
Not every change is equal. Claude picks the lowest rung that solves your request — lower rungs are faster, safer, and often need no code at all.
| Rung | What's changing | Needs code / PR? | How it goes live |
|---|---|---|---|
| Operational | When it runs, which model, which Slack channel, or propose-vs-auto | No | Effective immediately |
| Behavior | The agent's actual rule, its wording, or what data it reads | No — a new "version" | A human approves + activates it |
| New ability | It needs data or a capability it doesn't have yet | Yes — code + PR | Merge the PR, then approve + activate |
You don't choose the rung — Claude works out where the thing you want to change actually lives, and tells you. Most changes are the first two rungs (no code).
Before you start (prerequisites)
| What you need | Why | Who |
|---|---|---|
| The agent already exists and runs | You're changing it, not creating it | 👤 If it's new, see Adding Agents |
| MCP connected | So Claude can read the live agent, its runs, and real data | 👤 If not, see the connect guide |
| A rough description of what's wrong or what you want changed | To kick off the conversation | 👤 You |
| An agent-console admin who can approve/activate (or one to ask) | The final step to go live for a behavior change | 🛠Admin |
| Ability to review/merge a PR | Only if the change needs new code (the top rung) | 🤖 Claude writes it → 👤 you review/merge |
Changing an agent is not "one prompt and done." It's a short loop: describe → Claude diagnoses → you approve the approach → Claude changes it and simulates → you compare → a human turns it on. Two of those are deliberately human checkpoints.
Step 1 — Describe it; Claude diagnoses on real data 👤 → 🤖
You don't need to know which rung it is or how the agent is built. Describe what's wrong (or what you want changed) in a sentence or two. Claude will (1) update the repo, (2) read the /maintain-platform-agent skill, (3) read the live agent and its recent runs over MCP, (4) reproduce the problem on real data — actually pull the same rows the agent saw — and (5) come back with a diagnosis, a proposed change, and a plan to test it.
Nothing changes on the platform in this step. Claude is only reading and reproducing.
Starting in Claude Code's Plan Mode lets you review the diagnosis and the proposed approach before Claude touches anything.
This first checkpoint — you approve the approach before Claude changes anything — matters because a change to a live agent should never be a guess. If Claude can't reproduce the problem on real data, that's an answer too: it'll tell you, instead of "fixing" something it never saw.
Step 2 — Claude changes it and shows you before-vs-after 🤖 → 👤
Once you're happy with the approach, Claude makes the change at the lowest rung — but does not turn it on. Then it simulates: it runs both the current agent and the changed agent against the same real data (often tomorrow's) and shows you a before-vs-after — what the agent would now do differently, and just as importantly, what stays the same.
This is the second checkpoint: you compare and decide you're satisfied before anything goes live. A few things worth knowing:
- "No change / nothing proposed" can be the correct result. If the changed agent correctly decides there's nothing to flag today, an empty result is a pass, not a bug.
- Look at what stays the same, too. A good change fixes your case without quietly affecting everything else. Claude confirms the unaffected part is unaffected (the "blast radius").
- Nothing is live yet. The changed agent is sitting off to the side; the simulation never writes anything or posts to Slack.
Step 3 — Go live, and how to undo it ðŸ›
Only after you're satisfied does the change go live — and for a behavior change this is deliberately human-only:
| Rung | To go live | Who |
|---|---|---|
| Operational (schedule / model / channel) | Already applied — it took effect when Claude set it | 🤖 Claude (MCP) or 🛠admin |
| Behavior (a new version) | A human approves + activates the new version in agent-console | 🛠Human only (console) |
| New ability (code) | Merge the PR first, then a human approves + activates the version | 👤 merge → 🛠approve+activate |
| Propose → auto (apply without approval) | An admin flips it in the console — only after a clean simulation | 🛠Admin (console) |
Why are approve and activate human-only? Same safety valve as when you added the agent: Claude can prepare a change and simulate it, but a human always gives the final GO. That's exactly what lets Claude build a changed version and test it without it ever going live on its own.
Undoing a change is easy. Every behavior change is a new "version," and the old one is kept. If the live change surprises you, a human just re-activates the previous version in the console — an instant switch back. An operational change (schedule / channel) is undone by setting the old value again.
Once it's live, have Claude confirm the real behavior matches the simulation:
Troubleshooting
| Symptom | Meaning / fix |
|---|---|
| Claude "fixed" it but nothing changed | For a behavior change, did a human approve + activate the new version in the console? Authoring the change alone doesn't make it live. |
| Live behavior differs from the simulation | Re-run and compare with run_read. If the change needed new code, was the PR merged before activating? |
| "Nothing proposed" after the change | May be correct by design (nothing to flag today). Check the run result before assuming it's broken. |
| Rescheduled but it doesn't run at the new time | Is the agent still activated? Is the schedule ON, and the worker ON on the owner side (🛠)? |
| Want to go back to how it was | A human re-activates the previous version in the console (instant). Operational change → set the old value again. |
| Claude says the change needs code | That's the top rung — it needs a PR you review/merge, then approve + activate. Expect two tracks, not one prompt. |
| Claude can't reproduce the problem | That's a finding, not a failure — the cause may be elsewhere (data, timing, or already fixed). |
Quiz
You tell Claude: 'just change the agent's window from 7 to 14 days.' What does Claude do?