agent-builder

name

agent-builder

description

Design and build TypeScript/Bun AI agents for any domain. Use when users: (1) ask to create an agent, assistant, or agent harness (2) want to understand agent architecture, tool use, planning, subagents, or skills (3) need a small runnable Bun/TypeScript agent scaffold (4) ask about Claude Code, Cursor, or similar agent internals Keywords: agent, assistant, autonomous, workflow, tool use, orchestration, bun, typescript

Agent Builder

Build AI agents for customer service, research, operations, creative work, or specialized business processes using the same TypeScript/Bun harness patterns as this project.

Core Idea

The model already knows how to act. Your job is to provide a small loop, clear tools, and clean context.

while (true) {
  const response = await client.createMessage({ messages, tools, systemPrompt });
  messages.push({ role: "assistant", content: response.content });
  if (response.stopReason !== "tool_use") break;

  const results = await runToolCalls(response.content, tools);
  messages.push({ role: "user", content: results });
}

The magic is not in a giant workflow graph. The harness gives the model capabilities and faithfully returns the results.

Three Elements

1. Capabilities: small tools the model can call, such as bash, read_file, write_file, edit_file, todo, or domain APIs.
2. Knowledge: markdown skills loaded on demand, not shoved into every prompt.
3. Context: messages, summaries, task state, and artifacts that keep the work coherent.

Design Checklist

• Purpose: What should the agent accomplish?
• Domain: What files, APIs, data, or people does it operate around?
• Tools: What 3-5 actions unlock most work?
• Knowledge: Which SKILL.md documents should be loadable?
• State: Does it need todos, tasks, inboxes, background work, or worktrees?
• Trust boundary: Which operations need confirmation or sandboxing?

Progressive Complexity

Level	Add	When
s01	one loop + bash	Always start here
s02	typed tool dispatch	File operations need safety
s03	todos	Multi-step work drifts
s04	subagents	Exploration pollutes parent context
s05	skills	Domain knowledge should load on demand
s06	compaction	Context grows too large
s07+	tasks, teams, background tasks, worktrees	Work must persist or run in parallel

Implementation Resources

• references/minimal-agent.ts: a compact runnable agent loop
• references/tool-templates.ts: Bun-friendly runtime tool examples
• references/subagent-pattern.ts: isolated child-loop pattern
• scripts/init_agent.ts: scaffold a new Bun/TypeScript agent project

Scaffolding

bun skills/agent-builder/scripts/init_agent.ts my-agent --level 2
cd my-agent
bun install
bun agent.ts

Principles

1. Keep the loop boring.
2. Make tools typed and narrow.
3. Prefer Bun.file, Bun.write, and Bun.spawn for runtime work.
4. Load knowledge only when it is relevant.
5. Persist state that must survive the chat transcript.
6. Use subagents when investigation would flood the parent context.