user-md-guide

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

USER.md 建構引導 — 給 Agent 用的個人檔案

USER.md Construction Guide — Personal Profile for Agents

本 skill 協助初次使用者一步步完成 USER.md，讓 Cursor、nanobot 或其他 agent 能根據「你是誰、你的偏好、你的情境」提供更個人化的協助。採用融合風格：兼顧「人本敘事」（About your human）與「結構化偏好」（溝通風格、技術程度、工作情境）。

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

第一次要為工作區或 agent 建立 USER.md
想統一「給 AI 看的個人設定」、避免多套格式並存
不確定該寫「輕鬆介紹自己」還是「勾選偏好」——本引導兩者都涵蓋

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

USER.md 是什麼

What is USER.md

USER.md

是給 agent 讀的個人檔案，描述「正在協助的這個人」：稱呼、時區、溝通偏好、工作情境、地雷與笑點等。Agent 會在 bootstrap 或個人化時讀取，用來調整語氣、長度與建議方向。本引導產出的格式同時適用 Cursor 系工具與 nanobot 等結構化解析。

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)

步驟 1：確認檔案位置與標題

Step 1: Confirm File Location and Title

路徑：工作區根目錄的
```
USER.md
```
，或專案/環境約定位置（例如
```
~/.nanobot/workspace/USER.md
```
若使用 nanobot）。

標題：建議使用

# USER.md — About Your Human

或

# 給 Agent 的個人檔案

，讓 agent 一眼辨識。

先詢問：「這份 USER.md 會放在哪個專案或目錄？希望標題用英文還是中文？」

Path:
```
USER.md
```
in the root directory of the workspace, or a location specified by the project/environment (e.g.,
```
~/.nanobot/workspace/USER.md
```
if using nanobot).
Title: Recommended to use
```
# USER.md — About Your Human
```
or
```
# 给 Agent 的个人档案
```
(Personal Profile for Agents) so agents can recognize it at a glance.

First ask: "Which project or directory will this USER.md be placed in? Do you want the title in English or Chinese?"

步驟 2：填寫「基本資訊」（必填）

Step 2: Fill in "Basic Information" (Required)

對應融合版區塊 Basic Information。逐項引導填寫，必要時給範例：

欄位	說明	範例
Name	真實名字或暱稱	小明、Wei
What to call them	Agent 該怎麼稱呼你	「請叫我小華」
Pronouns	代名詞（選填）	they/them、他/她
Timezone	時區	UTC+8、Asia/Taipei
Language	偏好語言	繁體中文、English
Notes	一兩句備註	「常熬夜，下午才回訊息」

引導方式：一次問 1～2 個欄位，避免一次丟整張表。可問：「你希望 agent 怎麼稱呼你？」「你主要在哪個時區活動？」

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?"

步驟 3：選擇「偏好」（結構化，選填）

Step 3: Select "Preferences" (Structured, Optional)

對應融合版的 Preferences，用勾選讓 agent 知道溝通風格、回答長度與技術程度。向對方說明：「勾選你當下最符合的即可，之後可改。」

Communication Style：Casual / Professional / Technical（可多選或單選，依實作而定）
Response Length：Brief and concise / Detailed explanations / Adaptive based on question
Technical Level：Beginner / Intermediate / Expert

引導方式：問「你比較喜歡簡短回答還是詳細說明？」「你覺得自己目前是初學、中階還是進階？」再代為轉成對應勾選。

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.

步驟 4：填寫「工作情境」（選填）

Step 4: Fill in "Work Context" (Optional)

對應融合版 Work Context：角色、主要專案、常用工具。幫助 agent 在給建議時對齊你的情境。

Primary Role：例如學生、開發者、研究者
Main Projects：目前在做什麼（一兩句或條列）
Tools They Use：常用 IDE、語言、框架

引導方式：問「你現在主要身份是什麼？在忙什麼專案？」「平常寫程式用什麼語言或工具？」

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?"

步驟 5：撰寫「Context」（人本敘事，建議填）

Step 5: Write "Context" (Human-Centric Narrative, Recommended)

對應融合版 Context：自由文字，描述「這個人在乎什麼、討厭什麼、什麼會笑」。隨時間更新，不必一次寫完。

在乎的事、正在煩惱的
地雷（不喜歡的語氣或假設）
喜歡的互動方式、笑點或梗

引導方式：問「你希望 agent 特別記得什麼關於你的事？」「有什麼地雷或偏好要提醒 agent？」強調「這是給 agent 了解你這個人，不是交作業，可以之後慢慢補。」

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."

步驟 6：填寫「Special Instructions」與「Topics of Interest」（選填）

Step 6: Fill in "Special Instructions" and "Topics of Interest" (Optional)

Special Instructions：給 agent 的明確行為指示，例如「回答請用繁體中文」「不要假設我有 CLI 經驗」。
Topics of Interest：三兩項你常問或想深入的主題，方便 agent 預判方向。

引導方式：問「有沒有你希望 agent 一定遵守的規則？」「你最近常問或想學的主題有哪些？」

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?"

步驟 7：收尾與檢查

Step 7: Wrap-Up and Review

存檔：確認
```
USER.md
```
在約定路徑、副檔名為
```
.md
```
。
結構檢查：至少具備「基本資訊」與「Context」或「Preferences」其一；若有 YAML frontmatter，確認格式正確。
用語一致：若專案已有 AGENTS.md 或其它術語，與 USER.md 用詞一致。

Save the File: Confirm
```
USER.md
```
is in the agreed path with the
```
.md
```
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)

引導時可依步驟逐步產出，或最後給對方一份完整範本供複製後自行填寫。以下為融合版結構，含 YAML 與區塊標題。

markdown

---
summary: "User profile — preferences and context for personalized assistance"
read_when:
  - Bootstrapping a workspace manually
  - Personalizing nanobot or agent behavior
---

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)

Name:
What to call them:
Pronouns: (optional)
Timezone: (e.g. UTC+8)
Language: (preferred)
Notes: (short note or reminder)

Preferences

Communication Style

Response Length

Technical Level

Work Context

Primary Role: (e.g. developer, student, researcher)
Main Projects: (what they're working on)
Tools They Use: (IDEs, languages, frameworks)

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.

---

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

「這份 USER.md 會放在哪個專案或目錄？標題想用英文還是中文？」
「你希望 agent 怎麼稱呼你？用什麼語言跟你對話？」
「你比較喜歡簡短回答還是詳細說明？你覺得自己目前是初學、中階還是進階？」
「你現在主要身份是什麼？在忙什麼專案？用什麼工具？」
「有沒有你希望 agent 特別記得的事、或一定不要踩的地雷？」
「有沒有希望 agent 一定遵守的規則？最近常問或想學的主題？」

依回答逐段產出對應的 USER.md 內容，並建議貼到約定路徑後再微調。

"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

完成後可協助對方確認：

檔案名為
```
USER.md
```
，位於約定目錄（工作區根目錄或環境指定路徑）
至少具備「基本資訊」與「Context」或「Preferences」其一
若使用 nanobot 或會解析 frontmatter 的工具，已加上 YAML 與
```
read_when
```
用語與專案／AGENTS.md 一致，長度適中，方便日後維護

After completion, you can help the user confirm:

The file is named
```
USER.md
```
and located in the agreed directory (workspace root or environment-specified path)
At least includes "Basic Information" and either "Context" or "Preferences"
If using nanobot or tools that parse frontmatter, YAML and
```
read_when
```
have been added
Terminology is consistent with the project/AGENTS.md, length is moderate, and it's easy to maintain in the future