From 120d616ca576c4d70d6fbafde1c8baf91e775d47 Mon Sep 17 00:00:00 2001
From: FenjuFu <92919259+FenjuFu@users.noreply.github.com>
Date: Thu, 17 Sep 2026 13:48:25 +0800
Subject: [PATCH] docs(publish): correct skill package metadata requirements

---
 docs/skillhub/en/guide/skill-publish.md | 26 +++++++++++++++++++++----
 docs/skillhub/guide/skill-publish.md    | 25 ++++++++++++++++++++----
 2 files changed, 43 insertions(+), 8 deletions(-)

diff --git a/docs/skillhub/en/guide/skill-publish.md b/docs/skillhub/en/guide/skill-publish.md
index 3224f4d7..be9e3902 100644
--- a/docs/skillhub/en/guide/skill-publish.md
+++ b/docs/skillhub/en/guide/skill-publish.md
@@ -49,10 +49,28 @@ New version has serious issues, need to point `latest` tag to previous stable ve
 
 1. **Prepare Skill Package**
 
-Ensure skill package conforms to SkillHub specification:
-- Contains `skill.md` (skill description)
-- Contains `package.json` or `SKILL.md` (metadata)
-- Clear file structure, no sensitive information
+Prepare a skill directory with `SKILL.md` at its root:
+
+- Put both YAML frontmatter and the skill instructions in `SKILL.md`.
+- The frontmatter must contain `name` and `description`. Set `version` there when you need an explicit version.
+- `package.json` does not supply or replace this skill metadata.
+- Keep the package structure clear and exclude sensitive information.
+
+For example, save this as `my-skill/SKILL.md`:
+
+```markdown
+---
+name: my-skill
+description: Summarize a short text as numbered steps.
+version: 1.0.0
+---
+
+Summarize the supplied text as numbered steps.
+```
+
+When packaging an existing skill, keep its required scripts, references,
+`agents/` metadata, and license files together. Pass that skill directory
+(`./my-skill` in this example) to the publish command below.
 
 2. **Publish via CLI (Recommended)**
 
diff --git a/docs/skillhub/guide/skill-publish.md b/docs/skillhub/guide/skill-publish.md
index 72249d60..8d77fcf8 100644
--- a/docs/skillhub/guide/skill-publish.md
+++ b/docs/skillhub/guide/skill-publish.md
@@ -49,10 +49,27 @@ SkillHub 提供了类似 npm 的发布体验，但增加了企业级的权限控
 
 1. **准备技能包**
 
-确保技能包符合 SkillHub 规范：
-- 包含 `skill.md`（技能描述）
-- 包含 `package.json` 或 `SKILL.md`（元数据）
-- 文件结构清晰，无敏感信息
+准备一个根目录包含 `SKILL.md` 的技能目录：
+
+- 在 `SKILL.md` 中同时编写 YAML frontmatter 和技能指令。
+- frontmatter 必须包含 `name` 和 `description`；需要指定版本时，在其中设置 `version`。
+- `package.json` 不会提供或替代这些技能元数据。
+- 保持文件结构清晰，不包含敏感信息。
+
+例如，将以下内容保存为 `my-skill/SKILL.md`：
+
+```markdown
+---
+name: my-skill
+description: Summarize a short text as numbered steps.
+version: 1.0.0
+---
+
+Summarize the supplied text as numbered steps.
+```
+
+打包已有技能时，应一并保留其所需的脚本、参考文件、`agents/` 元数据和许可证文件。
+下一步发布命令的路径应指向该技能目录（本例为 `./my-skill`）。
 
 2. **使用 CLI 发布（推荐）**