USER.md Construction Guide — Personal Profile for Agents
This skill helps first-time users complete USER.md step by step, enabling Cursor, nanobot or other agents to provide more personalized assistance based on "who you are, your preferences, and your context". It adopts an integrated style: combining both "human-centric narrative" (About your human) and "structured preferences" (communication style, technical proficiency, work context).
When to Use This Guide
- Creating a USER.md for a workspace or agent for the first time
- Wanting to unify "personal settings for AI" and avoid multiple coexisting formats
- Unsure whether to write a "casual introduction of yourself" or "check off preferences" — this guide covers both
What is USER.md
is a
personal profile for agents to read, describing "the person being assisted": name, timezone, communication preferences, work context, pet peeves and inside jokes, etc. Agents will read it during bootstrapping or personalization to adjust their tone, response length and suggestion directions. The format generated by this guide is compatible with Cursor-based tools and structured parsing tools like nanobot.
Writing Process (Follow in Order)
Step 1: Confirm File Location and Title
- Path: in the root directory of the workspace, or a location specified by the project/environment (e.g.,
~/.nanobot/workspace/USER.md
- Title: Recommended to use
# USER.md — About Your Human
First ask: "Which project or directory will this USER.md be placed in? Do you want the title in English or Chinese?"
Step 2: Fill in "Basic Information" (Required)
Corresponds to the Basic Information section in the integrated version. Guide users to fill in each item, providing examples when necessary:
| Field | Description | Example |
|---|
| Name | Real name or nickname | Xiao Ming, Wei |
| What to call them | How the agent should address you | "Please call me Xiao Hua" |
| Pronouns | Pronouns (optional) | they/them, he/she |
| Timezone | Timezone | UTC+8、Asia/Taipei |
| Language | Preferred language | Traditional Chinese, English |
| Notes | 1-2 short notes | "Often stays up late, replies in the afternoon" |
Guidance Method: Ask 1-2 fields at a time to avoid overwhelming the user. You could ask: "How do you want the agent to address you?" "Which timezone do you primarily operate in?"
Step 3: Select "Preferences" (Structured, Optional)
Corresponds to the Preferences section in the integrated version. Use checkboxes to let agents know your communication style, response length and technical proficiency. Explain to the user: "Just check the option that best fits you right now; you can change it later."
- Communication Style: Casual / Professional / Technical (can select multiple or single, depending on implementation)
- Response Length: Brief and concise / Detailed explanations / Adaptive based on question
- Technical Level: Beginner / Intermediate / Expert
Guidance Method: Ask "Do you prefer short answers or detailed explanations?" "Would you consider yourself a beginner, intermediate, or expert right now?" Then convert the answers into the corresponding checkmarks.
Step 4: Fill in "Work Context" (Optional)
Corresponds to the Work Context section in the integrated version: role, main projects, commonly used tools. Helps agents align their suggestions with your context.
- Primary Role: e.g., student, developer, researcher
- Main Projects: What you're currently working on (1-2 sentences or bullet points)
- Tools They Use: Commonly used IDEs, languages, frameworks
Guidance Method: Ask "What is your current primary role? What projects are you working on?" "Which programming languages or tools do you usually use?"
Step 5: Write "Context" (Human-Centric Narrative, Recommended)
Corresponds to the Context section in the integrated version: free-form text describing "what this person cares about, what annoys them, what makes them laugh". Update it over time; you don't have to finish it all at once.
- Things you care about, things you're currently worried about
- Pet peeves (unliked tones or assumptions)
- Preferred interaction styles, inside jokes or memes
Guidance Method: Ask "Is there anything about yourself you want the agent to remember specifically?" "Are there any pet peeves or preferences you want to remind the agent of?" Emphasize "This is for the agent to get to know you as a person, not an assignment; you can add to it later."
Step 6: Fill in "Special Instructions" and "Topics of Interest" (Optional)
- Special Instructions: Clear behavioral instructions for the agent, e.g., "Please respond in Traditional Chinese" "Don't assume I have CLI experience".
- Topics of Interest: 2-3 topics you frequently ask about or want to dive deeper into, to help the agent predict directions.
Guidance Method: Ask "Are there any rules you want the agent to follow strictly?" "What topics have you been asking about or wanting to learn recently?"
Step 7: Wrap-Up and Review
- Save the File: Confirm is in the agreed path with the extension.
- Structure Check: At least include "Basic Information" and either "Context" or "Preferences"; if using YAML frontmatter, ensure the format is correct.
- Terminology Consistency: If the project already has an AGENTS.md or other related terms, keep the terminology consistent with USER.md.
Unified Template (Integrated Style)
You can generate content step by step during guidance, or provide the complete template for users to copy and fill in on their own. Below is the integrated structure, including YAML and section headers.
markdown
---
summary: "User profile — preferences and context for personalized assistance"
read_when:
- Bootstrapping a workspace manually
- Personalizing nanobot or agent behavior
---
# USER.md — About Your Human
_Learn about the person you're helping. Update this as you go._
## Basic Information
- **Name:**
- **What to call them:**
- **Pronouns:** _(optional)_
- **Timezone:** _(e.g. UTC+8)_
- **Language:** _(preferred)_
- **Notes:** _(short note or reminder)_
---
## Preferences
### Communication Style
- [ ] Casual
- [ ] Professional
- [ ] Technical
### Response Length
- [ ] Brief and concise
- [ ] Detailed explanations
- [ ] Adaptive based on question
### Technical Level
- [ ] Beginner
- [ ] Intermediate
- [ ] Expert
---
## Work Context
- **Primary Role:** _(e.g. developer, student, researcher)_
- **Main Projects:** _(what they're working on)_
- **Tools They Use:** _(IDEs, languages, frameworks)_
---
## Context
_(What do they care about? What annoys them? What makes them laugh? Build this over time.)_
---
## Special Instructions
_(Any specific instructions for how the assistant should behave.)_
---
## Topics of Interest
-
-
-
---
*Edit this file to customize behavior. The more you know, the better you can help — and remember to respect the person behind the profile.*
Key Questions to Ask During Guidance
- "Which project or directory will this USER.md be placed in? Do you want the title in English or Chinese?"
- "How do you want the agent to address you? Which language do you prefer to communicate in?"
- "Do you prefer short answers or detailed explanations? Would you consider yourself a beginner, intermediate, or expert right now?"
- "What is your current primary role? What projects are you working on? Which tools do you use?"
- "Is there anything about yourself you want the agent to remember specifically, or any strict pet peeves to avoid?"
- "Are there any rules you want the agent to follow strictly? What topics have you been asking about or wanting to learn recently?"
Generate the corresponding USER.md content section by section based on the answers, and suggest pasting it into the agreed path before making minor adjustments.
Final Checklist
After completion, you can help the user confirm: