What's inside an agent template

One zip, one folder, no build step. Nothing here needs installing before you can read it, and the whole thing opens in a text editor.

One folder is the whole point. A pack that needs a build step, a package to install, or a service to sign up for has stopped being something you can pick up on a Tuesday afternoon.

The goal is the first line of SOUL.md, and it is the line that decides whether the agent does anything useful. A goal names the job and the finish. If you cannot tell whether it was done, it is a wish, not a goal.

The left column tells the agent when to stop. The right column tells it to keep going forever, which is how a helpful agent turns into an expensive one.

The authority line is the guardrail. It says what the agent may change, what it may only read, and where it stops and asks.

Authority — Read-only on the finance folder. Raise questions; never edit an invoice.
  read-only on the finance folder  → it may look, not write
  raise questions                  → it reports back to a human
  never edit an invoice            → the line that survives a bad day

• The folders it may write to, named, and the ones it may only read.
• The actions that always wait for a person: sending mail, paying, publishing, deleting.
• What it should refuse outright, which is usually anything outside the folder it was given.
• A spend or time ceiling, so a loop that goes wrong ends on its own.

A template with no authority line is not a template to leave running unattended. What to let your agent touch takes the permissions side further, and API keys and permissions covers the credentials that go with them.

A skill is a folder with a short file in it. The file says when the skill applies, the steps to take, and the mistakes to avoid. Skills are where a template stops being generic and starts knowing your paperwork. The shape is set by an open standard rather than by whoever wrote the pack, so a skill written for one harness is readable by the others that follow it (the specification).

• SKILL.md — when to use it, the steps, and the pitfalls worth a warning.
• references/ — the detail, loaded only when the skill actually needs it.
• scripts/ — small programs for the parts that should not be improvised.

The best skills encode something you would otherwise have to explain: how your invoice numbers are shaped, which supplier names are the same company, the one table your finance team reads on a Monday.

Two different things get called memory. The first is the notes an agent writes for itself: what it learned about your files, which phrases mean the same thing, the approach that failed last time. Those notes are the reason a template gets better in its second week.

The second is the conversation in front of it. That one cannot grow forever — an agent can only hold so much at once — so as it works, it shortens the record: it writes down what mattered and lets the rest go. That shortening is compaction, and it is the least glamorous, most consequential part of any long-running agent.

Which is why a good template says what is worth keeping. A pack that remembers everything remembers the wrong things, and a pack that remembers nothing asks you the same question every Monday.

An agent that runs while you are asleep needs to leave a note. The templates worth keeping ship a reporting skill, so each run produces a record you can read later without replaying anything.

• What it did, in short: the task, the outcome, the time it took.
• What went wrong, with enough detail to recognise the same problem next week.
• What it recommends changing — in the template, not just in this run.
• What it learned, so the next version starts from something.

This is also how you judge a template from outside: a pack that reports is a pack someone has actually left running.

Self-improvement sounds like a claim. In practice it is a loop you can open and read, in three steps: the agent writes down a lesson, the lesson carries a status — active, solved, obsolete — and the next run reads the notes before it starts.

That is the whole trick, and it is why memory and reporting sit next to each other in a pack. One remembers, the other is the evidence that it did.

Be sceptical of a template that claims to improve and shows you neither the notes it keeps nor the report it writes. If the loop is real, you can see it in the files.

• The authority line — what it may touch, and what it must ask about.
• The licence — MIT most often, which is the one to keep if you plan to adapt it.
• The version note — what changed since the copy you were running.
• The quickstart — if it does not say which tool it was written for, that is the first question for the maker.
• The goal — if you cannot tell when it is finished, do not leave it running.