Add generic Claw skill-template (manifest, CLI, docs, optional snippets)

Made-with: Cursor

docs/PORTABILITY.md

@@ -0,0 +1,56 @@
+# 多宿主（多 Claw）可移植性说明
+
+## 设计目标
+
+同一套技能仓库应能在**不同 Claw 实现**下工作，只要宿主满足本文档的**最小契约**：能启动进程、传入环境变量、并把 `SKILL.md` 提供给编排层阅读。
+
+## 行业上常见的「技能包」形态
+
+- **声明式清单**（Markdown + YAML 头）：描述名称、描述、版本、工具权限、触发场景。
+- **可执行入口**：一至多个脚本/二进制，由宿主通过 `bash` / `python` 等调用。
+- **用户数据与代码分离**：持久化数据落在用户可写目录，不写在安装目录内。
+
+本模板按上述惯例组织；具体宿主如何解析 `SKILL.md` 的 YAML 键名，以各宿主文档为准。
+
+## 标识技能：`metadata.skill`
+
+本模板在 `SKILL.md` 中使用 **`metadata.skill.slug`** 作为**可移植**的机器可读标识（短横线命名，如 `my-skill`）。
+
+若你的宿主仍要求其它键名（例如历史实现里的嵌套字段），请在宿主侧做**映射**，或在 `SKILL.md` 中**并列声明**两组 metadata（保持 `slug` 值一致）。不要在业务代码里写死某一宿主品牌名。
+
+## 环境变量：推荐前缀 `CLAW_*`
+
+为减少对单一产品名的耦合，模板文档与可选片段推荐使用：
+
+| 变量 | 含义 |
+|------|------|
+| `CLAW_DATA_ROOT` | 用户数据根目录（多技能共享的上一级） |
+| `CLAW_USER_ID` | 当前工作空间或用户标识，用于数据隔离 |
+| `CLAW_SKILLS_ROOT` | 可选；多个技能并排安装时的根目录，便于 `subprocess` 调用兄弟技能 |
+
+宿主若已使用其它名称，推荐在**启动子进程时**注入别名，例如：
+
+- 将宿主内部的「数据根」映射为 `CLAW_DATA_ROOT`
+- 将宿主内部「用户 ID」映射为 `CLAW_USER_ID`
+
+这样技能脚本无需分支判断宿主品牌。
+
+## 路径布局约定（逻辑路径）
+
+在 `CLAW_DATA_ROOT` 与 `CLAW_USER_ID` 可用时，本技能推荐将私有数据放在：
+
+```text
+{CLAW_DATA_ROOT}/{CLAW_USER_ID}/{skill_slug}/
+```
+
+其中 `skill_slug` 与 `SKILL.md` 中 `metadata.skill.slug` 一致。若环境变量缺失，`optional/paths_snippet.py` 中提供了**仅用于开发机**的 fallback（见该文件注释），生产环境应由宿主注入变量。
+
+## 发布与制品
+
+不同组织对加密、签名、制品格式要求不同。`.github/workflows/release_skill.yaml` 仅作占位：**务必替换**为你们自己的复用工作流或删除。模板不假设必须使用某一家的发布流水线。
+
+## 自检
+
+- [ ] `SKILL.md` 中 `slug` 与目录名/制品名策略是否与宿主一致  
+- [ ] 宿主文档要求的环境变量是否已全部注入  
+- [ ] 是否在文档中说明了「未注入变量时的行为」（拒绝运行 / 本地 fallback）