# skill-template 工具

## 推荐：脚手架创建新技能

**不要**用资源管理器整文件夹复制 `skill-template`（会带走隐藏 `.git`，导致 push 串库）。

Windows 首选：

```powershell
cd D:\OpenClaw\client-commons\skill-template
.\tools\scaffold_skill.ps1 -Slug my-new-skill -Destination D:\OpenClaw\client-gdcm\my-new-skill
```

跨平台（Python 3.10+）：

```bash
python tools/scaffold_skill.py --slug my-new-skill --destination /path/to/my-new-skill
```

脚本行为：

- 复制模板到 `-Destination`（目录末段须与 `-Slug` 一致）
- **排除**：`.git`、`.pytest_cache`、`__pycache__`、`.env`、`.env.local`、`*.pyc`
- 删除目标中的 `.openclaw-skill-template` 标记
- 将文本文件中的模板占位 slug 替换为新 slug：
  - `your-skill-slug` → 新技能 kebab-case slug（如 `scrape-demo-records`）
  - `your_skill_slug` → 连字符替换为下划线（如 `scrape_demo_records`，用于 `LOG_LOGGER_NAME` 等）
  - 覆盖 `assets/actions.json`、`SKILL.md`、`scripts/util/constants.py` 等生成文件；文档中的路径示例可保留占位，但生成后的技能文件不得残留占位符
- **不**自动修改 `actions.json` 中的 CLI 业务命令；技能作者自行增删 action
- **不**移除 Schema 中的 `bind.tables` 支持，**不**把 `bind` 当模板残留清理
- **不**自动生成业务表名，**不**给 `health` / `version` / `config-path` 自动加 `toolbar`
- **不**生成任何具体平台业务 Action
- **不**自动 `git init`；打印后续 Git 与测试命令

目标目录若已存在且非空，需加 `-Force` / `--force`（且目标**不得**含 `.git`）。

## 脚手架复制后必须保留 / 修改 / 可删除的文件

| 文件 | 说明 |
|------|------|
| `assets/actions.json` | 默认复制；不需要宿主 Action 入口时可删除 |
| `references/ACTIONS.md` | 契约文档；无 `actions.json` 时可保留作参考或按需精简 |
| `assets/schemas/skill-actions.schema.json` | manifest 规范；无 action 时可保留 |
| `tests/test_actions_manifest.py` | 若删除 `actions.json`，应同步删除或改写此测试 |
| `tests/test_data_management_contract.py` | 通用契约测试；建议保留，按需扩展本技能表结构测试 |

`demo_items` 等示例表仅存在于模板测试中，**不会**作为 scaffold 后的默认业务表复制进新技能。

## 手工复制后的补救

若已整目录复制，必须先清理再初始化：

```powershell
cd <新技能目录>
Remove-Item -Recurse -Force .git
Remove-Item -Recurse -Force .pytest_cache -ErrorAction SilentlyContinue
Remove-Item -Force .openclaw-skill-template -ErrorAction SilentlyContinue
git init
git remote add origin <新技能仓库 URL>
git remote -v
```

确认 `origin` **不是** skill-template 的远端 URL。

## 模板标记

源仓库根目录有 `.openclaw-skill-template`（仅 template 保留）。业务技能不得保留该文件；`tests/test_scaffold_guard.py` 会守护。