Rules and skills

Give the agent standing instructions in AGENTS.md files, and skills it loads for particular kinds of work.

Rules files

Standing instructions for the agent go in plain Markdown files named AGENTS.md:

A rules file is whatever you would tell someone new to the work. For example:

# Working on this project

- Build with `make` and test with `make test`; run the tests before saying a change is done.
- Never change anything under `vendor/`.
- Write commit messages in the present tense.

Short, specific rules work best.

How rules are read

The files are read at the start of every turn, so an edit applies from your next message. The agent panel says which files it is following ("Following the rules in ~/.config/astrum/AGENTS.md and AGENTS.md."), and says it again when that changes.

They are given to the agent in order: your own file first, then the project's, from the one furthest up down to the one in the current directory. When rules disagree, the file closest to the current directory wins, and what you ask for in the conversation wins over all of them.

The instructions setting

A line or two for the agent can also go in the config file, under [agent]:

[agent]
instructions = "Prefer ripgrep over grep."

It is added to what the agent is told in every tab and every project, ahead of the rules files, and applies from the next message once the file is saved. Anything longer is easier to keep in ~/.config/astrum/AGENTS.md.

What a skill is

A skill is instructions for a particular kind of work, kept in a folder of its own with whatever it needs: scripts, templates, reference files. It is the layout other agents use, so a skill written for one of them works here as it is.

release-notes/
  SKILL.md
  scripts/changes.sh

The agent is shown only each skill's name and description, so having many skills costs little. When one fits what you ask, it loads the rest and follows it.

Writing a skill

SKILL.md begins with a short front matter, then the instructions:

---
name: release-notes
description: Write release notes for recent commits. Use when asked for release notes.
---
1. Run `scripts/changes.sh N` from this skill's folder ...

Where skills are found

Each of these is a folder of skill folders:

Where two skills have the same name, the later in that list wins: a project's over one from skill_dirs, and that over your own; among a project's folders, the closest. Skills are looked for afresh at the start of every turn, so a skill you add is there from your next message. Up to 100 are offered from each of the three, so a project with a great many does not leave out your own.

How the agent uses skills

When a skill fits what you ask, the agent loads it before it starts (the panel shows Read the skill release-notes) and follows it. It can read the skill's other files the same way. Loading a skill is never asked about: it only reads. A script a skill brings is run as any command is, in your shell, after the usual question, so a skill does not change what needs your approval.

Using a skill on purpose

To use one on purpose, type its name as a command in the panel, with what you want after it:

/release-notes for 0.6.0

The slash menu offers the skills as you type, after Astrum's own commands, each with skill:, where it is from (yours, from skill_dirs, or this project) and its description. With nothing after the name, the agent does what the skill is for, here. A skill that has the name of one of Astrum's own commands (/model, /help and the like) can still be loaded by the agent, but not chosen this way.

Turning skills off and on

/skills lists the skills there are: each one's name, where it is from (yours, from skill_dirs, or this project), whether it is off, what it is for and its folder.

A shell showing a project skill's SKILL.md, with its name, its description and three steps, and below it the agent panel listing four skills: one of this project, one from skill_dirs and two of yours, each with its description and its folderA shell showing a project skill's SKILL.md, with its name, its description and three steps, and below it the agent panel listing four skills: one of this project, one from skill_dirs and two of yours, each with its description and its folder
A skill as a file, and the skills there are, from /skills

To turn one off, choose ≡ menu → Settings → Skills (the row says how many there are, and how many are off), then choose the skill; choosing it again turns it back on. In the panel, /skills off name and /skills on name do the same. A skill that is off is not shown to the agent, and /name says it is off. The choice is remembered, for every session.

Skills on another machine

In a tab on another machine, or with the agent taken into an ssh, the agent is offered your own skills, which stay on your machine. A project's skills are read only when the project is on this machine.

A script one of your skills brings is put on the other machine by Astrum when the agent asks for it, in ~/.cache/astrum/skills/ there, as it is; one larger than 256 KB is not put there. In an ssh with nothing of Astrum's on the other side, the agent reads the script and writes it there itself, with a command you approve. See Other machines.