# Instructions

Project and global instructions loaded at startup.

An `AGENTS.md` file holds standing instructions for the agent: coding conventions, package managers, framework rules, things to always or never do. zot loads them at startup and appends them to the system prompt. No file is created or required; zot only includes the ones that already exist.

## Load order

Global instructions in `$ZOT_HOME/AGENTS.md` are loaded first. Then zot walks from the filesystem root down to the current working directory and loads the first matching instruction file in each directory. This includes `~/AGENTS.md` when the working directory is inside your home directory. Later files are more specific and may override earlier ones.

- $ZOT_HOME/AGENTS.md (global, applies everywhere)
- <filesystem-root>/AGENTS.md
- <ancestor>/AGENTS.md
- <cwd>/AGENTS.md (closest to cwd wins on conflicts)

> Per directory, zot reads the first of `AGENTS.md` or `AGENTS.MD` it finds. Empty files are skipped. Changing the working directory reloads the set for the new cwd.

## Disable for one run

Pass `--no-context-files` or `-nc` to skip discovery and loading of every global and project `AGENTS.md` file for that run. The files are not read, appended to the system prompt, or listed in startup context.

## Startup visibility

Enable `show loaded resources at startup` in `/settings` to list loaded context paths, extensions, and user-installed skills in compact `Context`, [Extensions](/docs/extensions), and [Skills](/docs/skills) sections above the transcript. Built-in skills are omitted. The setting is off by default, and the lists are not sent to the model or stored in the session transcript.

The upcoming [Pinned skills] notice is separate from this display setting. It shows skills selected for the next message, including their project or global scope, even when startup resource lists are off. Unlike the display-only lists, pinned skill bodies enter the conversation with that message. See [Skills](/docs/skills) for availability and behavior.

## $ZOT_HOME defaults

- All platforms: `$XDG_STATE_HOME/zot` when `XDG_STATE_HOME` is set.
- macOS fallback: `~/Library/Application Support/zot`.
- Linux fallback: `~/.local/state/zot`.
- Windows fallback: `%LOCALAPPDATA%/zot`.

> **Only AGENTS.md**
>
> zot reads instruction context from `AGENTS.md` only. It does not load `CLAUDE.md` or other vendor instruction files. (The Claude- and agent-compatible layouts zot understands are for skills, under `.claude/skills/` and `.agents/skills/`, not for instructions.) If you keep rules in a `CLAUDE.md`, point an `AGENTS.md` at it or copy the content over.

## Example

```AGENTS.md
# Project rules

- Use the package manager that matches the lockfile.
- Never start the dev server; run typecheck, lint, and build instead.
- Keep answers short and substantive.
- Do not use em-dashes in any text you write.
```

Reach for `AGENTS.md` when you want rules that travel with a repository and apply to every session. Reach for `SYSTEM.md` when you want to replace zot's core identity outright.