Customizing

AGENTS.md

Which guidance files Shelley reads, where it looks for them, and how they reach the model.

Shelley reads plain Markdown guidance files and puts them in the system prompt. Write down your conventions once (“use pnpm”, “run make test before committing”, “never touch vendor/”) and every new conversation starts out knowing them.

File names

In a project directory, any of these count, matched case-insensitively:

File	Notes
`AGENTS.md`	The common convention. Use this one.
`AGENT.md`
`CLAUDE.md`	So a repo set up for Claude Code works as is.
`DEAR_LLM.md`
`README.md`	Only in subdirectories, and only listed (see below). A root README is ignored.

Empty files are skipped. If two files have identical contents, or one is a symlink to the other, Shelley includes it once, so ln -s AGENTS.md CLAUDE.md is fine.

Where Shelley looks

When a conversation starts, Shelley gathers guidance in this order.

1. Your personal file. Shelley checks these paths and includes every one that exists:

~/.config/AGENTS.md
~/.config/shelley/AGENTS.md
~/.agents/AGENTS.md
~/.shelley/AGENTS.md

Only the name AGENTS.md counts here. Use this file for preferences that follow you everywhere: commit style, your preferred tools, how terse you like the replies.

2. The project root. If the conversation’s working directory is inside a git repository, Shelley reads the guidance files at the repository root. Outside a repository, it uses the working directory itself.

3. The working directory. If the working directory is somewhere below the repository root, Shelley also reads the guidance files in that directory. Directories in between are not read, and neither are directories above the repository root.

The contents of all of these go into the system prompt, each tagged with its path.

4. Subdirectories, listed but not inlined. Shelley walks the project (the repository root, or the working directory outside a repo) for guidance files in subdirectories, README.md included. It skips hidden directories, node_modules, and vendor, and gives up after two seconds on very large trees. The first ten paths go in the prompt with an instruction to read them before editing files in those directories; beyond ten, the model is told how many more there are. Outside a repository the walk starts at the working directory, so a conversation started in ~ lists the guidance files and READMEs of the projects under it.

Precedence

Nothing is dropped: if several files apply, the model sees all of them, personal file first. What it should do about conflicts is left to one line in the system prompt: “Deeper files take precedence; user instructions override all.” That’s advice to the model, not a merge Shelley performs, so contradictory files produce the confusion you’d expect.

When changes take effect

The system prompt is built when a conversation starts and stored with it. Editing a guidance file affects conversations started afterwards. An existing conversation keeps the prompt it began with until something rebuilds it: /clear or /compact, or changing its system prompt or its tools in the conversation settings.

Subagents get a shorter system prompt without guidance files. If a subagent needs your conventions, the parent has to pass them along.

Editing your personal file in the UI

Edit User AGENTS.md in the conversation’s More options menu (Ctrl+Shift+,, or ⌘⇧, on a Mac) opens the first of the personal paths above that exists, or ~/.config/shelley/AGENTS.md if none does.

Each save from that editor is committed to a private git repository at ~/.local/state/shelley/agents-md.git, so an edit you regret can be recovered:

git --git-dir ~/.local/state/shelley/agents-md.git log -p

The UI doesn’t show this history; it’s there for emergencies.

Custom system prompts

A conversation or profile can replace the built-in system prompt with its own template. Guidance files appear only if that template includes them: the system prompt editor lists the variables, among them .Codebase.InjectFiles, .Codebase.InjectFileContents, and .Codebase.SubdirGuidanceSummary. The built-in template is server/system_prompt.txt. For scripted changes to every prompt, see the system-prompt hook.