skill-template/docs/PORTABILITY.md

多宿主（多 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 可用时，本技能推荐将私有数据放在：

{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）