docs: standardize skill-template and add development guide

README.md

@@ -1,40 +1,47 @@
-# Claw 技能项目模板（通用）
+# OpenClaw 技能开发模板
 
-本目录是一个**与具体业务无关**的技能（Skill）工程骨架，供团队在各类 **Claw / Agent 宿主**（桌面端、网关、IDE 插件等）上交付可安装技能包时参考。
+这是一个**规范化的新技能模板仓库**，用于复制出新的 skill 项目；它本身**不是业务 skill**。
 
-## 你从这里能得到什么
+## 模板目标
 
-- **行业标准对齐**：技能以「清单文件 + 可执行入口 + 文档」组织——与常见的 Agent Skill、CLI 工具包、内部自动化脚本仓库的惯例一致；不绑定某一厂商私有协议。
-- **可移植约定**：数据目录、用户隔离、兄弟技能路径等通过**环境变量契约**描述（见 `docs/RUNTIME.md`）；不同宿主只需注入同名变量或做一层别名映射。
-- **低学习成本**：每个文件顶部与关键步骤都有注释；按下面顺序做即可跑通第一个命令。
+- 对齐当前规范 skill 的目录结构：`assets/`、`references/`、`scripts/`、`tests/`、`evals/`
+- 对齐当前规范脚手架分层：`scripts/cli`、`scripts/db`、`scripts/service`、`scripts/util`、`scripts/jiangchang_skill_core`
+- 提供最小可运行入口：`python scripts/main.py health` / `version`
+- 让新技能从一开始就按规范落地，不再沿用旧模板的 `docs/`、`optional/`、`skill_main.py` 结构
 
-## 建议的上手顺序（约 15～30 分钟）
+## 新技能使用步骤
 
-1. **复制本模板**为新仓库或新目录，全局把占位符 `your-skill-slug` / `Your Skill Display Name` 换成你的技能标识（与 `SKILL.md` 里 `metadata.skill.slug` 一致）。
-2. **阅读** `docs/RUNTIME.md`，确认你的宿主会注入哪些环境变量；若宿主使用另一套名字，在宿主侧做映射，或改 `optional/paths_snippet.py` 中的读取顺序（文件内有说明）。
-3. **本地试跑**：`python scripts/skill_main.py health` 应输出成功信息。
-4. **扩展子命令**：在 `scripts/skill_main.py` 的 `dispatch` 中增加分支；业务逻辑放在同目录其它模块或子包中，保持入口轻薄。
-5. **编写/调整 `SKILL.md`**：只改「何时触发、如何调用、参数含义」，不要写实现细节；实现细节放在 `docs/` 或代码注释里。
-6. **发布**：若使用 GitHub Actions，编辑 `.github/workflows/release_skill.yaml`，把 `uses:` 指向**你们组织**的复用工作流；若不用 CI，可删除该目录。
-7. **一键打标签推送（与匠厂 monorepo 对齐）**：在技能仓库根目录执行 `.\release.ps1`（需与 `jiangchang-platform-kit` 位于同一父目录，以便调用 `..\jiangchang-platform-kit\tools\release.ps1`）。支持 `-DryRun`、`-AutoCommit`、`-CommitMessage` 等参数，与 `account-manager` / `sohu-publisher` 一致。
+1. 复制本目录为新的 skill 仓库。
+2. 全局替换 `your-skill-slug`、`your-platform-key`、`您的技能显示名称`、`你的平台名` 等占位内容。
+3. 修改 `SKILL.md`、`references/` 和 `scripts/util/constants.py`。
+4. 在 `scripts/service/` 中补业务 service 与真正的发布/执行逻辑。
+5. 用 `python scripts/main.py health` 和 `python scripts/main.py version` 做最小验证。
 
-## 目录一览
+开发教程入口：
 
-| 路径 | 作用 |
+- `references/DEVELOPMENT.md`：给技术人员的完整开发步骤说明
+
+## 目录说明
+
+| 路径 | 用途 |
 |------|------|
-| `SKILL.md` | 技能清单（YAML 头 + Markdown 正文），供宿主与协作者阅读 |
-| `release.ps1` | 转调平台套件的发布脚本（提交/推送/语义化 tag）；依赖并列的 `jiangchang-platform-kit` |
-| `scripts/skill_main.py` | 推荐唯一 CLI 入口；含 `health` / `version` 示例 |
-| `docs/RUNTIME.md` | 环境与目录契约（多宿主通用） |
-| `docs/SKILL_TYPES.md` | 常见技能形态与自检清单 |
-| `docs/PORTABILITY.md` | 多 Claw 宿主差异与兼容建议 |
-| `optional/` | 可选复制进项目的片段（路径、SQLite 示例），**不默认 import** |
+| `SKILL.md` | 技能清单与触发说明模板 |
+| `assets/` | 示例输出与轻量 schema |
+| `references/` | 面向用户与编排的文档模板 |
+| `scripts/` | 规范分层后的代码骨架 |
+| `tests/` | 单元测试或最小回归测试 |
+| `evals/` | 人工/半自动评估材料 |
+| `.github/workflows/release_skill.yaml` | 标准发布工作流 |
+| `release.ps1` | 对齐现有 skill 的发布脚本入口 |
 
-## 不要做的事
+## 最小命令
 
-- 不要在模板中提交真实密钥、真实业务表结构或平台专用逻辑。
-- 不要把模板改成只支持某一种宿主；特殊项写在 `docs/PORTABILITY.md` 的「宿主附录」中。
+```bash
+python scripts/main.py health
+python scripts/main.py version
+```
 
-## 版本
+## 注意
 
-模板自身版本见 `SKILL.md` 的 `version` 字段；与你技能的业务版本一致更新即可。
+- 不要再往模板里引入旧式 `docs/` 或 `optional/` 目录。
+- 新技能若不需要某些目录，也建议先保留结构，再按实际业务填充内容。