From b1e93a323fbd3479918212a8a8fcc7c9f4a7a3db Mon Sep 17 00:00:00 2001
From: chendelian <116870791@qq.com>
Date: Tue, 14 Apr 2026 10:05:16 +0800
Subject: [PATCH] docs: generalize skill template development guide

---
 SKILL.md                  |  2 +-
 references/DEVELOPMENT.md | 54 +++++++++++++++++++++++++++------------
 scripts/util/constants.py |  2 +-
 3 files changed, 39 insertions(+), 19 deletions(-)

diff --git a/SKILL.md b/SKILL.md
index c54f762..e103bb8 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: 技能开发模板（复制后请修改）
 description: "这是 OpenClaw 技能开发模板仓库，不直接作为业务技能发布。复制为新技能仓库后，按本模板替换 slug、名称、说明、CLI 子命令与 service 实现。"
-version: 1.0.12
+version: 1.0.13
 author: 深圳匠厂科技有限公司
 metadata:
   openclaw:
diff --git a/references/DEVELOPMENT.md b/references/DEVELOPMENT.md
index 8ecfc48..76d42c1 100644
--- a/references/DEVELOPMENT.md
+++ b/references/DEVELOPMENT.md
@@ -214,10 +214,23 @@ scripts/
 
 - 技能名称
 - 技能描述
-- slug
-- category
+- `slug`
+  作用：技能的唯一英文标识，通常用于仓库名、发布包名、运行时目录名、平台主键匹配等
+  示例：`weibo-publisher`、`douyin-publisher`、`xiaohongshu-publisher`
+- `category`
+  作用：技能在平台中的分类，用于市场展示与归类，不是代码内部键
+  示例：`通用`、`内容`、`办公协作`、`物流`、`抖音`、`小红书`
 - `developer_ids`（如需给非公开技能自动补开发者可见权限）
-- dependencies
+  作用：声明发布后默认拥有可见权限的开发者用户 ID 列表
+- `dependencies`
+  作用：声明该技能依赖的兄弟技能或运行前置能力，便于平台或编排层识别依赖关系
+  示例：
+  ```yaml
+  dependencies:
+    required:
+      - account-manager
+      - content-manager
+  ```
 - 何时使用本技能
 - 对用户的引导话术
 - CLI 使用原则
@@ -380,27 +393,27 @@ metadata:
 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. 本地开发的最小验证顺序
 
@@ -417,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
@@ -434,7 +454,7 @@ python scripts/main.py log-get 1
 比如：
 
 ```bash
-python scripts/main.py publish
+python scripts/main.py <your-command>
 ```
 
 ## 15. 发布到正式环境验证
diff --git a/scripts/util/constants.py b/scripts/util/constants.py
index ea07e81..017e647 100644
--- a/scripts/util/constants.py
+++ b/scripts/util/constants.py
@@ -1,5 +1,5 @@
 """技能标识与版本（复制后请修改）。"""
 
 SKILL_SLUG = "your-skill-slug"
-SKILL_VERSION = "1.0.12"
+SKILL_VERSION = "1.0.13"
 LOG_LOGGER_NAME = "openclaw.skill.your_skill_slug"