diff --git a/docs/skillhub/en/faq.md b/docs/skillhub/en/faq.md
index 054e66164..51e3751fd 100644
--- a/docs/skillhub/en/faq.md
+++ b/docs/skillhub/en/faq.md
@@ -154,6 +154,10 @@ curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- u
 
 The script performs a series of initialization steps. The generated runtime configuration is located at `/tmp/skillhub-runtime/` by default (containing `.env.release` and the docker-compose file).
 
+## Q: What Kubernetes version does the Kubernetes deployment require?
+
+A: The official [Kubernetes deployment guide](./guide/kubernetes.md) requires Kubernetes **v1.24 or later**, a configured `kubectl`, and a default StorageClass for PVCs; an nginx ingress controller is needed if you want domain-based access. Older clusters have not been validated, so upgrade the cluster before deploying.
+
 ## Q: After deployment, I enter the correct username and password but get redirected back to the login page?
 
 A: This is most commonly seen with **manual deployment** (caused by API errors or incomplete initialization). Suggestions:
@@ -244,6 +248,12 @@ docker logs --tail=300 <skillhub-server container> 2>&1 | grep -Ei 'publish|SKIL
 
 A: The package root directory must contain a `SKILL.md` file, whose frontmatter must include fields such as `name` and `description`.
 
+## Q: Can a skill package contain API keys, tokens or other credentials?
+
+A: It is not recommended. Pre-publish validation detects what look like hard-coded tokens or secrets and blocks the publish or asks for confirmation (see the `registry returned 400` checklist above). Since v0.2.20, false positives for ordinary identifiers, function results, property access and string expressions have been reduced. This is a heuristic check covering only some file types and credential formats: it cannot guarantee that all real secrets are detected and does not automatically redact them. Check for and remove real credentials yourself before publishing.
+
+Instead, reference only the environment variable names or placeholders the skill needs, document the required credentials in `SKILL.md`, and let users configure the real values in the agent environment that runs the skill. SkillHub does not currently store or inject secrets for skills.
+
 ## 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.
@@ -322,6 +332,18 @@ A: Two common causes:
 docker compose --env-file .env.release -f compose.release.yml up -d --force-recreate
 ```
 
+## Q: Startup fails with `bind: address already in use` (port 80 is taken). What should I do?
+
+A: The official Compose file maps the web entry point to host port `80` and the API to port `8080`. When a port is taken, find the process with `netstat -tlnp` or `lsof -i :80`. If you cannot stop it, change the published ports in `.env.release` (the one-click script uses `${TMPDIR:-/tmp}/skillhub-runtime/.env.release`; if you set `SKILLHUB_HOME` or pass `--home`, use that directory instead):
+
+```bash
+WEB_PORT=8081
+# if 8080 is also taken
+API_PORT=18080
+```
+
+After changing ports, also set `SKILLHUB_PUBLIC_BASE_URL` to the real access URL including the new port (for example `http://your-host:8081`); otherwise login callbacks and other redirects may break. Then change to the actual runtime directory containing `.env.release` and `compose.release.yml`, and recreate the containers with `up -d --force-recreate` as described in the previous answer.
+
 ## Q: What external dependencies does SkillHub require at runtime?
 
 A: PostgreSQL and Redis are required. Object storage supports both `local` and S3, controlled by `SKILLHUB_STORAGE_PROVIDER`. `.env.release.example` explicitly selects `local`, but if the variable is completely unset when using `compose.release.yml`, the Compose fallback is `s3`. Set it explicitly; S3 is recommended for production (configured via `SKILLHUB_STORAGE_S3_*`). Only PostgreSQL is supported as the database — MySQL is not.
diff --git a/docs/skillhub/faq.md b/docs/skillhub/faq.md
index 7aeb70805..19e88b13f 100644
--- a/docs/skillhub/faq.md
+++ b/docs/skillhub/faq.md
@@ -154,6 +154,10 @@ curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- u
 
 脚本会执行一系列初始化操作，生成的运行时配置默认位于 `/tmp/skillhub-runtime/`（包含 `.env.release` 和 docker-compose 文件）。
 
+## Q: 用 Kubernetes 部署对集群版本有要求吗？
+
+A: 官方 [Kubernetes 部署指南](./guide/kubernetes.md) 要求 Kubernetes **v1.24 及以上**，并需要已配置好的 `kubectl` 与默认 StorageClass（用于 PVC）；如需域名访问，还需安装 nginx ingress controller。更低版本的集群未经验证，建议先升级集群再部署。
+
 ## Q: 部署后输入正确的账号密码，却又跳回登录页？
 
 A: 该现象多见于「手动部署」场景（接口异常或初始化未完成导致）。建议：
@@ -247,6 +251,12 @@ docker logs --tail=300 <skillhub-server 容器名> 2>&1 | grep -Ei 'publish|SKIL
 
 A: 技能包根目录必须包含一个 `SKILL.md` 文件，且其 frontmatter 需包含 `name`、`description` 等字段。
 
+## Q: 技能包里可以放 API Key、Token 等凭据吗？
+
+A: 不建议。发布前校验会识别疑似硬编码的 token / secret，并拦截或要求确认（见上文 `registry returned 400` 的排查项）；自 v0.2.20 起，已减少对普通标识符、函数返回值、属性访问和字符串表达式的误报。这只是针对部分文件类型和凭据格式的启发式校验，不能保证发现所有真实密钥，也不会自动脱敏；发布前仍需自行检查并移除真实凭据。
+
+推荐做法是：技能包里只写需要的环境变量名或占位符，并在 `SKILL.md` 中说明需要配置哪些凭据，由使用方在运行 Skill 的 Agent 环境中配置真实值。目前 SkillHub 不提供为 Skill 托管或注入密钥的功能。
+
 ## Q: 发布时报“技能包校验失败 / malformed input”怎么办？
 
 A: 该错误发生在 zip 解包读取文件名阶段，通常是压缩包不是 UTF-8 编码（例如用 Windows 自带压缩工具生成）或包内含中文路径导致。请使用 UTF-8 编码重新打包，并避免中文 / 特殊字符路径。
@@ -325,6 +335,18 @@ A: 两个高频原因：
 docker compose --env-file .env.release -f compose.release.yml up -d --force-recreate
 ```
 
+## Q: 启动时报 `bind: address already in use`（80 端口被占用）怎么办？
+
+A: 官方 Compose 默认把 Web 入口映射到宿主机 `80` 端口、API 映射到 `8080` 端口。端口被占用时，可以先用 `netstat -tlnp` 或 `lsof -i :80` 找到占用进程；如果不方便停止它，就在 `.env.release` 中修改对外端口（一键部署脚本使用 `${TMPDIR:-/tmp}/skillhub-runtime/.env.release`；若设置了 `SKILLHUB_HOME` 或通过 `--home` 指定目录，则以该目录为准）：
+
+```bash
+WEB_PORT=8081
+# 如 8080 也被占用
+API_PORT=18080
+```
+
+修改端口后，请同步把 `SKILLHUB_PUBLIC_BASE_URL` 改成包含新端口的实际访问地址（例如 `http://your-host:8081`），否则登录回调等跳转可能出错。然后进入 `.env.release` 与 `compose.release.yml` 所在的实际运行目录，按上一条的方法用 `up -d --force-recreate` 重建容器。
+
 ## Q: SkillHub 运行时需要哪些外部依赖？
 
 A: 必需 PostgreSQL 和 Redis；对象存储支持 `local` 与 S3 两种模式，由 `SKILLHUB_STORAGE_PROVIDER` 控制。`.env.release.example` 显式配置为 `local`，但如果使用 `compose.release.yml` 时完全没有设置该变量，Compose 的回退值是 `s3`。建议始终显式设置；生产环境推荐使用 S3（通过 `SKILLHUB_STORAGE_S3_*` 配置）。数据库仅支持 PostgreSQL，暂不支持 MySQL。