CloudThinker Engineering

Home > Skills > agent-native-design

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

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"

When to use

Use this skill when a design does either of these:

  1. 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.
  2. 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:

  1. 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.
  2. 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.
  3. 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_x and load_x tool pair plus a table is a second memory store that the prompt never reads.
  4. 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.
  5. Do bounded parallel work. Use subagents or a forked conversation. Do not fan out through a job queue.
  6. 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.
  7. 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:

“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:

# 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:

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.


CloudThinker Engineering · engineering.cloudthinker.io · Last built 2026-11-08 · Plain text version