skill-template/README.md

Claw 技能项目模板（通用）

本目录是一个与具体业务无关的技能（Skill）工程骨架，供团队在各类 Claw / Agent 宿主（桌面端、网关、IDE 插件等）上交付可安装技能包时参考。

你从这里能得到什么

• 行业标准对齐：技能以「清单文件 + 可执行入口 + 文档」组织——与常见的 Agent Skill、CLI 工具包、内部自动化脚本仓库的惯例一致；不绑定某一厂商私有协议。
• 可移植约定：数据目录、用户隔离、兄弟技能路径等通过环境变量契约描述（见 docs/RUNTIME.md）；不同宿主只需注入同名变量或做一层别名映射。
• 低学习成本：每个文件顶部与关键步骤都有注释；按下面顺序做即可跑通第一个命令。

建议的上手顺序（约 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，可删除该目录。

目录一览

路径	作用
SKILL.md	技能清单（YAML 头 + Markdown 正文），供宿主与协作者阅读
scripts/skill_main.py	推荐唯一 CLI 入口；含 health / version 示例
docs/RUNTIME.md	环境与目录契约（多宿主通用）
docs/SKILL_TYPES.md	常见技能形态与自检清单
docs/PORTABILITY.md	多 Claw 宿主差异与兼容建议
optional/	可选复制进项目的片段（路径、SQLite 示例），不默认 import

不要做的事

• 不要在模板中提交真实密钥、真实业务表结构或平台专用逻辑。
• 不要把模板改成只支持某一种宿主；特殊项写在 docs/PORTABILITY.md 的「宿主附录」中。

版本

模板自身版本见 SKILL.md 的 version 字段；与你技能的业务版本一致更新即可。