Two ways to feed the agent standing context: skills are instructions you name and pull into a prompt, and AGENTS.md is a file a project keeps for whatever agent reads it.
A skill is a piece of instruction saved under a name — a review checklist, a house style, the way commits are written here. Too long to retype, too situational for the system prompt, where you would pay for it on every turn.
It is a directory with a SKILL.md in it. The frontmatter is optional; without it the directory names the skill and the first line describes it:
--- name: review description: review checklist --- Check for data races, unhandled errors and missing tests. Say what you would change and why, and do not change it yourself.
SKILL.md rather than a format of our own, because it is what other agents already read. These directories are all searched, project first:
skills/ .raunen/skills/ .agents/skills/ .claude/skills/ .codex/skills/ .opencode/skills/
A repository that has already written its skills down works here without being adapted, and a skill written here is not wasted on the next tool. ~/.config/raunen/skills/ holds your own, applied in every project — and a project skill of the same name wins.
The older skills.json still works and needs no migration; the two are folded into one list and a SKILL.md wins a name collision.
Reference a skill with # and it goes to the model with your message. Typing # opens the list the way / and @ do, with the description beside each name; tab takes the highlighted one and a bare # lists everything, so skills are discoverable without remembering what you called them. /skills prints the same list, naming the file each came from.
▌ #review the diff on this branch # review Three things worth changing …
The skill is appended to the message on its way out, labelled [skill: review] so the model can tell where one set of instructions ends when a message names two. What you see on screen is what you typed, plus a dim line naming the skills that went with it. A name that is not a skill — #4213, example.com/x#review — is left alone. One skill is capped at 32 KB.
A project has conventions invisible in any one file: which command runs the tests, which directories are generated. Put them in AGENTS.md at the top of the repository, and it is read at startup and added to the system prompt. Keep it short — it costs context on every turn.
# raunen
Go 1.25, no runtime dependencies. `go test ./...` before a change.
- `internal/agent` must stay presentation-free
- Comments explain why, not whatIt is AGENTS.md rather than a name of our own because it is the file other agents already read — one written for raunen is not wasted on whatever gets used next.
Nested files apply to what is under them. Every AGENTS.md from the top of the tree down to the working directory is read, outermost first, so a rule in a sub-package overrides the one at the top. ~/.config/raunen/AGENTS.md comes before both and applies everywhere — the place for how you work. The walk stops at your home directory, so a stray file up the tree cannot attach itself to unrelated work.
project AGENTS.md, apps/web/AGENTS.md/status names what was loaded, because instructions that quietly did not arrive look exactly like the model ignoring them. Files are capped at 32 KB each and 64 KB in total, and what is cut is reported rather than dropped silently. Sub-agents inherit the same instructions, since they edit the same directory and cannot see the conversation.