user.md: teach your agent who it serves

user.md is the file that tells your agent who it serves. It holds your name and role, your goals, how you like to be spoken to, and what the agent is allowed to access. Harnesses inject it into the part of the system prompt reserved for user context, so the agent can tailor its first answer instead of learning you from scratch every session.

Why the agent needs to know you

A capable agent without user.md is like a skilled new colleague on their first day, every day. They do good work, but they do not know whether you want the headline or the detail, whether you are a beginner or an expert, or which projects matter this month. user.md fixes that. It is the difference between an assistant that is competent and one that is yours.

The five fields

• userName: what the agent should call you. A first name, a nickname, or a title — whatever you want to hear.
• userRole: what you do, in the context the agent works in. “Product designer at a small studio”, “second-year medical student”, “parent running a busy household”.
• userGoals: what you are trying to achieve right now. Specific beats general: “ship the onboarding redesign by December” is more useful than “be productive”.
• userPrefs: how you like to be spoken to. Length, tone, language, whether you want options or a single recommendation, whether to explain the reasoning.
• userAccess: what the agent may and may not touch — files, accounts, tools, decisions it can make alone and decisions it must bring to you.

What AgentSoul fills in for you

A Gao Dao user.md starts with an Enneagram summary — your type, wing and subtype — followed by what you care about (core desire, core fear, and a tendency to watch), your communication preferences, and notes on how to work with you, including signs that you are thriving or drifting. Flash Forge writes a shorter version focused on your communication preferences and working rhythm, read from the way you actually write in your chats. Those preferences follow from your reading: where a type is given, a Type 1 might prefer precise communication that separates principle from preference; a Type 7 might prefer idea-rich communication that opens options. This is the part an agent struggles to guess, and it is the part a forge is good at.

What only you can add

A forge reads patterns; it does not know your calendar. Open user.md after forging and add the facts that make the agent immediately useful:

1. Your name as you want to be addressed, and the language you prefer — for example, replies in Chinese with technical terms in English.
2. Your role and the context you will use this agent in.
3. Two or three current goals, phrased concretely.
4. Access boundaries: what the agent may do on its own, and what it must always ask about first.
5. Anything it should never assume, such as your location or your schedule.

Keep it current and private

Goals change faster than personality, so user.md is the file you will edit most. A quick monthly review keeps it honest. It is also the most personal of the four files. The AgentSoul app keeps your souls on your iPhone, tied to an anonymous device ID with no account, and you can remove everything with Delete my data in Settings. Once you send the files to a computer or paste them into another service, though, they live wherever you put them. Read user.md before you share it, and leave out what you would rather keep to yourself.

As with every AgentSoul file, the reading behind user.md is an AI-generated hypothesis, not a diagnosis. If a preference it lists does not describe you, change it.