Skip to main content

​
One File to Orient Any Assistant

AGENTS.md is a single, self-contained markdown file you drop at the root of your data folder — ~/.wolffish/AGENTS.md — to orient any AI assistant you point at your Wolffish installation. Open .wolffish in an editor, or hand the folder to a coding agent (Claude Code, Cursor, an MCP-connected assistant), and that assistant can read this one file to instantly understand what Wolffish is, where everything lives, and how to help you.
Don’t confuse this with agents.md (lowercase, at brain/prefrontal/agents.md). That file tells your Wolffish agent how to do its job. AGENTS.md (uppercase, at the folder root) tells a visiting assistant how to navigate your workspace. Different audience, different file.

​
Why drop it in

A Wolffish workspace is just files — readable, editable, yours. That’s the whole point: you can bring any AI to help you read, repair, or extend it. But a cold assistant doesn’t know that conversations/ lives under brain/, that capabilities are dot-prefixed, or that cortex.db is disposable. AGENTS.md front-loads all of that so the assistant is useful on the first message instead of the tenth. Moments it pays off:
  • “Why did my agent do that?” — the assistant knows to read brain/corpus/ and brain/prefrontal/.debug/.
  • “Change my agent’s personality.” — it edits brain/identity/soul.md, not random code.
  • “What am I spending?” — it sums usage/daily/*.md.
  • “Add a tool that checks the weather.” — it scaffolds a capability the right way (see below).

​
What’s inside — the topics it covers

The file is organized into twelve parts. Here’s what each one teaches a reader: Read top to bottom, it’s an onboarding course. Used as reference, sections 4 (where things live) and 8 (file formats) answer most “where / what” questions on their own.

​
Creating a capability — the short version

One of the most common things you’ll ask a visiting assistant is “teach Wolffish a new skill.” The full walkthrough — with a complete, working Weather example that needs no API key — is in Creating Capabilities. But here’s the entire idea in four steps, which is roughly what AGENTS.md tells the assistant:
1

Make a folder

~/.wolffish/workspace/brain/cerebellum/<name>/
2

Write SKILL.md

YAML frontmatter (name, description, triggers, tools) plus a markdown body of instructions. Add danger_patterns / confirm_patterns only if the tool can cause harm.
3

Add plugin/index.mjs (optional)

For custom logic, export { name, tools, execute(toolName, args) } returning { success, output }. Pure skills that lean on existing tools (shell_exec, file_read) skip this entirely.
4

Restart Wolffish

The cerebellum discovers the folder, the triggers make it matchable, and the tools become callable. No app rebuild.
That’s the whole extension model: a folder of markdown teaches your agent a new trick. See Writing Plugins and Safety Patterns for the depth.

​
Where it lives

Wolffish bundles this guide and writes it to the root of your data folder, refreshing it on every launch:
It sits next to workspace/, runtime/, and logs/ — not inside workspace/. That keeps it clear of workspace re-initialization and makes it the first thing anyone sees when they open ~/.wolffish/.
This file is managed by Wolffish — the bundled copy is rewritten on every launch, so an app update always refreshes it to the current version. Treat it as read-only: local edits are replaced on the next launch. For custom agent behavior that should persist, use agents.md instead.

​
The full AGENTS.md

This is the guide Wolffish bundles and keeps at ~/.wolffish/AGENTS.md, reproduced here for reference — read it, or drop it into an older install by hand.