# Write agent instructions

Define stable behavior with a system prompt, reusable skills, and named prompt templates.

Start with one clear system instruction. Add skills and prompt templates only when behavior needs to be reusable or invoked for a specific task.

## Write the base instruction

`.pi/SYSTEM.md` applies to every turn:

```markdown
# Incident investigator

Investigate operational reports using the available workspace and tools.

## Working rules

1. Read existing evidence before changing files.
2. Label assumptions explicitly.
3. Keep a chronological investigation log in `/workspace/investigation.md`.
4. Never expose credentials or raw secret values.

## Final response

Report the observed impact, likely cause, evidence, and next action.
```

Write instructions as observable behavior. Prefer “save the report to this path” over vague goals such as “be thorough.”

## Add a reusable skill

Use a skill when a procedure should be discoverable and reusable across prompts.

Create `.pi/skills/incident-triage/SKILL.md`:

```markdown
---
name: incident-triage
description: Triage an incident and produce an evidence-backed assessment
disableModelInvocation: false
---

1. Read the available incident artifacts.
2. Build a timestamped event sequence.
3. Separate direct evidence from inference.
4. Record unresolved questions.
5. Produce a concise incident assessment.
```

Set `disableModelInvocation: true` when the skill should be selected only by trusted application logic rather than automatically by the model.

## Add a named prompt

Use a prompt template for a repeatable user-facing task:

`.pi/prompts/incident-report.md`:

```markdown
---
name: incident-report
description: Produce the final report for an investigated incident
argumentHint: <incident-id>
---

Create a report containing the timeline, impact, cause, evidence, resolution, and follow-up work.
```

## Choose the right mechanism

| Need                           | Use             |
| ------------------------------ | --------------- |
| Rules that always apply        | `.pi/SYSTEM.md` |
| A reusable operating procedure | Skill           |
| A named task template          | Prompt template |
| New executable behavior        | Extension tool  |
| Behavior around runtime events | Lifecycle hook  |

Skills and prompts are compiled into the immutable deployment. Changing them requires a new deployment.

## Validate discovery

```bash
salambo manifest --path . --json
```

Confirm the compiled output contains the expected system prompt inputs, skill names, prompt names, and provenance. Next, [configure built-in tools](/docs/agent-development/settings).