template-skill

新 skill 的基础模版，内置认证、遥测回调、CI/CD 注册流程。

---

认证机制：auth-cli.ts

每个 skill 内置一份 src/auth-cli.ts，通过 subprocess 调用 auth-rt 二进制完成认证，零 npm 依赖。

skill/scripts/run.ts
  → createSkillClient().session()
  → auth-cli.ts spawnSync auth-rt
  → auth-rt 读取 ~/.openclaw/.env (CLIENT_KEY)
  → 返回 { accessToken, hookUrl, hookToken, ... }

使用方式

import { createSkillClient } from './auth-cli.ts';

const client = createSkillClient({ dryRun: false });
const session = await client.session();
// session = { accessToken, hookUrl, hookToken, ... }

const res = await client.post('/ecom/your/endpoint', { param: 'value' });
// res = { status: 200, body: '...' }

前置条件

每台运行 skill 的机器需安装 auth-rt（install.sh 自动处理）：

# 手动安装
bash install.sh

# 或确保 ~/.openclaw/.env 中配置
CLIENT_KEY=sk_xxxx

---

遥测与可观测性：Hook 回调

scripts/run.ts 在每次 skill 执行后，自动向 auth server 下发的 hookUrl 发送结构化执行报告。

工作原理

Client 执行 skill
    │
    ├─ 1. auth-rt session  →  auth gateway 返回 { hookUrl, hookToken }
    ├─ 2. 执行命令
    └─ 3. POST hookUrl (fire-and-forget，不阻塞输出)
              {
                skill: "my-skill",
                command: "run",
                status: "success" | "failed",
                durationMs: 1234,
                error: "..." (仅失败时)
              }
                  ↓
            服务端 → Loki → Grafana

特性

• 服务端控制：hookUrl 由 auth server 在 session 时下发，客户端无需任何配置
• 非阻塞：fire-and-forget，hook 失败不影响 skill 正常执行和输出
• dry-run 跳过：--dry-run 模式下不发送 hook
• 统一入口：所有遥测逻辑在 scripts/run.ts 中，src/index.ts 保持纯业务逻辑

服务端可查询内容

维度	Loki label / 字段
哪个客户端调用了哪个 skill	CLIENT_KEY → session → hook
成功率 / 失败率	status
响应耗时	durationMs
错误类型分布	error
命令维度拆分	command

---

新建 Skill 检查清单

1. 从此模版创建仓库（Forgejo → Use this template）
2. package.json 中修改 name 字段
3. scripts/run.ts 中修改 SKILL_NAME 常量
4. SKILL.md 中更新 name / description frontmatter
5. src/index.ts 中实现业务逻辑
6. 不要 在 package.json 中添加 @clawd/auth-runtime 依赖
7. 推送 v* tag 触发 CI/CD 自动注册 skill

---

CI/CD：自动注册

.forgejo/workflows/register-skill-release.yml 在推送 v* tag 时触发，调用 shared-actions/register-skill 将 skill 注册到平台。

# 发布新版本
git tag v1.0.0 && git push origin v1.0.0

注册所需的 CLIENT_KEY 通过 Forgejo 仓库 Secret 配置，skill 代码中不包含任何密钥。

---

目录结构

.forgejo/workflows/     # CI/CD：tag 触发自动注册
scripts/run.ts          # CLI 入口：参数解析 + session + 遥测 hook
src/
  auth-cli.ts           # auth-rt 薄 wrapper（勿修改）
  index.ts              # 业务逻辑入口
  types.ts              # 类型定义
SKILL.md                # skill 元数据（frontmatter）+ Claude 使用说明
.env.example            # 环境变量模版
install.sh              # 依赖安装（含 auth-rt 自动下载）