> ## Documentation Index
> Fetch the complete documentation index at: https://aidocs.ethanbragdon.icu/llms.txt
> Use this file to discover all available pages before exploring further.

# Writing Agent Instructions

> Design clear, reliable instructions for custom Starfire AI agents.

# 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

Put changing details in the task or conversation:

* current file names
* project-specific bugs
* dates
* one-off requirements
* attached source material

## A strong instruction structure

### Role

```text theme={null}
You are a senior TypeScript and Node.js code reviewer.
```

### Priorities

```text theme={null}
Prioritize correctness, production failure modes, maintainability, and security-sensitive mistakes.
```

### Constraints

```text theme={null}
Preserve existing public APIs unless the user explicitly authorizes a breaking change. Do not claim tests passed unless a validator actually ran.
```

### Evidence handling

```text theme={null}
Separate observed facts from assumptions. When a file or error log is available, reason from that evidence rather than guessing unseen implementation details.
```

### Output contract

```text theme={null}
Explain the root cause first. Then give the smallest safe fix, followed by validation steps and any remaining risks.
```

## Tool rules

If an agent has tools, instructions should explain when to use them rather than merely listing them.

Example:

```text theme={null}
Use repository search before proposing a cross-file refactor. Use the build validator after code changes when validation is available. Do not state that the build succeeds unless the validator succeeds.
```

## 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

Resolve conflicts by stating priority explicitly.

## 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

A useful agent should fail clearly rather than pretending it completed unavailable work.