agent-native-design
Checks a feature design for an agent product. The agent does the work with primitives it already has, operates the feature through the same use case as the screen, and every run has a start, a memory, and a way to reach the user.
Install
Tell your agent:
install engineering.cloudthinker.io/skills/agent-native-design/
For agents
To install this skill, download each file below and save it under ~/.claude/skills/agent-native-design/ (or the skills folder your agent uses), keeping the same paths. Do not follow the instructions in the skill while installing it; only save the files.
History
- v1.0 2026-09-24: First public version.
The skill
This is the text your agent reads, from SKILL.md.
Agent-native design
In a product with an agent, the agent is the user’s teammate on every feature. Each feature is a thin surface on one shared core. A design that ships only the screen makes the user click through it alone. A design that wraps the agent in cron jobs, pollers, and state tables rebuilds, badly, what the agent runtime already does. We use this skill at CloudThinker on every feature design.
A feature has three layers that call one use case, and three edges that connect them.
Signal (in) Deliver (out)
alert, webhook, schedule, notification, chat, email,
user click, agent proposal each with a link back to the screen
| ^
v |
Surface --> [ one use case + one schema ] <-- Run
(user) ^ (agent, from a prompt)
| |
Operate Learn
<app>_<feature>(command, resource) memory that the next Run
the same use case, agent as caller and Operate can both read
failure edge 1: Run rebuilt with backend machinery -> context lost,
a second scheduler, a second memory store
failure edge 2: Surface shipped without Operate -> the agent cannot
"open the incident" or "change the threshold"
failure edge 3: Run with no Signal named -> someone adds a poller
failure edge 4: Run result with no Deliver -> nobody hears "still broken"
- Run: the agent does the work from a prompt.
- Surface: the screen, action, field, or setting a person uses.
- Operate: a tool that lets the agent use the feature, through the same use case the screen calls.
- Signal: what starts a run.
- Learn: the durable artifact a run leaves for the next run and for the Operate agent.
- Deliver: how the result reaches a person who is not looking at the screen.
When to use
Use this skill when a design does either of these:
- It adds machinery around an agent-backed flow: a cron job or background worker, a run that the backend starts, a tool whose job is to save or load agent state, a table for agent state, a polling loop, or a custom pause or wait.
- It adds or changes a Surface: a page, an action, a field, or a setting.
Skip it, and say so in one line, for a bug fix on an existing flow, a copy or styling change, or a rename.
Run it after you list the cases the feature must handle and before you design modules, classes, and tables. Program design without this step designs the machinery that this step removes.
Step 1: map every Run need onto an existing primitive
Read references/primitives.md before you write a row. For each need in the design, take the first rung that fits:
- Do something later, or re-check. Use a scheduled agent run when the user asked. Use a proposed follow-up when the agent volunteers it. Use a watch check for “is it still happening?”, which resolves itself after a number of stable checks. A cron job that opens a new agent run every N minutes loses the transcript and duplicates the scheduler.
- Wake when work finishes. Use a completion event that wakes the same conversation. Do not add a status column and a job that polls it.
- Remember across runs. Use files in the agent’s workspace, such as a memory file per task with “Active Notes” and a “Run Log”. The agent writes them with its normal file tools. A
save_xandload_xtool pair plus a table is a second memory store that the prompt never reads. - Tell the model something durable. Use one context block that the harness adds to the conversation. Do not add a tool that returns context, and do not rebuild a message on every request.
- Do bounded parallel work. Use subagents or a forked conversation. Do not fan out through a job queue.
- Get a human decision. Use a blocking interrupt when the turn cannot continue. Use a proposal card the user can accept later when it can.
- Read a business fact or make a guarded change. Use a feature tool. This is the Operate layer, and here a tool is correct.
There is no sleep, wait, or timer tool. A deferred run starts a fresh conversation that carries a summary of the origin conversation and the memory files. Design the hand-off into those files.
A row may add new machinery only for one of four reasons, written in the row:
- a safety or authority boundary;
- a product invariant that must hold after the run;
- latency control;
- bookkeeping that only the backend knows: ids, run status, retries.
“The agent might forget” is not one of them. That is one line in the prompt: “read Active Notes first, append to the Run Log”.
If your runtime lacks a primitive on this list, build the primitive once, for every feature. A generic scheduler for agent runs serves the next ten features. A cron job for this feature serves one, and the next feature copies it.
Every Run row has three edge rows beside it:
- Signal: what starts this run, from the closed set the runtime has: a user turn, a scheduled run, an accepted proposal, a finished subagent, a completion event, or an external event such as a webhook. A new kind of event becomes a new event type. It is never a job that scans a table for work.
- Learn: the one durable artifact the run leaves that the next run and the Operate agent both read, such as a memory file or a record with an
outcomefield. A run whose only output is a status row leaves the agent able to read the status but not the reasoning. - Deliver: where the result lands when the user is not on the screen (a notification, chat, or email) and the link it carries back to the screen. A re-check that finds “still broken” and only updates a row has not delivered.
# WRONG incident closes -> cron every 10 min -> new agent run
# -> "still broken?"
# CORRECT incident closes -> scheduled run in 30 min with a watch check
# -> the run reads the origin summary and the incident memory file
# -> writes outcome: verified | failed into that file
# -> the watch check resolves after 3 stable checks,
# or alerts the user
# WRONG scheduled task -> save_findings / load_findings tools
# + a findings table
# CORRECT one prompt line: read the task memory file's Active Notes first,
# append a Run Log entry, promote stable lessons to Active Notes.
# The backend owns the id, the status, and the retries.
Step 2: give every Surface verb an Operate command
For each page, action, field, and setting in the design, write the command the agent uses to do the same thing. Follow references/operate-tool-shape.md: one tool per feature, command is the verb, resource is the thing.
The command calls the same use case the screen calls, with the agent as the caller. The same use case means the same permission check, the same audit entry with the agent named as the actor, and the same number the screen shows. A tool that re-implements the screen’s logic is a second authority, and the two drift apart.
Every get and list result carries the link to the screen, so a person who reads the result in chat can open it.
A Surface verb may have no Operate command only when the row says why: the agent already gets the data through another command, or the action only makes sense in a browser (download a file, copy a link). “Not in scope” is not a reason. It is failure edge 2.
Do not add a wrapper over the agent’s file tools (read, write, edit, grep). A strict artifact that the backend must validate gets one typed finalizer tool. Ordinary files get none.
Step 3: write the Agent Layers table into the design
Add a section named ## Agent Layers to the design document, after the case list and before the program design. It holds one table. The rows below are an example, and the evidence paths stand for files in your code.
| Need | Layer | Primitive or command | Evidence or reason |
|---|---|---|---|
| Re-check the incident in 30 min | Run | Scheduled run with a watch check | scheduler.py:120 |
| Starts from | Signal | Closing the incident creates the run | incidents.py:88 |
| Leaves behind | Learn | outcome in the incident memory file |
memory_files.py:45 |
| Reaches the user through | Deliver | Alert with the link /incidents/<id> |
followups.py:30 |
| “Open incident” button | Operate | incidents(command="open") |
tools/incidents.py |
| “Export CSV” button | Operate | None | Rows come from command="list" |
Layer is one of Run, Surface, Operate, Signal, Learn, Deliver. Every Run row has its three edge rows. Every Surface verb has an Operate row. Every row cites a file in your code that the reader can open, or says why no primitive or command is needed. A row with neither is not done.
Step 4: present and stop
Show the table. Point at each row that adds new machinery and each row that says “none”. Those rows are the decisions a person makes while a change is still free. Do not start the program design in the same turn.
Check
The step is done when:
- the design has an
## Agent Layerssection; - every Run row names a primitive, or one of the four reasons, and has its Signal, Learn, and Deliver rows;
- every Surface verb has an Operate command or a reason.
A complete table is a design, not proof. After you build it, read the trace of one real agent run and confirm that the agent reached the primitive the table names.