Table of Contents generated with DocToc
By now you have worked with an agent, chosen a model, written a skill, learned to keep it safe, tested it with evals, and let it run on its own. This page steps back to name the idea underneath all of it, the mental shift that makes the whole craft click.
Here it is: when you build with agents, the words you write are the program. The English (or any natural language) in your prompts and skills is not documentation about the code. It is the code. Once that lands, a lot of the advice in this stream stops feeling like a list of tips and starts feeling like one coherent discipline.
New to some of these words? Here is what they mean here. The landing page has a fuller list.
| Traditional programming | Programming with English |
|---|---|
| You write code in a formal language | You write instructions in natural language |
| The compiler is exact and unforgiving | The model is flexible and interprets |
| A typo fails loudly | A vague phrase fails quietly, by doing something plausible but wrong |
| You debug logic | You debug wording and ambiguity |
| Tests give a yes or no | Evals give a distribution, better or worse across many inputs |
The middle column is where twenty years of habit lives. The right column is the new craft. Neither is harder; they fail differently, and you debug them differently.
A beginner's hope is that natural language means you can be vague and the model will “just get it”. The opposite is true. Because the model will act on whatever you wrote, imprecise words produce imprecise behaviour, and, worse, they fail quietly. A compiler rejects a typo with an error. A model reads a woolly instruction and does something reasonable-looking that is not what you meant, and you may not notice until it matters.
So precision does not go away when you write in English. It moves from syntax to meaning. Compare:
“Handle old issues.”
against:
“An issue is ‘stale’ if it has had no comment for 90 days and carries no
pinnedlabel. For each stale issue, draft (do not post) a comment asking whether it is still relevant.”
The second leaves the model far less to invent. Every ambiguity you remove is a decision you made instead of one the model made for you. Writing for an agent is the discipline of hunting down ambiguity and closing it.
In ordinary prose, “review the recent changes” is a perfectly clear sentence. As an instruction to an agent it hides at least three bugs. Recent since when? Review how, meaning read them, critique them, or summarise them? The changes to what? Each unstated answer is a place the agent will guess, and it may guess differently on Tuesday than it did on Monday.
This is why so much of good skill-writing is really disambiguation:
If prose is the program, then everything you already do to keep code healthy applies, and Magpie leans into exactly this:
The deepest consequence of this idea is that your “compiler”, the model, is probabilistic. Give it the same instruction twice and it may act slightly differently each time. A real compiler is deterministic, so passing once means passing forever. A model is not, so a single successful run tells you almost nothing.
That is the whole reason this stream gives evals their own step. When the language you program in is executed by something that interprets rather than computes, the only way to know your program works is to run it over many representative inputs and judge the results as a whole. Evals are not an add-on to programming in English; they are the part that makes it engineering instead of hoping.
Hold onto “the words are the program” and the rest of the craft organises itself:
The tools are new. The engineering instincts are the ones you already have. This page is just the bridge that lets you reuse them.
Everything in docs/education/ is under the Apache License 2.0 (PRINCIPLE 17). Pages written with help from AI carry a Generated-by: note in their commit message, following ASF Generative Tooling Guidance.