docs(faq): add CLI publish & deployment Q&A (zh & en)

Add more community-sourced questions (both Chinese and English):

- Troubleshooting CLI `skillhub publish` returning 400 (name conflict,
  SKILL.md location/frontmatter, namespace membership, etc.)
- Required skill package structure (SKILL.md in root)
- "malformed input" on publish caused by non-UTF-8 / Chinese-path zips
- Per-package file-count limit and how to raise it
- Minimum server version for CLI features (v0.2.7+)
- PostgreSQL-only (no MySQL); plugins not distributable yet
- How to check server/CLI versions and customize via secondary dev

Signed-off-by: FenjuFu <fufenjupku@gmail.com>

docs/skillhub/en/faq.md

@@ -186,6 +186,66 @@ A: SkillHub has built-in security scanning. The scanner integration, task orches
 
 A: `scanner/Dockerfile` runs `pip install cisco-ai-skill-scanner` directly without pinning a version, so the latest version on PyPI is pulled when the image is built. To pin a version, do so yourself when customizing the build.
 
+## Q: How do I troubleshoot a `registry returned 400` error from `skillhub publish` (CLI)?
+
+A: A 400 usually means backend validation failed. Common causes:
+
+- `SKILL.md` is not in the package root directory;
+- `SKILL.md` frontmatter is missing `name` / `description` or is malformed;
+- name or version conflict (e.g. `error.skill.publish.nameConflict`, meaning a skill with the same name is already published in that namespace) — change `name` in `SKILL.md`, use another namespace, or have an admin handle the existing skill;
+- the namespace does not exist, or you are not a member of it;
+- the package contains suspected tokens/secrets that the CLI cannot confirm skipping;
+- file type / size / path is not allowed.
+
+You can inspect the server logs to locate the cause:
+
+```bash
+docker logs --tail=300 <skillhub-server container> 2>&1 | grep -Ei 'publish|SKILL.md|namespace|400|BadRequest'
+```
+
+## Q: What directory structure does a skill package require?
+
+A: The package root directory must contain a `SKILL.md` file, whose frontmatter must include fields such as `name` and `description`.
+
+## Q: Publishing fails with "package validation failed / malformed input" — what do I do?
+
+A: This error occurs while unzipping and reading file names, usually because the archive is not UTF-8 encoded (e.g. created with the built-in Windows compression tool) or contains Chinese/non-ASCII paths. Repackage using UTF-8 encoding and avoid Chinese / special-character paths.
+
+## Q: How many files can a skill package contain? What if I hit the file-count limit?
+
+A: The default limit is **100 files** (this is separate from the 100MB size limit). To raise it, change the `skillhub.publish.max-file-count` setting, or override it via an environment variable at deploy time:
+
+```bash
+SKILLHUB_PUBLISH_MAX_FILE_COUNT=500
+```
+
+Restart the containers for the change to take effect. Note that `compose.release.yml` must also reference this variable; older versions (e.g. v0.2.6) may hard-code the value, so upgrading to the latest version is recommended.
+
+## Q: Is there a server version requirement for using the CLI (publish / download, etc.)?
+
+A: A SkillHub server image of **v0.2.7 or later** is required for CLI features.
+
+## Q: Does SkillHub support MySQL?
+
+A: Currently only PostgreSQL is supported; MySQL is not supported.
+
+## Q: Can SkillHub be used to distribute Plugins?
+
+A: Not supported for now.
+
+## Q: How do I check the SkillHub version? How do I customize it (e.g. change the logo)?
+
+A:
+
+- Check the server image version:
+
+```bash
+docker image inspect ghcr.io/iflytek/skillhub-server:latest --format '{{index .Config.Labels "org.opencontainers.image.version"}}'
+```
+
+- Check the CLI version: `skillhub version`.
+- For customization (e.g. changing the logo), it is recommended to fork the latest code, modify it, and build your own Docker image.
+
 ## Q: What should I do if I encounter issues?
 
 A: You can get help through the following channels:

docs/skillhub/faq.md

@@ -186,6 +186,66 @@ A: SkillHub 内置安全扫描能力。其中扫描接入、任务编排、审
 
 A: `scanner/Dockerfile` 中直接执行 `pip install cisco-ai-skill-scanner`，未锁定版本，因此构建镜像时会拉取 PyPI 上的最新版本。如需固定版本，可在二次开发时自行锁定。
 
+## Q: 使用 CLI `skillhub publish` 报错 `registry returned 400` 怎么排查？
+
+A: 400 通常是后端校验未通过。常见原因：
+
+- `SKILL.md` 不在技能包根目录；
+- `SKILL.md` 的 frontmatter 缺少 `name` / `description` 或格式错误；
+- 名称或版本冲突（如 `error.skill.publish.nameConflict`，表示该 namespace 下已存在同名的已发布技能）——可改 `SKILL.md` 里的 `name`、换一个 namespace，或让管理员处理已有同名技能；
+- namespace 不存在，或你不是该 namespace 的成员；
+- 包内含疑似 token/secret，CLI 无法确认跳过；
+- 文件类型 / 大小 / 路径不合规。
+
+可用以下命令查看服务端日志定位：
+
+```bash
+docker logs --tail=300 <skillhub-server 容器名> 2>&1 | grep -Ei 'publish|SKILL.md|namespace|400|BadRequest'
+```
+
+## Q: 技能包的目录结构有什么要求？
+
+A: 技能包根目录必须包含一个 `SKILL.md` 文件，且其 frontmatter 需包含 `name`、`description` 等字段。
+
+## Q: 发布时报“技能包校验失败 / malformed input”怎么办？
+
+A: 该错误发生在 zip 解包读取文件名阶段，通常是压缩包不是 UTF-8 编码（例如用 Windows 自带压缩工具生成）或包内含中文路径导致。请使用 UTF-8 编码重新打包，并避免中文 / 特殊字符路径。
+
+## Q: 技能包能包含多少个文件？提示文件数超限怎么办？
+
+A: 默认上限为 **100 个文件**（这与 100MB 的大小限制是两回事）。如需放宽，修改配置项 `skillhub.publish.max-file-count`，或在部署时用环境变量覆盖：
+
+```bash
+SKILLHUB_PUBLISH_MAX_FILE_COUNT=500
+```
+
+修改后需重启容器生效。注意 `compose.release.yml` 中也需引用该变量；较旧版本（如 v0.2.6）可能将该值写死，建议升级到最新版本。
+
+## Q: 使用 CLI（发布 / 下载等）对服务端版本有要求吗？
+
+A: 需要 SkillHub 服务端镜像 **v0.2.7 及以上** 才支持 CLI 功能。
+
+## Q: SkillHub 支持 MySQL 数据库吗？
+
+A: 目前仅支持 PostgreSQL，暂不支持 MySQL。
+
+## Q: SkillHub 可以用来分发 Plugin 吗？
+
+A: 暂不支持。
+
+## Q: 如何查看 SkillHub 的版本？想做定制（如修改 logo）怎么办？
+
+A:
+
+- 查看服务端镜像版本：
+
+```bash
+docker image inspect ghcr.io/iflytek/skillhub-server:latest --format '{{index .Config.Labels "org.opencontainers.image.version"}}'
+```
+
+- 查看 CLI 版本：`skillhub version`。
+- 如需定制（如修改 logo 等），建议基于最新代码进行二次开发并自行构建 docker 镜像。
+
 ## Q: 遇到问题怎么办？
 
 A: 可以通过以下方式获取帮助：