docs: explain developer_ids in skill template

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/`