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）

docs/RUNTIME.md

@@ -0,0 +1,55 @@
+# 运行时契约（环境变量与目录）
+
+本文档定义技能进程**建议依赖**的外部条件，便于不同 Claw 宿主统一接入。业务技能应**读取环境变量**，而不是在代码里写死路径或用户名。
+
+## 必需程度说明
+
+- **强烈建议**：生产环境由宿主注入；技能应对缺失给出明确错误提示，避免静默写到意外目录。
+- **可选**：没有时技能仍可部分运行（例如只读 `health`）。
+
+## 变量一览
+
+### `CLAW_DATA_ROOT`（强烈建议）
+
+用户数据根。多个技能、多个用户的数据都在此根之下分区。
+
+- 典型场景：组织策略指定的盘符路径或 `~/.your-org-data`。
+- 未设置时：技能**不应**猜测网络盘；开发机 fallback 仅限 `optional/paths_snippet.py` 中说明的情形。
+
+### `CLAW_USER_ID`（强烈建议）
+
+当前会话所代表的用户或工作空间 ID（字符串）。与数据隔离强相关。
+
+- 用于拼接：`{CLAW_DATA_ROOT}/{CLAW_USER_ID}/{skill_slug}/`
+- 未设置时：可用匿名占位（如 `_anon`）**仅用于开发**，生产应显式注入。
+
+### `CLAW_SKILLS_ROOT`（可选）
+
+多个技能以并列目录安装时的根路径，例如：
+
+```text
+{CLAW_SKILLS_ROOT}/skill-a/scripts/...
+{CLAW_SKILLS_ROOT}/skill-b/scripts/...
+```
+
+编排型技能若需要通过子进程调用兄弟技能，应基于该变量定位脚本，避免写死绝对路径。
+
+## 本技能推荐的数据目录
+
+```text
+{CLAW_DATA_ROOT}/{CLAW_USER_ID}/{skill_slug}/
+```
+
+- `skill_slug`：与 `SKILL.md` 内 `metadata.skill.slug` 一致。
+- 在此目录下可放置 SQLite 文件、缓存、上传临时文件等；**不要**向版本库提交该目录内容。
+
+## 标准输出约定（建议）
+
+为便于宿主与自动化解析，建议：
+
+- 致命错误：单行前缀 `ERROR:`，例如 `ERROR:MISSING_ENV_CLAW_DATA_ROOT`
+- 成功：人类可读一行或多行；若有机读需求，可用 `JSON` 单行输出并在 `SKILL.md` 中说明格式。
+
+## 与具体宿主的关系
+
+若某宿主文档规定了另一套变量名，应在**宿主启动技能子进程时**注入为本文档中的 `CLAW_*` 名称，或在技能内使用一层极薄的 `getenv` 封装（见 `optional/paths_snippet.py` 注释示例）。**不要在业务模块中散落多套变量名判断。**

docs/SKILL_TYPES.md

@@ -0,0 +1,33 @@
+# 技能形态与自检清单（无业务）
+
+开发前先选定形态，避免把「编排、存储、浏览器」混在一个脚本里难以测试。
+
+## 类型 A：无状态工具型
+
+- **特征**：不持久化用户数据，或只读配置文件；输入输出主要在 stdin/stdout。
+- **数据目录**：通常不需要 `CLAW_DATA_ROOT` 下的专属库；若需要缓存，仍建议放在契约目录下。
+- **自检**：离线可跑；`health` 不访问网络也可成功。
+
+## 类型 B：本地持久化型
+
+- **特征**：使用 SQLite、本地文件等保存用户数据。
+- **数据目录**：必须使用 `{CLAW_DATA_ROOT}/{CLAW_USER_ID}/{skill_slug}/`。
+- **自检**：首次运行自动建库/建表；文档中说明库文件路径与备份方式。
+
+## 类型 C：编排型（调用其它技能或外部 CLI）
+
+- **特征**：自身逻辑薄，主要 `subprocess` 或 HTTP 调用其它组件。
+- **依赖**：在 `SKILL.md` 中明确写出**先决条件**（兄弟技能已安装、某 CLI 在 PATH 等）。
+- **自检**：`health` 可检查兄弟可执行文件是否存在；缺失时打印清晰错误。
+
+## 类型 D：混合型
+
+- **特征**：既有本地存储，又调用外部能力。
+- **建议**：拆模块（存储 / 编排 / 领域逻辑），入口脚本只做参数解析与调度。
+
+## 发布前通用自检
+
+- [ ] `SKILL.md` 中触发条件与示例命令与实际入口一致  
+- [ ] 未注入 `CLAW_DATA_ROOT` / `CLAW_USER_ID` 时行为已文档化  
+- [ ] 不向仓库提交用户数据、密钥、大型二进制  
+- [ ] 错误信息包含「如何修复」（缺什么环境变量、缺哪个依赖）