What an agent is
An assistant answers. An agent acts, looks at what happened, and decides what to do next. The mechanical difference is small — a loop — and the consequences are large.
while not done:
decide the next action
execute it
read the result
update understanding
Because it runs commands and reads their output, an agent can find its own mistakes: run the tests, see the failure, fix it, run them again. That is genuinely new, and it is also why context discipline stops being an optimisation and becomes a requirement. Every step adds output to the window, so a loose context that was merely wasteful in a chat becomes a session that dies halfway through a task.
Progressive disclosure
If you have forty instruction sets covering your conventions, deployment, testing, and security, you cannot load them all — that is the red band from the homepage demo.
Progressive disclosure loads them in stages:
- Index. The agent sees only each skill's name and one-line description — around a hundred tokens each.
- Activate. When a description matches the task, it opens that one file in full.
- Resources. If that file points at scripts, references, or templates, they load only at the moment they are needed.
Forty skills cost you roughly four thousand tokens of index instead of a hundred and fifty thousand of bodies — and the one that matters arrives in full, near the end of the prompt where attention is strongest.
The description is the trigger. If two skills describe overlapping territory, both fire and compete; if one is vague, it never fires at all. Write descriptions that say precisely when to use the skill and, where there is any risk of overlap, when not to.
Skill files
A skill is a folder with a Markdown file in it. The frontmatter is the index entry; the body is the procedure.
---
name: django-deployment
description: Deploy a Django service to staging or production.
Use when the user asks to deploy, release, or ship a Django
app, or mentions migrations against a live database.
---
# Django deployment
1. Confirm the target environment explicitly. Never infer it.
2. Run the test suite. Do not proceed on failure.
3. Apply migrations with --plan first and show the output.
4. Deploy, then verify /health before reporting success.
## Never
- Run migrations directly against production without a plan.
- Skip step 4 because the deploy command exited zero.
Note what this is doing. It is not teaching Django — the model knows Django. It is encoding your sequence, your guardrails, and the specific mistakes you have seen made before. That is knowledge no amount of training data contains.
Keep the body short, a few hundred lines at most, and push detail into separate reference files that load on demand. And treat skills from strangers as executable code, because effectively they are: a skill file can instruct an agent to read your environment variables and send them somewhere. Read before installing.
Tool calling
Tool calling is the mechanism underneath all of it. You describe the functions available — name, purpose, parameters — and the model responds with a request to call one. Your code executes it and returns the result. The model never runs anything itself.
Two practical points. Tool definitions are sent on every request, so they belong in the cached prefix. And descriptions matter as much as they do for skills: an ambiguous tool description produces an agent that calls the wrong thing confidently.
MCP servers
The Model Context Protocol is an open standard for exposing tools and data to any assistant that speaks it. Instead of writing a separate integration for each product, you write one MCP server and every compatible client can use it.
For a team this is the difference between maintaining four integrations and maintaining one. It is also a clean boundary for permissions: the server decides what is exposed, and nothing outside that surface is reachable.
Multi-agent workflows
Once one agent works, the temptation is to build a team of them. Sometimes that is right, usually for one specific reason: context isolation.
If a task requires reading forty files to extract one answer, doing it in the main conversation dumps forty files of noise into a context you still need. Handing it to a sub-agent means the noise lives and dies in that sub-agent, and only the answer comes back.
That is the strong case. The weak case is splitting by job title — a "planner", a "coder", a "reviewer" — which mostly adds handoffs where context gets lost. Split when you want to quarantine context, not to imitate an org chart.
The complete loop
Everything in this book assembled into one working cycle:
- Wake. The agent reads the stable system prompt and the static memory files, placed at the front so they stay cached.
- Index. It reads the skill index — names and descriptions only.
- Understand. Your request arrives at the end of the payload, where attention is strongest.
- Activate. It opens the one or two skills that actually match.
- Act. It works the loop — call a tool, read the result, correct itself.
- Compress. As the window fills, history collapses into a structured handoff rather than being truncated.
- Write back. Before finishing, it updates the memory files so the next session starts oriented.
Steps 1, 2, and 4 are Phase 2 and progressive disclosure. Step 6 is compression. Step 7 is the memory bank. The economics from Phase 3 run underneath all of it. None of the pieces are complicated on their own — the discipline is in doing all seven, every time, so that the next session inherits a working state instead of an empty window.