writing-prompts
Writing Model Instructions
What a model instruction is
A model instruction is any text a model reads to decide how to behave: a system prompt, a tool name and description, a parameter description, the text a tool returns, an AGENTS.md or other guidance file, a skill description or body, or a prompt template. The model reads all of these together with the conversation, and its attention is limited. Every line competes with every other line. Text that does not change behavior still costs attention.
The goal is behavior, not prose. A good instruction reliably produces the intended behavior across the whole range of situations it covers, with the least text that achieves that. Clarity for the model comes first; everything else follows from it.
Principles
Be clear and direct
Name the situation, the behavior, and the boundary. Define a term before you use it. Use concrete nouns and verbs, short sentences, and one idea per sentence. The test: a new teammate with no context should be able to follow the text without asking a question. If they would be confused, the model will be too.
Weak: "Handle git operations carefully."
Clear: "Ask before any git command that rewrites published history, such as push --force or amending a pushed commit. Run local, reversible commands without asking."