User & Identity Files: Teaching Your Agent Who You Are

Every time you start a new conversation with an AI model, it knows nothing about you. It does not know your name, your role, your projects, or how you like to communicate. You start from zero every single time. The user file and identity file solve this problem by giving your agent permanent context about who you are and what it is.

The User File: A Profile Document About You

The user.md file is a comprehensive document about you — the person the agent serves. Think of it as a detailed briefing that gets loaded into the agent's context at the start of every interaction.

Here is an example structure:

# user.md

name: Sarah Chen
role: Senior Backend Engineer at Nexus Labs
timezone: America/Los_Angeles (Pacific Time)

communication_style:
  - Direct and concise — skip unnecessary pleasantries
  - Use technical terminology without simplifying
  - When explaining trade-offs, use tables

current_projects:
  - Project Atlas: migrating monolith to microservices (lead)
  - Internal CLI tooling for deployment automation
  - Mentoring two junior engineers

goals:
  - Ship Atlas Phase 2 by end of Q2
  - Reduce deployment time from 45 minutes to under 10
  - Write one technical blog post per month

preferences:
  - Prefer Python for scripting, Go for services
  - Use conventional commits for all repositories
  - Morning hours (7-11 AM) are deep work — no meetings

What to include depends on what you want the agent to do for you. If your agent manages your calendar, include your scheduling preferences. If it reviews code, include your coding standards. The more relevant detail you provide, the more personalized the agent's responses become.

The Identity File: What the Agent Is

The identity.md file defines the agent itself — not you, but the agent's name, role, and core mission. This is typically a concise description, often just five lines:

# identity.md

name: Atlas
role: Engineering operations assistant
serves: Sarah Chen (Senior Backend Engineer)
mission: Streamline engineering workflows, automate repetitive tasks, and surface actionable insights from project data.
style: Technical, precise, proactive — surfaces problems before they escalate.

This file answers the question every agent needs to answer: "What am I, and what am I here to do?" Without this, the agent defaults to being a generic assistant. With it, the agent has a focused purpose that shapes every interaction.

The Identity Interview Approach

Writing these files from scratch can feel overwhelming. A practical technique is the identity interview — a structured set of questions that generate the content for both files.

For the user file, answer questions like:

• What is your name and professional role?
• What are you working on right now?
• How do you prefer to receive information (bullet points, detailed explanations, tables)?
• What tools and languages do you use daily?
• What are your top three priorities this quarter?

For the identity file, answer questions like:

• What should the agent be called?
• What is its primary job?
• Who does it serve?
• What is its one-sentence mission?
• What tone should it use?

Some agent frameworks automate this process. During initial setup, the framework asks you these questions conversationally and generates both files from your answers. Whether automated or manual, the result is the same: structured context that persists across every session.

Why This Context Matters

Without user and identity files, every interaction starts cold. The agent does not know that you prefer Go over Java, that you are leading a migration project, or that you hate verbose explanations. It will ask questions you have already answered, suggest tools you do not use, and communicate in a generic tone.

With these files loaded, the agent:

• Skips redundant questions — it already knows your stack and preferences
• Tailors its output — code examples in your preferred language, responses in your preferred format
• Maintains continuity — it references your active projects and goals without being reminded
• Acts with purpose — its identity file keeps it focused on its defined mission

The user file and identity file are the foundation of the agent's context system. Everything else — soul configuration, memory, operational rules — builds on top of this base layer.

Key takeaway: The user file teaches the agent about you. The identity file teaches the agent about itself. Together, they transform a generic AI into a personalized, purpose-driven assistant that remembers who it serves and why it exists.

Next: Defining your agent's personality, values, and boundaries with soul configuration. :::