docs: standardize skill-template and add development guide

SKILL.md

@@ -1,56 +1,42 @@
 ---
-# ---------------------------------------------------------------------------
-# 技能清单（Skill Manifest）
-# 行业常见做法：YAML 头描述元数据，正文 Markdown 描述「何时用、怎么调」。
-# 不同 Claw 宿主解析字段可能略有差异；可移植标识请使用 metadata.skill.slug。
-# ---------------------------------------------------------------------------
-name: 您的技能显示名称
-description: 一句话说明技能做什么（给编排层与人类阅读，不写实现细节）。
+name: 技能开发模板（复制后请修改）
+description: "这是 OpenClaw 技能开发模板仓库，不直接作为业务技能发布。复制为新技能仓库后，按本模板替换 slug、名称、说明、CLI 子命令与 service 实现。"
 version: 1.0.0
 author: 深圳匠厂科技有限公司
 metadata:
-  skill:
-    # 机器可读、稳定标识：小写字母、数字、短横线；与数据子目录名一致。
+  openclaw:
     slug: your-skill-slug
     emoji: "📦"
     category: "通用"
-# 宿主若限制可调用的工具类型，在此列出（按宿主文档填写）。
 allowed-tools:
   - bash
 ---
 
-# Your Skill Display Name
+# 技能开发模板（skill-template）
 
-## 使用时机
+这是一个**用于复制的新技能模板**，不是业务技能本身。新建技能时，应复制本仓库结构，再把占位内容替换成你的真实业务实现。
 
-<!-- 由技能作者填写：用户在自然语言里怎样表达时应触发本技能。 -->
+## 模板使用方式
 
-- 示例：用户说「检查技能是否可用」「运行某某任务」
+1. 复制目录为你的新 skill 仓库。
+2. 全局替换 `your-skill-slug`、`技能开发模板（复制后请修改）` 等占位词。
+3. 按 `references/CLI.md`、`scripts/` 分层与 `README.md` 的说明补业务逻辑。
 
-## 执行步骤
+## 目录约定
 
-<!-- 将 {baseDir} 替换为宿主提供的技能根目录；若宿主使用其它占位符，以宿主文档为准。 -->
+- 根目录结构参考现有规范技能：`assets/`、`references/`、`scripts/`、`tests/`、`evals/`。
+- CLI 入口固定为 `scripts/main.py`。
+- 业务逻辑按 `cli / db / service / util / jiangchang_skill_core` 分层。
 
-### 健康检查（推荐自动化先跑）
+## 最小命令
 
 ```bash
-python3 {baseDir}/scripts/skill_main.py health
+python {baseDir}/scripts/main.py health
+python {baseDir}/scripts/main.py version
 ```
 
-### 查看版本
+## 重要说明
 
-```bash
-python3 {baseDir}/scripts/skill_main.py version
-```
-
-### 扩展子命令
-
-在 `scripts/skill_main.py` 中增加新的子命令分支，并在此处追加对应示例命令与参数说明。
-
-## 环境依赖
-
-详见本仓库 `docs/RUNTIME.md`（`CLAW_DATA_ROOT`、`CLAW_USER_ID` 等）。
-
-## 数据与隐私
-
-本技能若产生持久化数据，应仅写入 `{CLAW_DATA_ROOT}/{CLAW_USER_ID}/your-skill-slug/` 下；不得将用户数据提交到版本库。
+- 复制后请同步修改 `scripts/util/constants.py` 中的 `SKILL_SLUG` / `SKILL_VERSION`。
+- 如技能无需持久化，可保留 `db/` 目录但不主动调用。
+- 面向用户与编排的文档写在 `references/`，不要再新增旧式 `docs/` / `optional/` 结构。