docs: generalize skill template development guide

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,13 +1,16 @@
 ---
 name: 技能开发模板（复制后请修改）
 description: "这是 OpenClaw 技能开发模板仓库，不直接作为业务技能发布。复制为新技能仓库后，按本模板替换 slug、名称、说明、CLI 子命令与 service 实现。"
-version: 1.0.0
+version: 1.0.13
 author: 深圳匠厂科技有限公司
 metadata:
   openclaw:
     slug: your-skill-slug
     emoji: "📦"
     category: "通用"
+    developer_ids:
+      - 1032
+      - 12428
 allowed-tools:
   - bash
 ---
@@ -39,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

@@ -11,6 +11,68 @@
 
 如果你开发的是发布型 skill，这个模板就是直接可用的起点。
 
+## 推荐 AI 开发工具
+
+当前 skill 开发建议尽量配合 AI 编程工具使用。这样做不是为了替代技术人员，而是为了提升以下环节的效率：
+
+- 搭建标准目录结构
+- 生成样板代码
+- 理解旧项目代码
+- 批量补文档、注释和测试
+- 辅助排查报错与重构代码
+
+建议团队统一选择 1 到 2 个主力工具长期使用，避免每个人工具链差异太大，导致协作方式不一致。
+
+下面先列国外主流工具，再列国内主流工具。链接优先使用官方站点、官方文档或官方安装入口。
+
+### 国外主流工具
+
+| 工具 | 类型 | 适合场景 | 官方入口 |
+|------|------|----------|----------|
+| Cursor | 独立 AI IDE | 代码编辑、Agent 开发、整仓理解 | <a href="https://www.cursor.com/" target="_blank" rel="noopener noreferrer">官网</a> / <a href="https://www.cursor.com/downloads" target="_blank" rel="noopener noreferrer">下载</a> |
+| Windsurf | 独立 AI IDE | Agent 编程、项目生成、连续开发流 | <a href="https://docs.codeium.com/windsurf" target="_blank" rel="noopener noreferrer">文档</a> / <a href="https://windsurf.com/download" target="_blank" rel="noopener noreferrer">下载</a> |
+| GitHub Copilot | IDE 插件 / 编程助手 | 日常补全、解释代码、生成函数、配合 VS Code 或 JetBrains 使用 | <a href="https://github.com/copilot" target="_blank" rel="noopener noreferrer">官网</a> |
+| Claude Code | 终端 / IDE 编程代理 | 命令行开发、代码库分析、自动改代码、运行命令 | <a href="https://www.anthropic.com/claude-code" target="_blank" rel="noopener noreferrer">官网</a> / <a href="https://docs.anthropic.com/en/docs/claude-code/" target="_blank" rel="noopener noreferrer">文档</a> |
+| Codex | 终端 / IDE / Web 编程代理 | OpenAI 官方编码代理，适合代码生成、理解、调试、评审 | <a href="https://developers.openai.com/codex/" target="_blank" rel="noopener noreferrer">官网</a> / <a href="https://developers.openai.com/codex/quickstart" target="_blank" rel="noopener noreferrer">快速开始</a> |
+| Aider | 终端 AI 编程工具 | 已有代码仓库的增量开发、终端协作、快速提交 | <a href="https://www.aider.chat/" target="_blank" rel="noopener noreferrer">官网</a> / <a href="https://aider.chat/docs/" target="_blank" rel="noopener noreferrer">文档</a> |
+| Cline | VS Code / JetBrains 插件 | 编辑器内 Agent 开发、命令执行、浏览器联动调试 | <a href="https://cline.bot/" target="_blank" rel="noopener noreferrer">官网</a> / <a href="https://docs.cline.bot/introduction/welcome" target="_blank" rel="noopener noreferrer">文档</a> / <a href="https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev" target="_blank" rel="noopener noreferrer">VS Code 插件</a> |
+
+### 国内主流工具
+
+| 工具 | 类型 | 适合场景 | 官方入口 |
+|------|------|----------|----------|
+| Trae | 独立 AI IDE | AI 辅助写代码、项目搭建、对话式开发 | <a href="https://www.trae.ai/home" target="_blank" rel="noopener noreferrer">官网</a> / <a href="https://www.trae.ai/download" target="_blank" rel="noopener noreferrer">下载</a> |
+| 通义灵码 | 独立 IDE / IDE 插件 | 国内团队日常编码、问答、补全、代码生成 | <a href="https://tongyi.aliyun.com/lingma/?channel=yy_AiBot" target="_blank" rel="noopener noreferrer">官网</a> / <a href="https://tongyi.aliyun.com/lingma/download" target="_blank" rel="noopener noreferrer">下载</a> |
+| CodeGeeX | IDE 插件 / 开源助手 | 代码补全、生成、注释、跨语言辅助 | <a href="https://github.com/zai-org/CodeGeeX" target="_blank" rel="noopener noreferrer">GitHub</a> / <a href="https://marketplace.visualstudio.com/items?itemName=aminer.codegeex" target="_blank" rel="noopener noreferrer">VS Code 插件</a> |
+| 腾讯 CodeBuddy | IDE 插件 | 代码补全、测试生成、智能问答、腾讯云开发体系协作 | <a href="https://www.codebuddy.ai/" target="_blank" rel="noopener noreferrer">官网</a> / <a href="https://www.tencentcloud.com/document/product/1256" target="_blank" rel="noopener noreferrer">文档</a> / <a href="https://marketplace.visualstudio.com/items?itemName=Tencent-Cloud.coding-copilot" target="_blank" rel="noopener noreferrer">VS Code 插件</a> |
+| 百度文心快码（Baidu Comate） | IDE 插件 | 国内研发团队辅助编码、解释、测试、优化 | <a href="https://comate.baidu.com/zh" target="_blank" rel="noopener noreferrer">官网</a> |
+
+### 选型建议
+
+如果你们团队主要做这类 Python skill 开发，我建议这样选：
+
+- 想要一体化最强体验：优先试 `Cursor` 或 `Windsurf`
+- 想要命令行深度协作：优先试 `Claude Code` 或 `Aider`
+- 想继续基于 VS Code 插件体系：优先试 `GitHub Copilot`、`Cline`、`通义灵码`、`CodeBuddy`
+- 想优先使用国内生态与中文支持：优先试 `Trae`、`通义灵码`、`CodeGeeX`、`CodeBuddy`、`文心快码`
+
+### 团队落地建议
+
+为了减少培训成本，建议内部至少统一一套主工具方案：
+
+- 国外方案：`Cursor` + `Claude Code`
+- 国内方案：`Trae` + `通义灵码`
+- VS Code 插件方案：`GitHub Copilot` + `Cline`
+
+不建议每位技术人员完全自由发挥，否则后续在：
+
+- 提示词写法
+- 代码修改习惯
+- 调试方式
+- 提交节奏
+
+这些方面会越来越不统一。
+
 ## 1. 先理解模板的定位
 
 `skill-template` 不是业务 skill，它只是一个**新 skill 仓库模板**。
@@ -124,6 +186,8 @@ scripts/
 - 平台内部键
 - 日志 logger 名
 
+此外，如果该技能发布后默认不公开（`access_scope = 0`），建议一开始就把 `SKILL.md` 中的 `metadata.openclaw.developer_ids` 配好。这样后续发布到平台时，开发者本人仍能在技能市场中看到并验证该技能。
+
 ## 5. 哪些占位内容必须替换
 
 复制后，至少要全局检查并替换下面这些内容：
@@ -150,9 +214,23 @@ scripts/
 
 - 技能名称
 - 技能描述
-- slug
-- category
-- dependencies
+- `slug`
+  作用：技能的唯一英文标识，通常用于仓库名、发布包名、运行时目录名、平台主键匹配等
+  示例：`weibo-publisher`、`douyin-publisher`、`xiaohongshu-publisher`
+- `category`
+  作用：技能在平台中的分类，用于市场展示与归类，不是代码内部键
+  示例：`通用`、`内容`、`办公协作`、`物流`、`抖音`、`小红书`
+- `developer_ids`（如需给非公开技能自动补开发者可见权限）
+  作用：声明发布后默认拥有可见权限的开发者用户 ID 列表
+- `dependencies`
+  作用：声明该技能依赖的兄弟技能或运行前置能力，便于平台或编排层识别依赖关系
+  示例：
+  ```yaml
+  dependencies:
+    required:
+      - account-manager
+      - content-manager
+  ```
 - 何时使用本技能
 - 对用户的引导话术
 - CLI 使用原则
@@ -164,6 +242,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 的文档中心，建议至少有这些：
@@ -288,27 +393,27 @@ scripts/
 3. 用子进程调用
 4. 机器可读输出优先 JSON
 
-## 13. 如何开发发布型 skill
+## 13. 如何开发一个新 skill
 
-如果你开发的是 publisher 类 skill，建议按这个顺序做：
+不管你开发的是发布类、采集类、分析类还是知识库类 skill，建议都先按下面这个顺序推进：
 
 1. 先把目录结构搭完整
 2. 先让 `health` / `version` 跑通
-3. 再让 `publish_service.py` 的骨架跑通
-4. 再接 `sibling_bridge.py`
-5. 最后再写 `*_playwright.py`
+3. 再把核心 `service` 骨架跑通
+4. 再接兄弟技能桥接、数据库或外部系统
+5. 最后再补浏览器自动化、复杂流程编排或高风险集成
 
-不要一开始就直接写页面选择器。
+不要一开始就直接写页面选择器、复杂接口编排或深层业务逻辑。
 
 推荐先确保这些基础能力正常：
 
-- 能取到账号
-- 能取到文章
-- 能写日志
-- CLI 子命令通了
+- CLI 入口能跑通
+- 基础命令输出稳定
+- 关键依赖能取到
+- 日志或本地状态能落下来
 - 错误返回值格式定好了
 
-然后再进浏览器自动化。
+如果你的 skill 恰好是 publisher 类，可以把上面的“核心 `service`”具体落成 `publish_service.py`，再逐步接 `sibling_bridge.py`、`*_playwright.py`。但这只是示例，不代表模板只适合发布类技能。
 
 ## 14. 本地开发的最小验证顺序
 
@@ -325,12 +430,19 @@ python scripts/main.py version
 
 ```bash
 python scripts/main.py -h
-python scripts/main.py publish -h
+python scripts/main.py <your-command> -h
 ```
 
 ### 3. 验证本地日志与数据库
 
-如果是发布型 skill，再继续：
+如果你的 skill 需要本地日志或数据库，再继续：
+
+```bash
+python scripts/main.py <your-log-command>
+python scripts/main.py <your-detail-command> <id>
+```
+
+如果你沿用了模板中的发布型骨架，那么这里可以具体对应成：
 
 ```bash
 python scripts/main.py logs
@@ -342,7 +454,7 @@ python scripts/main.py log-get 1
 比如：
 
 ```bash
-python scripts/main.py publish
+python scripts/main.py <your-command>
 ```
 
 ## 15. 发布到正式环境验证
@@ -357,6 +469,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.0"
+SKILL_VERSION = "1.0.13"
 LOG_LOGGER_NAME = "openclaw.skill.your_skill_slug"