---
title: Design an agent
description: Plan a Hub before you build it. Choose what the agent knows and can reach, agree the plan with the people it serves, then map each part to a folder.
canonical_url: https://hubzoid.com/docs/guides/design-an-agent
last_updated: 2026-09-27
---

# Design an agent

Plan a Hub before you build it. Choose what the agent knows and can reach, agree the plan with the people it serves, then map each part to a folder.

An agent is what it knows plus what it can reach. Most of the work in a useful agent is choosing both, and that is quicker on one page than in code. This guide describes a working practice. Hubzoid does not enforce any of it.

## Start with one job

Write these down before you create any files:

- **One goal you can check**, such as "supplier bills are matched within a day". If it needs a paragraph, it is not clear yet.
- **Up to three things the agent does.** More than three usually means two agents.
- **What stays human.** What the agent decides, what it drafts for a person to approve, and who signs off the rules it follows.

## Choose the four parts

Each part answers one question. [The Hub](https://hubzoid.com/docs/concepts/hub#what-a-hub-holds) shows them around the agent's definition in `AGENTS.md`.

| Part | The question | Where it lives |
| --- | --- | --- |
| Knowledge | What must it hold as true? | `knowledge/`, `raw_data/` |
| Skills | Which procedures does it follow? | `skills/` |
| Tools | What must it compute or check? | `tools_local/` |
| Connections | Which live systems must it read? | `restricted/`, `connectors/.mcp.json` |

## Rules of thumb

- **Knowledge first, tools second, live systems last.** Most of an agent's value is what it knows. A first version with no live connections ships quickly and is safe to test.
- **Small, named knowledge files.** Keep one topic per file, with a description that says when to read it, because the model chooses from names and descriptions. Copy sources into the Hub rather than linking to them, and give each source an owner who confirms it.
- **One skill per task.** Write it as plain numbered steps. Only a skill's name and description sit in the prompt until it is loaded, so many skills cost little.
- **Never let the model produce a number that matters.** Compute totals, dates and thresholds in a tool, and let the model explain the result. When the model fills in fields, allow "not found", because a field that must always have a value invites an invented one.
- **Keep the tool list short.** Every tool's description takes context on every call and adds a choice the model can get wrong. Turn off the web tools with `HUBZOID_DISABLE_HTTP_GET` and `HUBZOID_DISABLE_WEB_SEARCH` when the agent does not need them, and give each delegate a `tools:` list.
- **Connections read-only and restricted.** Put tools that reach live systems in `restricted/`, so only people and workflows granted the permission can run them and every call is recorded. Nothing in `tools_local/` or `connectors/` checks who is asking, so give their credentials the narrowest scope. Prefer a system's API to driving its screens with the shared browser.

## Agree before you build

Two approvals before any building save the most rework:

1. **Collect the sources:** specifications, email threads, exports, procedures and spreadsheets.
2. **Describe the work as it is today:** the people involved by role, the systems they use and where time is lost.
3. **Write a one-page plan** with the goal, the three things, each knowledge source and tool with its expected impact, and what stays human.
4. **Agree the plan.** The person who asked and the owner of each knowledge source approve it.
5. **Record it next to the Hub**, for example as a reviewed change in Git, so the build points back to what was agreed.
6. **Build and test.** Run `hubzoid doctor`, try prompts with `hubzoid test`, and add an [eval](https://hubzoid.com/docs/guides/evals) for each behavior in the plan.
7. **Release with a short note:** what the agent does, who can use it and where, and what it does not do.

New sources or feedback start the loop again. A change inside the agreed scope, such as a new skill or refreshed knowledge, can go straight to step 6.

## From plan to folder

Every part of an agreed plan has a home in the Hub. A row with no home is not ready to build.

| In the plan | In the Hub | Built as |
| --- | --- | --- |
| The one job | `AGENTS.md` | Role, duties, tone, which knowledge and skill to use when, and what to refuse |
| Knowledge | `knowledge/`, `raw_data/` | Topic files with descriptions, plus copied source material to search |
| Skills | `skills/` | One procedure per task |
| Tools | `tools_local/` | Python functions with `@function_tool` |
| Connections | `restricted/`, `connectors/.mcp.json` | Restricted tools with one permission per file, or MCP servers with a narrow credential |
| Scheduled work | `schedule/`, `workflows/` | A markdown task with a cron or webhook trigger, or a code workflow |
| Checks | `evals/` | One case per behavior |
| Who may use it | The Console | **Use this agent** and tool permission grants |

`hubzoid init` creates the folder. [Project structure](https://hubzoid.com/docs/getting-started/project-structure) lists every file, and [bring an existing agent](https://hubzoid.com/docs/guides/existing-agents) covers starting from a project you already have.

## Next steps

- [Tools and connectors](https://hubzoid.com/docs/guides/tools-and-connectors): Write Python tools and add MCP servers.
- [Restrict tools](https://hubzoid.com/docs/guides/restrict-tools): Put a live system behind a permission.
- [Evals](https://hubzoid.com/docs/guides/evals): Turn each planned behavior into a check.