Writing agent instructions
Agent instructions are the durable behavioral contract for a custom Starfire agent. They should define how the agent approaches its role without trying to encode every future task into one giant prompt.Separate durable behavior from task context
Put stable rules in the agent:- role and purpose
- priorities
- boundaries
- preferred working style
- required verification behavior
- default output structure
- current file names
- project-specific bugs
- dates
- one-off requirements
- attached source material
A strong instruction structure
Role
Priorities
Constraints
Evidence handling
Output contract
Tool rules
If an agent has tools, instructions should explain when to use them rather than merely listing them. Example:Approval boundaries
Instructions are not a substitute for runtime permission controls. Sensitive actions should still be gated by the platform’s actual authorization and approval systems. An agent instruction that says “always deploy changes” should not bypass an approval requirement configured by the workflow or organization.Avoid instruction conflicts
Common problems include:- asking the agent to be both extremely concise and exhaustively detailed
- telling it never to ask questions while requiring missing information
- demanding certainty when evidence is incomplete
- mixing several unrelated professional roles into one agent
Keep proprietary data out of the prompt
Do not place API secrets, passwords, private keys, or production credentials inside an agent’s reusable instructions. Credentials belong in the platform’s secure integration or developer-credential layer.Test an agent
Before using an agent for important work, test it against:- a normal request
- an ambiguous request
- a request with missing information
- a request that conflicts with its constraints
- a task that would require a tool it does not have