ralphctl-writing-for-agents

Writing for Agents

Adapted from mattpocock/skills — "Writing for Agents" (MIT). Adapted for ralphctl's harness contract.

A reference for writing any document an agent consumes: a project context file, a skill, a task spec, a set of requirements. The packaging differs; the writing does not. The same levers make each one predictable — the agent takes the same process every run, rather than producing the same output.

The session's prompt still owns the output: its length targets, required sections, and what-to-leave-out rules win over anything here.

When this applies

• Readiness — the context-file proposal. Every line is loaded into every future session, so each one must change behaviour versus the default. Point at what the environment already states instead of restating it, but keep every exact command the prompt asks for (build and test lines, setup and verify skill bodies).
• Refine — the requirements are read by the planner and every implementing session. Give each criterion a checkable completion condition, keep each meaning in one place, and phrase the target behaviour positively.

Context pointers

A context pointer is a line in context that names material outside it and encodes when to reach it — a skill's description, or a context-file line naming a doc. The pointer's wording, not its target, decides when and how reliably the agent reaches the material. A must-have target behind a weakly worded pointer is a variance bug: sharpen the wording first; inline the material only if that fails.

A pointer states what the material is and lists the branches — distinct cases — that should trigger it. Every word of an always-loaded pointer costs on every turn, so prune it hardest:

• Front-load the leading word; the start of the pointer does the triggering.
• One trigger per branch. Synonyms naming one branch are one branch written twice.
• Cut identity the body already carries.