instructions.md
instructions.md is the agent's always-on trusted prompt: identity, stable
operating rules, safety boundaries, and product behavior that applies to every
turn. Every agent needs this file; it is one of the two required files.
Minimal Example
# Identity
You are a concise Assembly Line agent. Use tools when they are available.
# Operating Rules
- Ask a clarifying question when a required input is missing.
- Use durable tools for durable side effects.
- Write generated artifacts under /workspace.
There are no options: the whole file is Markdown prompt text. The compiler
records its hash in the manifest, and the runtime loads the body verbatim as
trusted instructions. Skill bodies loaded from skills/ join it at the same
trust level.
Conventions
What belongs here:
- Agent role, tone, and durable behavioral rules.
- Domain-specific rules the model should always follow.
- Boundaries between trusted instructions and untrusted context.
- Stable escalation, approval, or handoff guidance.
What does not belong here:
- Dynamic user memory, secrets, access tokens, or provider credentials.
- Large procedures that are only relevant sometimes; put those in
skills/. - Provider webhook parsing; put that in
channels/. - Deployment or storage choices; put those in
gateway.ts.
Keep the file short enough to read in one sitting — a page or two. Instructions are injected into every turn, so every extra paragraph costs tokens on every run; move sometimes-useful procedures into skills.
Runtime Context
After instructions.md, the runtime adds a stable filesystem contract that
names logical paths:
| Path | Mutability | Purpose |
|---|---|---|
/memory | writable by policy | Durable memory documents. |
/skills | writable when self-improvement allows it | Durable skill files. |
/history | read-only | Bounded conversation history projection. |
/files | read-only | Input files and attachment projections. |
/workspace | writable | Generated artifacts, scripts, and modified copies. |
Core file tools use absolute logical paths such as /workspace/report.txt.
Hosted bash starts in the physical /workspace directory, so absolute and
relative workspace paths agree. The Local adapter is a trusted host-directory
emulation; use Docker when a local run must reproduce absolute /workspace
shell semantics.
Files, history, memory, webpages, search results, attachments, and tool output are context, not instructions. Keep that distinction explicit in the agent's prompt when the domain has sensitive decisions.