Instructions and skills

Your deployment describes what the model is. Instructions and skills describe how the agent should operate it — that a constraint is off limits, that “leg” means one vehicle between two stops, that volumes are reported in pallets, and what your end-of-shift handover note has to look like.

Both are authored by you, stored with the deployment, and copied into every project created from it. Neither is a file in the project workspace, so nobody chatting with the agent can edit them.

Instructions: an AGENTS.md appended to the agent’s prompt

Write plain markdown. It is appended to the agent’s system prompt for every turn, labelled as coming from you.

AGENTS.md

# Operating instructions — Northwind Logistics

## Vocabulary

- A **leg** is one vehicle travelling between two consecutive stops. A **route** is all the legs
  one vehicle drives in a shift.
- **Drop** means a delivery to a customer stop. Never call it a "job" or a "task".

## Reporting conventions

- Report distances in **kilometres**, to one decimal place.
- Report load as a count of **pallets**, never in m³ or kg.

## Rules

- The vehicle capacity constraint is fixed by our fleet contract. Never modify or relax it, and if
  asked to, explain that it is set by the deployment and decline.

## Escalation

- Changes to fleet size, vehicle capacity, or depot hours go through the operations manager, not
  through this chat. Say so and stop rather than modelling them.

Declare it in the config and it ships with aura deploy:

pyproject.toml

[tool.aura.deployment.vrp]
data_folder = "../define/data"
agents_md = "../agent-config/AGENTS.md"

Or push one on its own, without re-uploading the model:

aura deployment instructions set ./AGENTS.md vrp
aura deployment instructions show vrp          # print what the deployment ships
aura deployment instructions delete vrp

Write rules, not formatting

Vocabulary, units, refusals, and escalation land reliably. An instruction dictating the shape of a reply — “end every message with this exact line” — competes with Aura’s own presentation rules and usually loses. Say what the agent must know and must not do, not how to lay out an answer.

Instructions steer, they do not enforce

The agent knows your rule at the moment it acts and will normally follow it and cite it when declining. That is behavioural steering, not a security boundary — do not rely on an instruction to protect something that must not happen. Instructions are also not secret: the agent will quote the rule it is refusing on.

Skills: procedures the agent loads when they apply

A skill is a directory with a SKILL.md whose frontmatter carries a name matching the directory and a description. The agent reads descriptions and pulls in the body only when a request calls for it, so a long procedure costs nothing on unrelated turns.

skills/depot-handover/SKILL.md

---
name: depot-handover
description: Produce the end-of-shift depot handover note. Trigger whenever the user asks for a
  "handover note" or "depot handover" for a solved route plan. The format is fixed and must be
  reproduced exactly rather than paraphrased.
---

# depot-handover

The depot supervisor reads this off a clipboard at shift change, so the format is fixed by
Northwind's operations manual (form NWD-114).

## Format

```
=== NORTHWIND DEPOT HANDOVER ===
Form:               NWD-114
Vehicles returned:  [count of vehicles used]
Total distance:     [total km, one decimal place]
Drops carried over: [count of unserved drops, or "none"]
=== END HANDOVER ===
```

## Rules

- If a value is unavailable because no solve has run, write `NO SOLVE ON RECORD` rather than
  guessing.

The description is what selection turns on — say when to use the skill, not just what it is.

Point the config at the folder holding them; each subdirectory becomes one skill:

pyproject.toml

[tool.aura.deployment.vrp]
data_folder = "../define/data"
skills_folder = "../agent-config/skills"

aura deployment skills list vrp                              # names + descriptions
aura deployment skills show depot-handover vrp                # one skill, contents and all
aura deployment skills set ./skills/depot-handover vrp        # push just one
aura deployment skills delete depot-handover vrp

Your skills are mounted alongside Aura’s own, never in place of them. Aura’s names are reserved, and size is capped because every byte travels with each turn: 64 KiB of instructions, and per deployment 20 skills of 256 KiB each (128 KiB per file), 512 KiB in all.

Per-project overrides

A project starts with a copy of what its deployment shipped, so a later edit to the deployment does not change projects already running. On top of that copy, a project can add its own:

TypeScript

// Adds to the deployment's rules; does not replace them.
await aura.setProjectInstructions(project.id, "# Contract ZEBRA-42\n\n- Cite the contract id.\n");

const { deployment, project: own } = await aura.getProjectInstructions(project.id);

// A skill named like a deployment one shadows it, for this project only.
await aura.setProjectSkill(project.id, "depot-handover", { "SKILL.md": skillMd });

const skills = await aura.listProjectSkills(project.id); // filenames only
const one = await aura.getProjectSkill(project.id, "depot-handover"); // bodies + scope

Python

# Adds to the deployment's rules; does not replace them.
await aura.set_project_instructions(project.id, "# Contract ZEBRA-42\n\n- Cite the contract id.\n")

view = await aura.get_project_instructions(project.id)
print(view.deployment, view.project)

# A skill named like a deployment one shadows it, for this project only.
await aura.set_project_skill(project.id, "depot-handover", {"SKILL.md": skill_md})

skills = await aura.list_project_skills(project.id)  # filenames only
one = await aura.get_project_skill(project.id, "depot-handover")  # bodies + scope

aura project instructions set ./project-rules.md
aura project skills set ./skills/depot-handover
aura project skills list    # every skill in force, labelled by scope
aura project skills show depot-handover

Reads separate the two scopes, so you can always see why a rule is in force, and the agent attributes a rule to the scope that set it when it cites one. list labels every skill with the scope that set it — naming the deployment it was pulled from, since a project can pull from one it was not seeded from — and marks a deployment skill that a project skill shadows. show <skill> prints the copy actually in force, contents and all, which for a shadowed name is the project’s own.

Project commands only ever change the project

A project holds its own copy of what it pulled, so deleting there never touches the deployment or any sibling project — and delete takes no scope, because it removes what this project holds:

aura project instructions delete       # both blocks, this project only
aura project skills delete depot-handover

Set it before the project is ready to run

Only Run turns read this config, but you can write it to a project that has not reached run mode yet — it is deferred, not discarded. The prompt is rebuilt from storage on every turn, so rules set now take effect on the first Run turn.

Pulling in a revision

Because a project holds a copy, it does not see a deployment edit until something pulls it in. Re-pull the config on its own, leaving the workspace alone:

TypeScript

await aura.pullAgentConfig(project.id, "acme/vrp");                        // both kinds
await aura.pullAgentConfig(project.id, "acme/vrp", { skills: false });     // instructions only

Python

await aura.pull_agent_config(project.id, "acme/vrp")                  # both kinds
await aura.pull_agent_config(project.id, "acme/vrp", skills=False)    # instructions only

aura project instructions pull acme/vrp
aura project skills pull acme/vrp

This replaces the deployment scope and keeps the project’s own additions, so a rule you revised takes effect and one you retired stops applying. It is how a project gets back anything it deleted.

A full checkout of the deployment does the same thing and overwrites run/, data/, and solutions/ — use pull when you only want the rules and not the files. Config is separate from the workspace: a snapshot checkout leaves it alone. A deployment checkout pulls it, and so does pull on its own.