agent-builder

Generating a workspace layout is easy; deciding the autonomy model before generating anything is what most agent builds get wrong, and this skill forces that conversation first. The advisor, operator and autopilot distinction is a clean way to pin down what the agent may do without asking, and the required file set (identity, user profile, agent rules, heartbeat plan) maps directly to the failure modes you hit later: an agent that does not know its user, or does not know when to speak. The multiple-short-rounds interview guidance is also correct in practice. Trade-off: the output is a starting scaffold, not a finished agent, so expect to iterate on the guardrails after the first real tasks expose which permissions were too broad. Read the workspace reference before filling in the templates rather than after.

Use case: Standing up a new agent and needing to decide its surfaces, autonomy level and heartbeat plan before writing prompts.

# The order of decisions matters more than the templates Generating identity and rules files is mechanical. The expensive mistakes are made earlier, when nobody decides what the agent is allowed to do on its own. Settle three things first, then fill the templates. ## One: the mission sentence Write a single sentence describing the agent's primary mission. If it needs an and, you are probably describing two agents. A tight mission makes every later guardrail easier to justify, because you can ask whether a proposed capability serves it. ## Two: the surfaces Decide which channels the agent answers on, and whether it speaks in direct messages, in group channels, or both. Group surfaces change the tone and force a rule about when to stay quiet; a group-capable agent with no silence rule becomes noise within a week. ## Three: the autonomy level This is the decision people skip and then pay for. Pick one explicitly and write it into the agent's rules: - advisor reports and suggests, acting on nothing - operator performs non-destructive work and asks before anything destructive or external - autopilot acts broadly, which raises both value and blast radius ```python # Encode the autonomy level as a permission check, not as prose in a prompt. LEVELS = { "advisor": {"read": True, "write_local": False, "write_external": False, "destructive": False}, "operator": {"read": True, "write_local": True, "write_external": False, "destructive": False}, "autopilot":{"read": True, "write_local": True, "write_external": True, "destructive": True}, } def may(level, action): rules = LEVELS[level] if action not in rules: return False return rules[action] for level in LEVELS: print(level, "publish:", may(level, "write_external"), "delete:", may(level, "destructive")) ``` ## Then write the files Identity, user profile, agent rules, and a heartbeat plan each map to a failure you will otherwise meet later: an agent that does not know its user, does not know its own boundaries, or does not know when to report. Fill them after the three decisions above, so the rules file expresses a decision rather than a guess. ## Tips - Ask the mission, surfaces and autonomy questions in several short rounds instead of one long questionnaire. - Write the silence rule for group channels at build time; retrofitting it after the agent has been noisy is harder. - Treat the generated workspace as a scaffold and expect to tighten permissions after the first real tasks. - Gotcha: picking autopilot because it is convenient makes the blast radius of a single wrong tool call far larger than the time saved. - Gotcha: an agent that cannot state which model and version it is running cannot be debugged when behaviour changes.