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

• Create USER.md in your home or project root.
• Add five lines: who you are, what you are building, how you want answers, one constraint, one preference.
• 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.