# 多宿主（多 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）