diff --git a/skills/create-agent/SKILL.md b/skills/create-agent/SKILL.md
index 415d60b..e1ba8ff 100644
--- a/skills/create-agent/SKILL.md
+++ b/skills/create-agent/SKILL.md
@@ -245,6 +245,37 @@ create-agent 是一个**元技能（Meta-Skill）**，赋予 DesireCore 创建
 > - 为它添加技能，让它更强大
 > - 调整它的性格或行为规则
 
+### 背景知识：AgentFS 仓库结构
+
+> 以下信息仅供 Agent 内部理解，**不要向用户展示**。
+> 用于创建后的验证、排查问题、以及后续精细化维护。
+
+创建后的 Agent 仓库遵循 AgentFS v2 扁平结构：
+
+```
+<agent_id>/
+├── agent.json        # 元数据与运行时配置
+├── persona.md        # 人格定义（L0/L1/L2）
+├── principles.md     # 行为原则（L0/L1/L2）
+├── memory/           # 记忆目录
+├── skills/           # 技能目录
+├── tools/            # 工具目录
+└── heartbeat/        # 心跳配置
+```
+
+**排查要点**：
+
+| 文件 | 验证方式 | 常见问题 |
+|------|---------|---------|
+| `agent.json` | `GET /api/agents/:id` 返回完整配置 | engine 字段缺失导致无法启动 |
+| `persona.md` | `GET /api/agents/:id/persona` 返回结构化数据 | L0 为空则 Agent 无身份摘要 |
+| `principles.md` | `GET /api/agents/:id/principles` 返回结构化数据 | must_not 为空则无安全红线 |
+| `memory/` | 目录存在即可 | `_policy.json` 缺失会使用默认策略 |
+
+**受保护路径**（不可自动修改）：
+- `persona.md` L0 section — 核心身份
+- `principles.md` "绝不做" section — 安全红线
+
 ### 错误处理
 
 | 错误码 | 场景 | 处理方式 |