writing-agent-instructionslisted

# Writing Agent Instructions Choose the smallest instruction surface that reaches the intended work: - Put durable repository facts, commands, boundaries, and conventions in the nearest applicable project instruction file. - Put reusable task judgment or a multi-step capability in a skill. - Put rules that must execute or block an action in tests, hooks, settings, or a deterministic tool. Prose can guide a model but cannot enforce behavior. Read the applicable repository instructions, nearby instruction files, code, tests, and configured tools before drafting. For every load-bearing statement, identify its source as direct observation, repository policy, upstream documentation, or an explicit author decision. Remove claims that code or a command can reveal cheaply unless their omission would repeatedly cause a bad decision. Write the minimum instruction that changes behavior. State the condition, the required outcome, and any real boundary. Preserve user intent and existing authorization. Do not turn examples, preferences, or hypothetical risks into blanket prohibitions, approval gates, fixed workflows, or extra files. Add detail only when omitting it caused an observed failure or creates a concrete risk. Write every new deterministic helper or policy tool in Go. For a skill, read [skill authoring](references/skills.md). For project or subfolder guidance, read [repository instructions](references/repository-instructions.md). Read both only when the task changes both