docs: explain developer_ids in skill template

README.md

@@ -17,6 +17,8 @@
 4. 在 `scripts/service/` 中补业务 service 与真正的发布/执行逻辑。
 5. 用 `python scripts/main.py health` 和 `python scripts/main.py version` 做最小验证。
 
+如果你的技能在平台里默认是非公开的（`access_scope = 0`），建议在 `SKILL.md` 的 `metadata.openclaw.developer_ids` 中填写开发者用户 ID 列表。这样发布后，平台会自动给这些开发者补可见权限，避免“技能已发布但开发者自己在市场中看不到”。
+
 开发教程入口：
 
 - <a href="references/REQUIREMENTS.md" target="_blank" rel="noopener noreferrer">需求文档模板</a>：给技术人员编写和查看研发需求的标准模板
@@ -46,3 +48,4 @@ python scripts/main.py version
 
 - 不要再往模板里引入旧式 `docs/` 或 `optional/` 目录。
 - 新技能若不需要某些目录，也建议先保留结构，再按实际业务填充内容。
+- `metadata.openclaw.developer_ids` 是发布元数据，不是用户展示文案。它的作用是让发布后的非公开技能自动授权给指定开发者查看。

SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: 技能开发模板（复制后请修改）
 description: "这是 OpenClaw 技能开发模板仓库，不直接作为业务技能发布。复制为新技能仓库后，按本模板替换 slug、名称、说明、CLI 子命令与 service 实现。"
-version: 1.0.11
+version: 1.0.12
 author: 深圳匠厂科技有限公司
 metadata:
   openclaw:
@@ -42,4 +42,7 @@ python {baseDir}/scripts/main.py version
 
 - 复制后请同步修改 `scripts/util/constants.py` 中的 `SKILL_SLUG` / `SKILL_VERSION`。
 - 如技能无需持久化，可保留 `db/` 目录但不主动调用。
+- `metadata.openclaw.developer_ids` 用于声明技能发布后的默认开发者可见用户 ID 列表。
+- 当技能在平台中 `access_scope = 0`（不公开）时，发布流程会把 `developer_ids` 中的用户自动补写到 `skill_user_access`，使这些开发者仍可在技能市场中查看该技能。
+- `developer_ids` 建议写为正整数数组；第一个 ID 会作为主开发者同步到 `skills.developer_id`。
 - 面向用户与编排的文档写在 `references/`，不要再新增旧式 `docs/` / `optional/` 结构。

references/DEVELOPMENT.md

@@ -186,6 +186,8 @@ scripts/
 - 平台内部键
 - 日志 logger 名
 
+此外，如果该技能发布后默认不公开（`access_scope = 0`），建议一开始就把 `SKILL.md` 中的 `metadata.openclaw.developer_ids` 配好。这样后续发布到平台时，开发者本人仍能在技能市场中看到并验证该技能。
+
 ## 5. 哪些占位内容必须替换
 
 复制后，至少要全局检查并替换下面这些内容：
@@ -214,6 +216,7 @@ scripts/
 - 技能描述
 - slug
 - category
+- `developer_ids`（如需给非公开技能自动补开发者可见权限）
 - dependencies
 - 何时使用本技能
 - 对用户的引导话术
@@ -226,6 +229,33 @@ scripts/
 - 代码注释
 - `service/` 实现里
 
+### 关于 `metadata.openclaw.developer_ids`
+
+这是一个平台发布元数据字段，用于解决下面这个问题：
+
+- 技能发布后若平台记录中的 `access_scope = 0`，技能默认不公开
+- 如果不额外授权，连开发者自己也可能在技能市场里看不到这个技能
+
+因此可以在 `SKILL.md` 中声明：
+
+```yaml
+metadata:
+  openclaw:
+    slug: your-skill-slug
+    category: 通用
+    developer_ids:
+      - 1032
+      - 12428
+```
+
+约定如下：
+
+- 只允许填写正整数用户 ID
+- 推荐使用数组，即使当前只有 1 个开发者
+- 发布时平台会把这些用户自动补写到 `skill_user_access`
+- 第一个 ID 会同步到 `skills.developer_id`
+- 一期只做“补授权”，不会因为你 later 修改数组而自动撤销旧授权
+
 ## 7. `references/` 应该放什么
 
 `references/` 是当前规范 skill 的文档中心，建议至少有这些：
@@ -419,6 +449,8 @@ python scripts/main.py publish
 .\release.ps1
 ```
 
+如果你的技能使用了 `metadata.openclaw.developer_ids`，那么这一步触发的发布工作流除了同步 `skills` / `skill_versions` 外，还会在平台侧自动补开发者可见权限。测试非公开技能时，建议重点验证这部分是否生效。
+
 这一步会自动完成标准发布动作，包括：
 
 1. 检查当前仓库状态

references/README.md

@@ -17,10 +17,26 @@ description: "这是规范化的新技能模板说明，不直接作为业务技
 ## 复制后你需要改什么
 
 - `SKILL.md` 中的名称、描述、slug、触发说明
+- `SKILL.md` 中 `metadata.openclaw.developer_ids`（如需让非公开技能默认授权给开发者查看）
 - `references/CLI.md` 里的命令示例
 - `scripts/util/constants.py` 中的 slug / 版本 / logger 名
 - `scripts/service/` 下的真实业务实现
 
+## `developer_ids` 是做什么的
+
+`metadata.openclaw.developer_ids` 是平台发布元数据，不是终端用户文案。
+
+它用于声明：当技能发布后，如果平台侧将该技能设置为 `access_scope = 0`（不公开），哪些开发者用户仍应自动获得可见权限。
+
+约定如下：
+
+- 字段位置：`SKILL.md` -> `metadata.openclaw.developer_ids`
+- 推荐格式：正整数数组，例如 `[1032, 12428]`
+- 发布效果：发布接口会把这些用户补写到 `skill_user_access`
+- 第一个 ID 会作为主开发者同步到 `skills.developer_id`
+
+如果你的技能本来就是公开技能，或暂时不需要开发者专属可见性，这个字段可以留空数组。
+
 ## 不建议再保留的旧结构
 
 - 旧模板里的 `docs/`

scripts/util/constants.py

@@ -1,5 +1,5 @@
 """技能标识与版本（复制后请修改）。"""
 
 SKILL_SLUG = "your-skill-slug"
-SKILL_VERSION = "1.0.11"
+SKILL_VERSION = "1.0.12"
 LOG_LOGGER_NAME = "openclaw.skill.your_skill_slug"