Practical Agent Design: Composing Agents from Components

Most “build an AI agent” articles describe a single artifact - a prompt, a model, a tool list. After a year of building production agents at Ability.ai, I think that framing is wrong.

An agent isn’t one thing. It’s a stack of small, swappable components, and the design work is choosing which components a given agent actually needs. The interesting question is never “how do I build the agent” - it’s “which subset of the available components does this particular job require, and which would just add surface area?”

You will learn:

• The seven components every production agent is composed from

• Four archetypes that recur across real agents

• A decision matrix for adding components without over-engineering

• Five principles that fell out of doing this enough times to know which mistakes repeat

──────────────────────────────

Every agent I build today is assembled from some subset of seven layers.

A CLAUDE.md file at the agent root. Defines who the agent is, what it owns, what it doesn’t. The only mandatory component.

The mistake to avoid: stuffing identity with operational detail. Identity is who, skills are how. If a paragraph in CLAUDE.md describes a multi-step procedure, it belongs in a skill instead.

Slash-callable procedures in .claude/skills/[name]/SKILL.md. They give an agent operational control - a known method for a known job, instead of relying on the model to invent one each time.

Three tiers:

Tier

Description

Example

**Simple**

Stateless, one-shot.

`/summarize-meeting`

**Stateful**

Reads or writes state, calls APIs.

`/send-email`

**Playbook**

Multi-step workflow with checkpoints.

`/work-loop`

The discipline: a skill encodes the right way to do something in your context. The first time you correct an agent’s approach, you’ve identified a candidate skill. Capture it.

Five memory templates:

Type

When to use

**file-index**

Agent operates inside a folder of human-curated files.

**json-state**

Agent tracks counters, configs, last-run timestamps.

**workspace**

Agent runs multiple parallel projects with their own lifecycle.

**brain**

Agent accumulates knowledge over time and surfaces connections.

**vault**

The brain *is* the product (Cornelius’s pattern).

Memory should follow one principle: the agent should still do useful work when the memory layer is empty. Memory enhances - it doesn’t gate.

Turns the agent’s own GitHub repo into its work queue. Adds:

• /backlog, /pick-work, /close-work, /work-loop

The shift in mental model: instead of telling the agent what to do each session, you file issues against it the same way you file issues against a human teammate.

Three hooks that turn the agent’s repo into its durable state layer:

• SessionStart: stash drift, fetch, rebase, restore drift

• PreCompact: fast local commit so in-flight work survives compaction

• Stop: commit and push, with rebase-on-reject retry

This is what makes an agent durable across sessions. The folder is the cognition; git is the persistence.

For multi-session work that doesn’t fit a single conversation. I use it sparingly - reach for it when scope crosses a week of effort.

Deploys the agent so it can run on a schedule, receive MCP calls, and stay always-on for inbound triggers (email, webhooks). Trinity is the upgrade, not the gate. Every agent works locally first.

──────────────────────────────

These are the patterns I see recurring. Each is a different combination of the seven components.

Example: Cornelius - Identity, domain skills, vault memory, git-sync, Trinity. No backlog.

Distinguishing trait: the memory is the product. Value comes from the growing graph, not from any single skill output.

When to build this: the user wants a thinking partner over time, not a one-shot answer machine.

Example: Corbin (business management) - Identity, operational skills, file-index + json-state, git-sync, Trinity. No backlog.

Distinguishing trait: the agent acts on the world through tool calls. Memory is for awareness and audit, not knowledge accumulation.

When to build this: the user has recurring operational chores and wants them executed reliably.

Example: Lilu (maintains Ability.ai’s wizard system) - Identity, workflow skills. No memory, no backlog, no Trinity required.

Distinguishing trait: the agent modifies another codebase. Its memory lives in that other codebase’s git history. Lightweight by design.

When to build this: the user has a system they maintain and wants a specialised collaborator.

Example: any dev agent running `/work-loop` on Trinity - Narrow identity, dev skills, workspace memory, backlog, git-sync, Trinity.

Distinguishing trait: fully event-driven and autonomous. You file issues, it ships PRs.

When to build this: you have well-scoped engineering work and want it to happen while you sleep.

──────────────────────────────

When I scaffold a new agent I walk down this list:

Question

If yes, add

Will it accumulate knowledge over weeks/months?

**brain** or **vault**

Will it operate inside a folder of human-curated files?

**file-index**

Does it have small structured state?

**json-state**

Does it run multiple parallel projects?

**workspace**

Will work arrive as a queue of discrete tasks?

**backlog**

Will it run when no human is watching?

**git-sync** + **Trinity**

Will scope cross a week of effort?

**plan**

Have you corrected its approach to a recurring job more than once?

promote into a **skill**

The inverse matters too. If the answer is no, don’t add it. Composition is a budget, not a buffet.

──────────────────────────────

Memory is a product decision, not a technical one. “Should this agent remember?” is the wrong question. The right one is “what is this agent’s relationship to time?” An operator forgets gracefully. A knowledge worker must not. A builder doesn’t need its own memory because the artefact it builds is the memory.

Skills earn their place by surviving correction. A skill that you wrote once and never corrected is suspect. The good ones are the ones that crystallised after the third time you said “no, do it this way.”

Backlog is a regime change. Adding GitHub Issues isn’t a feature, it’s a different mode of working. You stop having conversations and start filing tickets. Most agents shouldn’t make this transition.

Git-sync without Trinity is half a feature. Local-only durability is nice. Cross-instance durability - local Claude Code and remote Trinity routine sharing the same repo state - is where it pays off. Install them together or neither.

Composition beats inheritance. I tried building a “base agent” once that included everything. It was unusable. Every conversation started by parsing layers the agent didn’t need. The current model - empty by default, add only what’s required - is much better.

──────────────────────────────

The seven components aren’t a framework, they’re a vocabulary. Most days I don’t think about them explicitly - I think about what the agent needs to do, and the components fall out. But when I’m scaffolding something new, or auditing something I built six months ago, having names for the pieces is what keeps the work honest.

If you’re starting your first agent: identity plus two or three skills. Resist everything else until the agent earns it.

The agent will tell you what it needs by where it keeps failing. Listen to those failures, and the right component will be obvious.