A prompt with tools

Ask a model. If it asked for tools, run them, put the answers back, ask again. Stop when it stops asking. That is the whole loop.

It runs in two places, and the difference is how much you hand over. work.agent() runs it inside a job you control, bounded by the tools that step was given and the cap you set: see step, model, agent. A markdown job runs it for the whole run, which is this page.

Hand over a whole run only when the work is open ended from end to end: answering somebody on a channel, writing the evening note, working out what a week of failures means.

A job that is a prompt

The words are markdown, either as a .md file with frontmatter, named in agent.ts with markdownJob("jobs/<id>.md"), or as a .ts job with markdown: when the job needs a line of code around its words. A job has run or markdown and never both, and the loader refuses anything with neither.

A markdown job takes four keys and no others: cron, description, timezone, model. A cron that does not read stops the agent loading.

Read your `sites` note, and your own notes from the last few weeks.

Then say, in three sentences at most, whether anything has been quietly getting
worse: a site that is slower than it was, one that failed twice this month, one
you have written about before and nothing changed.

If nothing has, say that in one sentence and stop. A quiet week is a fine
answer and is worth writing down as one.

Write what you found into a note so that next week's run can read it.

What a tool is

A tool is for a model and nothing else. The work is a plain function published from chloejs, and a job calls it from a step. A tool is a description, a schema and one call over that function. Nothing in a tool does work of its own.

A job that imports a tool is either paying a model to read a path it already knew, or it wanted a plain function, and the tests say so. The other direction is fine: a tool may call a job's exported function.

Three sets most agents take, each named for what it gives:

• memory(): list_notes, read_notes, search_notes and write_notes, all inside one folder, for what an agent keeps from one run to the next.
• selfImprovement(): write_skill, to rewrite its own skills. Every write is a commit.
• runScripts(): run_script, to run a file in its own scripts/ folder. An agent with no scripts is refused as it loads.

A tool that fails does not kill the turn. A missing tool, bad arguments, or a tool that throws all go back to the model as text it can act on, because a turn that dies on one bad call throws away everything it had already done. So a run that worked may still hold failures: read the trace, not just the reply.

A tool that reaches private material is bound, not asked

The search behind a mail tool, and the folder behind the notes tools, come from the agent's own agent.ts. The model chooses only how far back and how many. Reading one item re-runs that same search and refuses anything that is not in it.

A query a model can write is a filter, not a boundary: it widens the moment a turn goes wrong, and by then it has already read the thing. Give any new tool that reaches private material this shape.

Skills and scripts

A skill is a markdown file in skills/ with a name and a description, saying when to do something and which script does it. The agent sees every skill's description and opens the ones it needs. Skills are the first thing to reach for: they are words, and they are live with no restart.

A script is any executable file in scripts/. Shell when you are stringing commands together, TypeScript or Python when you are parsing. The more a script decides for itself, the less there is for a prompt to get wrong.

Every script in that folder is reachable by that agent, so if no skill or instruction mentions one, it does not belong there.

What an agent may change about itself

It writes its own skills and its own notes. A skill is markdown, it is committed as it is written, and it can only point at a script that is already there, so self-improvement always leaves a diff you can read.

It does not write its own tools or scripts. Those are code, and code an agent writes is code it then runs as itself.