USER.md for AI Agents: A Portable Operator Profile

Every AI tool I use wants to know the same things: who I am, what I am working on, how I like answers formatted, and what to never do. I was repeating myself across Claude, OpenCode, Cursor, and a handful of custom agents. So I extracted it into one file.

The idea

A USER.md (or USER.md-equivalent) is a portable operator profile. It is not a system prompt and it is not project documentation. It holds tastes: communication style, priorities, constraints, and preferences. Infra rules live in plugins or AGENTS.md. Machine facts live in a machine profile. Project facts live in the project.

Keeping those separate is the whole point. When tastes are mixed into infra rules, every new machine or project re-derives them.

What goes in

• Identity and role (operator, not persona)
• Current priorities and active projects
• Communication preferences (terse vs detailed, language)
• Hard constraints ("never force push to main", "ask before publishing")
• Things I have already decided (so the agent does not re-litigate them)

What stays out

• Tool configuration and hooks (plugins/AGENTS.md)
• Machine-specific paths (machine profile)
• Project architecture (project AGENTS.md)

A template

I published a template at farishan/user-md that you can use as a starting point. It is intentionally small: around one to one-and-a-half thousand tokens. Bigger profiles get ignored or truncated.

Demand, not hype

I held off on a paid product until I saw real demand. The signal I watch: how often I (or others) re-explain the same preferences to a new agent. Three or more signals means the problem is real. So far the signals are there, so Phase 2 (a Gumroad listing) is in prep.

Try it

1. Create USER.md in your home or project root.
2. Add five lines: who you are, what you are building, how you want answers, one constraint, one preference.
3. Point your agent at it in the system prompt or AGENTS.md.

The first time an agent stops asking "should I use tabs or spaces?" you will know it worked.