diff --git a/docs/en/guides/skills.md b/docs/en/guides/skills.md
index b3b0853..89cd0e5 100644
--- a/docs/en/guides/skills.md
+++ b/docs/en/guides/skills.md
@@ -32,7 +32,6 @@ KODE SDK provides a complete Skills system supporting modular, reusable capabili
 .skills/
 ├── skill-name/              # Skill directory
 │   ├── SKILL.md            # Skill definition (required)
-│   ├── metadata.json       # Skill metadata (optional)
 │   ├── references/         # Reference documents
 │   ├── scripts/            # Executable scripts
 │   └── assets/             # Static resources
@@ -42,10 +41,13 @@ KODE SDK provides a complete Skills system supporting modular, reusable capabili
 
 ### SKILL.md Format
 
+SKILL.md uses YAML frontmatter format for metadata, followed by Markdown content:
+
 ```markdown
-<!-- skill: skill-name -->
-<!-- version: 1.0.0 -->
-<!-- author: Your Name -->
+---
+name: skill-name
+description: Skill description
+---
 
 # Skill Name
 
@@ -61,17 +63,14 @@ Brief description of the skill's functionality.
 Detailed instructions for using this skill...
 ```
 
-### metadata.json Format
+**Field Reference:**
 
-```json
-{
-  "name": "skill-name",
-  "description": "Skill description",
-  "version": "1.0.0",
-  "author": "Author",
-  "baseDir": "/path/to/skill"
-}
-```
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Skill identifier, must match the directory name |
+| `description` | Yes | Skill description, used for system prompt injection |
+
+> **Note**: Agent runtime uses the folder name as the skill identifier; management operations require the `name` field in YAML frontmatter.
 
 ---
 
diff --git a/docs/zh-CN/guides/skills.md b/docs/zh-CN/guides/skills.md
index 88c3869..f6cdfbf 100644
--- a/docs/zh-CN/guides/skills.md
+++ b/docs/zh-CN/guides/skills.md
@@ -32,7 +32,6 @@ KODE SDK 提供完整的 Skills 系统，支持模块化、可重用的能力单
 .skills/
 ├── skill-name/              # 技能目录
 │   ├── SKILL.md            # 技能定义（必需）
-│   ├── metadata.json       # 技能元数据（可选）
 │   ├── references/         # 参考资料
 │   ├── scripts/            # 可执行脚本
 │   └── assets/             # 静态资源
@@ -42,10 +41,13 @@ KODE SDK 提供完整的 Skills 系统，支持模块化、可重用的能力单
 
 ### SKILL.md 格式
 
+SKILL.md 使用 YAML frontmatter 格式声明元数据， 跟着 Markdown 正文：
+
 ```markdown
-<!-- skill: skill-name -->
-<!-- version: 1.0.0 -->
-<!-- author: Your Name -->
+---
+name: skill-name
+description: 技能描述
+---
 
 # 技能名称
 
@@ -61,17 +63,14 @@ KODE SDK 提供完整的 Skills 系统，支持模块化、可重用的能力单
 使用此技能的详细说明...
 ```
 
-### metadata.json 格式
+**字段说明：**
 
-```json
-{
-  "name": "skill-name",
-  "description": "技能描述",
-  "version": "1.0.0",
-  "author": "作者",
-  "baseDir": "/path/to/skill"
-}
-```
+| 字段 | 必需 | 说明 |
+|------|------|------|
+| `name` | 是 | 技能标识符，必须与目录名一致 |
+| `description` | 是 | 技能描述，用于系统提示词注入 |
+
+> **注意**：Agent 运行时使用文件夹名称作为技能标识符；管理操作要求 YAML frontmatter 中必须包含 `name` 字段。
 
 ---