From 16327dec7202f2acb0ce890836d95d47ab019813 Mon Sep 17 00:00:00 2001
From: root <root@minecraft-server>
Date: Thu, 16 Apr 2026 17:25:24 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0README=20-=20?=
 =?UTF-8?q?=E4=BF=AE=E6=AD=A3Skill=E5=90=8D=E7=A7=B0=E5=B9=B6=E6=B7=BB?=
 =?UTF-8?q?=E5=8A=A0Skill=E5=AE=9A=E4=B9=89=E6=A0=BC=E5=BC=8F=E8=AF=B4?=
 =?UTF-8?q?=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 修正Skill列表中的名称：persona/task（WaterFlow使用目录名）
- 添加Skill定义格式说明，解释WaterFlow如何解析SKILL.md
- 说明name/description/allowed-tools等字段的提取规则
- 中英文版本同步更新
---
 README.md    | 16 ++++++++++++++--
 README_EN.md | 16 ++++++++++++++--
 2 files changed, 28 insertions(+), 4 deletions(-)

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().
 
 ---