diff --git a/README.md b/README.md
index 0327460..15d13eb 100644
--- a/README.md
+++ b/README.md
@@ -131,8 +131,20 @@ AI Agent 会自动读取 SKILL.md 并调用 `builtin:graph_memory` 工具。
 | Skill 名称 | 功能 | 使用场景 |
 |------------|------|----------|
 | `graph_memory` | 记忆 CRUD | 读取/写入/删除记忆 |
-| `graph_memory_persona` | 人设管理 | 设置 AI 角色性格 |
-| `graph_memory_task` | 任务管理 | 创建/更新长期任务 |
+| `persona` | 人设管理 | 设置 AI 角色性格 |
+| `task` | 任务管理 | 创建/更新长期任务 |
+
+#### Skill 定义格式说明
+
+WaterFlow 的 SkillLoader 会从 `SKILL.md` 中提取：
+
+- **name**: 从目录名提取（如 `graph_memory`、`persona`、`task`）
+- **description**: 从 Markdown 的第一个 `#` 标题提取
+- **allowed-tools**: 转换为 `allowedTools` 字段
+- **arguments**: 正确映射到 SkillDefinition.arguments
+- **user-invocable**: 转换为 `userInvocable` 字段
+
+**注意**: `when_to_use` 信息已整合到 Markdown body 中，通过 SkillRegistry.search() 可匹配。
 
 ---
 
diff --git a/README_EN.md b/README_EN.md
index fafffe6..27e3568 100644
--- a/README_EN.md
+++ b/README_EN.md
@@ -132,8 +132,20 @@ AI Agent automatically reads SKILL.md and calls `builtin:graph_memory` tool.
 | Skill Name | Function | Use Case |
 |------------|----------|----------|
 | `graph_memory` | Memory CRUD | Read/Write/Delete memories |
-| `graph_memory_persona` | Persona management | Set AI role/personality |
-| `graph_memory_task` | Task management | Create/update long-term tasks |
+| `persona` | Persona management | Set AI role/personality |
+| `task` | Task management | Create/update long-term tasks |
+
+#### Skill Definition Format
+
+WaterFlow's SkillLoader extracts from `SKILL.md`:
+
+- **name**: Extracted from directory name (e.g., `graph_memory`, `persona`, `task`)
+- **description**: Extracted from first Markdown `#` heading
+- **allowed-tools**: Converted to `allowedTools` field
+- **arguments**: Properly mapped to SkillDefinition.arguments
+- **user-invocable**: Converted to `userInvocable` field
+
+**Note**: `when_to_use` info is integrated into Markdown body, searchable via SkillRegistry.search().
 
 ---