stolinski/s-stack/agentbuilder

AgentBuilder Skill

This guide is a living record. It is not part of the Standard Agent Specification — it exists to help humans and coding agents use the spec to build effective agents. It is updated regularly and not bound to any spec version.

Commands like pnpm exec agents … are placeholders. Use whichever package manager (npm, pnpm, yarn, bun) the project actually uses.

For deeper reference material that this skill links to, see:

• agents/agents/AGENTS.md — agent definition reference (created by agents scaffold)
• agents/prompts/AGENTS.md — prompt and tool config reference
• agents/tools/AGENTS.md — tool-writing patterns and ThreadState examples
• agents/models/AGENTS.md — recommended model list (authoritative)
• agents/hooks/AGENTS.md — hook reference
• Canonical TypeScript types (full signatures): read node_modules/@standardagents/spec/dist/ in your project, or browse packages/spec/src/ on GitHub at https://github.com/standardagents/agentbuilder
• Specification: https://standardagentspec.org/llms.txt
• Builder docs: https://docs.standardagentbuilder.com/llms.txt

If the agents/*/AGENTS.md files don't exist in your project yet, run pnpm exec agents scaffold to create them.

Before you write any code

Most failed Standard Agent projects fail in the same six ways. Read this section first and answer all six questions explicitly before creating any code. Each links to the deeper section that explains how.

1. Architect the agent graph before picking types. List the domains the system touches. Determine the tree (coordinator → domain agents → sub-domain agents). Then decide what each node is. Do not start by writing one agent and bolting tools onto it. → Architecture & decomposition

2. `dual_ai` is the default. `ai_human` is the exception. ai_human is correct only when the thread itself is the chat surface (chat UI, website widget, AgentBuilder admin, direct API chat). For Slack, email, SMS, Discord, webhooks, polled inboxes, schedulers, or any other mediated channel, the human is just a tool target — the agent is dual_ai. The whole graph being dual_ai is fine and often cleaner. → Interaction type

3. Every `dual_ai` agent must have explicit session boundaries. Name its sessionStop tool. Name its sessionFail tool. Set a finite maxSessionTurns. Give side_b a real, non-redundant job. If you cannot say in one sentence what tool call ends the session, the agent is not designed yet. → Session boundary discipline

4. Pick models from `current-models` only. Never invent model strings from memory. Run pnpm exec agents current-models, choose by category, then run pnpm exec agents available-models --provider=<name> to confirm the exact string. → Model selection

5. Research every third-party API before writing the tool. Fetch the official current docs. Confirm auth, base URL, endpoint paths, payload shapes, rate limits, error codes. Do not write a tool from memory of how an API "usually" works. APIs change. → API research checklist

6. Check `ThreadState` before adding any dependency. Before reaching for S3, Redis, an external cron, a queue service, or even node:fs, confirm the framework does not already provide the capability via ThreadState. It almost always does. → ThreadState first

What is a Standard Agent?

In the Standard Agent paradigm, agents are the atomic unit of an AI system, and it is the composition of many domain-specific agents that produces efficacy. Standard Agents can be effective using small and cheap models — but small and cheap models suffer from poor tool discernment when presented with a broad, undifferentiated set of tools. Decomposition is what makes them work.

A "gmail" agent will outperform a "google apps" agent. A higher-level "communications" coordinator composes the gmail, slack, and SMS agents. A still-higher "personal assistant" coordinator composes communications, research, scheduling, and finance. This is fractal: the same shape scales up to teams, departments, and entire products. These agent-graphs solve real industry problems — progressive tool discovery, model/prompt tuning, context dilution, task resumability, and compaction.

Just because subagents can compose complex behavior doesn't mean every step needs one. A subagent is a two-sided conversation where each side may take multiple steps per turn. Sometimes you only need a feature of a different model — generating an image, rewriting a paragraph in a more eloquent voice. For those, use a subprompt (a single LLM step exposed as a tool), not a subagent. Use a subagent when you need iteration, QA, reflection, or long-lived addressable behavior.

When a subagent does QA on another model's output, prefer a different provider on the reviewing side. Same-lab models tend to rate their own output too generously.

Example graph

personal_assistant_coordinator         (dual_ai, top-level reasoning model)
├── communications_coordinator         (dual_ai, resumable, explicit parent communication, note: children are explicit because they receive inbound messages and should filter out noise before returning)
│   ├── gmail_agent                    (dual_ai, resumable, immediate, explicit parent communication)
│   ├── slack_agent                    (dual_ai, resumable, immediate, explicit parent communication)
│   └── sms_agent                      (dual_ai, resumable, immediate, explicit parent communication)
├── research_assistant                 (dual_ai, resumable, explicit parent communication)
│   ├── browser_use_agent              (dual_ai, resumable, implicit parent communication)
│   ├── google_drive_agent             (dual_ai, resumable, implicit parent communication)
│   └── notes_agent                    (dual_ai, resumable, implicit parent communication)
├── scheduling_coordinator             (subprompt)
└── finance_ops_coordinator            (dual_ai)

Note: no ai_human anywhere. The "human" enters via the gmail/slack/sms tool calls. The whole graph is autonomous.

The Standard Agent stack

The spec defines an agent as a composition of:

• Providers — how to talk to LLM providers and model variants
• Models — named model definitions referencing a provider
• Prompts — system instructions plus the tools, subprompts, and subagents available at that step
• Tools — functions the agent can call to interact with the world (and other agents)
• Agents — bind it all together: name, type, sides, session bindings
• Hooks — custom code that intercepts lifecycle events (history filtering, message injection, tool result transforms)
• Effects — custom code scheduled to run later
• Threads — runtime instances of an agent, each with its own state, message history, and filesystem
• Endpoints — built-in and custom HTTP endpoints exposed by a thread

Architecture & decomposition

Procedure (do this in order, every time):

1. List the domains the system actually touches.
2. Draw the tree on paper or in a comment block. Coordinators on top, leaf agents at the bottom.
3. Pick interaction types. (Default dual_ai. Use ai_human only at chat-surface entry points.)
4. Name session boundaries for every dual_ai node.
5. Pick a model category for every node.
6. List the third-party APIs each leaf needs and queue them for research.
7. Map each capability to a ThreadState primitive before writing any custom plumbing.

Only then start writing files.

Mega-agent smell test

If a single agent has more than ~8 tools across unrelated domains, decompose it. Decomposition is rarely wrong; flattening usually is.

Other smells that mean "decompose now":

• One prompt has tools from two clearly different worlds (e.g., send_email and query_postgres and generate_image).
• The system prompt is trying to teach the model when to use which tool by writing rules in English. Rules-in-prose are coordinator logic; promote them to a coordinator that picks subagents.
• A model keeps calling the wrong tool because two tools have similar names or overlapping descriptions. Different domains, different agents.
• The agent's prompt is over ~150 lines. That's almost always context dilution — split.

Worked example: wrong vs. right

Wrong — one mega-agent with tools from unrelated domains:

personal_assistant (ai_human)
  tools: send_gmail, read_gmail, search_ebay_listings, place_ebay_order,
         track_ebay_shipment, create_calendar_event, list_calendar_events,
         post_slack_message, read_slack_channel, query_stock_price,
         execute_stock_trade, search_recipes, generate_image

Gmail, eBay, calendar, Slack, stock trading, recipes, image gen — seven unrelated worlds in one tool list. The model picks send_gmail when it meant post_slack_message. It calls execute_stock_trade with eBay listing IDs. The system prompt grows 80 lines of rules trying to teach it which tool belongs to which world. Every bug fix breaks two unrelated flows.

Right — coordinator + domain subagents:

personal_assistant_coordinator (dual_ai, reasoning model)
├── gmail_agent        tools: send_gmail, read_gmail
├── ebay_agent         tools: search_ebay_listings, place_ebay_order,
│                             track_ebay_shipment
├── calendar_agent     tools: create_calendar_event, list_calendar_events
├── slack_agent        tools: post_slack_message, read_slack_channel
├── trading_agent      tools: query_stock_price, execute_stock_trade
└── content_helpers    subprompts: search_recipes, generate_image

personal_assistant_coordinator runs a reasoning model and decides which domain owns the next step. Each leaf is a fast tool-calling model with a tight tool set it can actually discern between. A fix to the eBay flow can't break Gmail.

Coordinators

Coordinators provide two things flat agents can't:

1. Inter-domain communication. A coding_coordinator can ask research_agent to investigate a library, then hand the findings to bash_agent to run commands. The bash agent never needed to know the research agent existed.
2. Filtering. A gmail_agent can filter spam well on its own. But the higher-level objectives of the organization — "what email actually matters to the CEO of the sprinkler hose company" — belong to a coordinator above it. The coordinator filters again before escalating.

Graph depth tradeoffs

Deeper graphs add latency and create more inter-agent communication that can fail. But they also enable parallelism and isolation. A marketing_communications_agent can have a social_media_agent which has twitter_agent, linkedin_agent, and facebook_agent as children. That subtree handles posting workflows entirely without involving the top coordinator. Aim for depth that matches the natural hierarchy of the work, not depth for its own sake.

Interaction type: dual_ai is the default

`dual_ai` is the default agent shape. `ai_human` is the exception, used only when the thread itself is the chat surface — chat UI, website widget, AgentBuilder admin, or an API the user is talking to directly.

For Slack, email, SMS, Discord, webhooks, polled inboxes, schedulers, or any other mediated channel, the human is just a tool target. The agent on the framework side is dual_ai. The whole graph being dual_ai is fine — often cleaner.

The single decision

Ask: "Is the human typing directly into this thread?"

• Yes → the top-level agent is ai_human.
• No → the top-level agent is dual_ai. The human enters the graph via a tool somewhere (e.g., a send_slack_message call inside a slack subagent).