writing-for-agents

Write the description as a context pointer: front-load the leading trigger word, list one trigger per distinct branch the skill handles, and cut any identity the body already carries. Every word of an always-loaded description costs context on every turn, so prune it harder than body text.

Organize content along an information hierarchy: in-file steps first, in-file reference consulted on demand, and disclosed reference pushed behind pointers into separate files. Keep each concept's definition, rules, and caveats co-located under one heading.

Split by sequence when visible later steps tempt the agent to rush the current one, or by invocation when a distinct trigger word should fire a skill independently. Each split spends context or cognitive load, so the cut must earn its cost.

A model-invoked skill keeps a description so the agent and other skills can fire it autonomously, paying permanent context load. A user-invoked skill sets disable-model-invocation: true, removing that load but requiring the human to remember and invoke it by name.

Common causes are weakly worded pointers, no-op instructions the model already follows by default, and negations that activate the forbidden behavior. Sharpen pointer wording, delete sentences that fail the default-behavior test, and state positive target behaviors instead of prohibitions.