Integrate SkillHub CLI into publish lifecycle

- Rewrite skill-publisher with 7-step flow: target → checklist → format adaptation → dry-run → publish → verify → registry update - Add format adapter: skill.json + prompt.md → SKILL.md for Qoder/Codex/Claude Code - Add namespace auto-mapping for 4 frameworks (sola-*-work) - Update skill-discover with SkillHub as primary search source - Update skill-retire with skillhub remove --remote for server-side deletion - Add SkillHub platform section to README
2026-07-01 20:07:32 +08:00 · 2026-07-01 20:07:32 +08:00 · df4635a1da
commit df4635a1da
parent 4fe53197c4
11 changed files with 326 additions and 70 deletions
--- a/README.md
+++ b/README.md
@ -197,14 +197,45 @@ retire   → "已归档" → 结束

 ---

+## 发布平台：SkillHub
+
+SkillHub 是团队自建的 Agent Skill Registry（`https://skill.solahqb22.cn`），支持 **14 种 Agent CLI** 的技能发布、搜索和安装。
+
+### CLI 工具
+
+```bash
+npm install -g @astron-team/skillhub    # 安装
+skillhub login --registry https://skill.solahqb22.cn --token <TOKEN>  # 登录
+skillhub search <keyword>               # 搜索
+skillhub publish <path> --namespace <ns>  # 发布
+```
+
+### 命名空间映射
+
+| 框架 | SkillHub 命名空间 | 说明 |
+|------|------------------|------|
+| OpenClaw | `sola-openclaw-work` | OpenClaw 框架开发的技能 |
+| Claude Code | `sola-claude-code-work` | Claude Code 开发的技能 |
+| Codex | `sola-codex-work` | Codex 开发的技能 |
+| Qoder | `sola-qoder-work` | Qoder 创建的技能 |
+| Hermes Agent | 暂无 | 等待官方支持 |
+
+### 格式适配
+
+- **OpenClaw**：原生兼容（已有 `SKILL.md`），直接发布
+- **Qoder / Codex / Claude Code**：`skill-publisher` 自动将 `skill.json` + `prompt.md` 合并生成 `SKILL.md` 后发布
+- **Hermes Agent**：暂不支持
+
+---
+
 ## 后续规划

 - [x] 搭建完整目录结构（5 个框架 + 9 个生命周期技能）
 - [x] 构建 skill-lifecycle 总路由器和 8 个子技能
 - [x] OpenClaw meta-skill 规范整理（基于 ClawHub 官方生态）
+- [x] SkillHub 集成（skill-publisher / skill-discover / skill-retire 更新）
 - [ ] 补充各框架 meta-skill 的详细规范（Qoder / Claude Code / Codex / Hermes Agent）
 - [ ] 为各框架 meta-skill 的 `examples/` 补充官方参考技能示例
- [ ] 补充 SkillHub 发布规范到 `skill-publisher`
 - [ ] 为每个框架编写适配指南（`<framework>/docs/`）
 - [ ] 建设技能示例库（提供参考实现）

--- a/skills/skill-discover/CHANGELOG.md
+++ b/skills/skill-discover/CHANGELOG.md
@ -1,5 +1,11 @@
 # Changelog

+## 0.2.0 - 2026-07-01
+
+- 新增 SkillHub 作为首选搜索源（`skillhub search`）
+- 搜索结果合并展示，标注来源（SkillHub / ClawHub / 其他）
+- 支持 OpenClaw / Claude Code / Codex / Qoder 四个命名空间的内部搜索
+
 ## 0.1.0 - 2026-07-01

 - 初始版本
--- a/skills/skill-discover/prompt.md
+++ b/skills/skill-discover/prompt.md
@ -22,14 +22,15 @@

 ### Step 2: 搜索已有技能

-在以下平台搜索同类技能：
+在以下平台搜索同类技能（按优先级排序）：

-| 平台 | 搜索方式 | 适用框架 |
-|------|---------|---------|
-| [ClawHub](https://clawhub.ai/search) | Web 搜索 | OpenClaw |
-| Qoder 技能市场 | `qoder skills search <keyword>` | Qoder |
-| Claude 社区 | Web 搜索 | Claude Code |
-| OpenAI 插件市场 | Web 搜索 | Codex |
+| 平台 | 搜索方式 | 适用框架 | 优先级 |
+|------|---------|---------|--------|
+| **SkillHub**（团队内部） | `skillhub search <keyword>` | OpenClaw / Claude Code / Codex / Qoder | ⭐ 首选 |
+| [ClawHub](https://clawhub.ai/search) | Web 搜索 | OpenClaw | 外部参考 |
+| Qoder 技能市场 | `qoder skills search <keyword>` | Qoder | 外部参考 |
+| Claude 社区 | Web 搜索 | Claude Code | 外部参考 |
+| OpenAI 插件市场 | Web 搜索 | Codex | 外部参考 |

 对每个搜索结果，记录：
 - 技能名称、作者、版本
@ -52,8 +53,10 @@
 ## 调研报告：<功能描述>

 ### 已有技能
-| 名称 | 平台 | 功能覆盖度 | 活跃度 | 备注 |
-|------|------|-----------|--------|------|
+| 名称 | 来源 | 命名空间 | 功能覆盖度 | 活跃度 | 备注 |
+|------|------|---------|-----------|--------|------|
+
+> **来源标注**：`SkillHub`（团队内部）/ `ClawHub`（外部）/ `其他`

 ### 框架可行性
 - ✅ 支持的功能：...
--- a/skills/skill-discover/skill.json
+++ b/skills/skill-discover/skill.json
@ -1,6 +1,6 @@
 {
  "name": "skill-discover",
-  "version": "0.1.0",
+  "version": "0.2.0",
  "description": "Research existing skills across platforms, analyze framework capabilities, and assess feasibility before creating a new skill.",
  "type": "lifecycle-stage",
  "stage": "discover",
--- a/skills/skill-lifecycle/prompt.md
+++ b/skills/skill-lifecycle/prompt.md
@ -83,7 +83,7 @@ test     → "测试通过，建议做一次安全审计" → audit
 audit    → "审计通过，可以发布了" → publish
 debug    → "问题已修复，建议重新测试" → test
 update   → "更新完成，建议重新测试和审计" → test
-publish  → "发布成功" → （结束，或建议监控）
+publish  → "发布成功（SkillHub: namespace/slug）" → （结束，或建议监控）
 retire   → "已归档" → （结束）
 ```

--- a/skills/skill-publisher/CHANGELOG.md
+++ b/skills/skill-publisher/CHANGELOG.md
@ -1,5 +1,18 @@
 # Changelog

+## 0.2.0 - 2026-07-01
+
+- 完整集成 SkillHub CLI（`@astron-team/skillhub` v0.1.8）
+- 新增 7 步发布流程（确定目标 → 检查 → 适配 → dry-run → 发布 → 验证 → 注册）
+- 新增格式适配层：Qoder/Codex/Claude Code 的 skill.json + prompt.md → SKILL.md
+- 新增命名空间自动映射（4 个框架 → 4 个 SkillHub 命名空间）
+- 新增 dry-run 校验步骤
+- 新增可见性选择（public / namespace-only / private）
+- 新增发布后验证（搜索确认 + 安装测试）
+- 新增排坑指南和 CLI 命令速查
+- 保留 ClawHub 发布支持（OpenClaw 框架）
+- Hermes Agent 标记为暂不支持
+
 ## 0.1.0 - 2026-07-01

 - 初始版本
--- a/skills/skill-publisher/prompt.md
+++ b/skills/skill-publisher/prompt.md
@ -5,21 +5,46 @@
 ## 核心职责

 1. 发布前检查清单
-2. 平台特定发布流程指导
-3. 发布后验证
-
-> **注意**：SkillHub 的详细规范将由用户稍后提供，当前版本先支持通用发布流程和各已知平台。
+2. 格式适配（各框架格式 → SkillHub SKILL.md）
+3. SkillHub CLI 发布流程
+4. 发布后验证

 ---

-## 发布流程
+## 平台与命名空间映射
+
+| 框架 | SkillHub 命名空间 | 框架目录 | SkillHub 支持 |
+|------|------------------|---------|--------------|
+| OpenClaw | `sola-openclaw-work` | `openclaw/skills/` | ✅ 原生兼容 |
+| Claude Code | `sola-claude-code-work` | `claude-code/skills/` | ✅ 需格式适配 |
+| Codex | `sola-codex-work` | `codex/skills/` | ✅ 需格式适配 |
+| Qoder | `sola-qoder-work` | `qoder/skills/` | ✅ 需格式适配 |
+| Hermes Agent | 暂无 | `hermes-agent/skills/` | ❌ 等待官方支持 |
+
+SkillHub 平台：`https://skill.solahqb22.cn`
+CLI 工具：`@astron-team/skillhub`（`skillhub` 命令）
+
+---
+
+## 发布流程（7 步）

 ### Step 1: 确定发布目标

 询问用户：
 - 要发布的技能名称和路径
- 目标框架
- 目标平台（SkillHub / ClawHub / 其他）
+- 目标平台（默认 SkillHub，也可选 ClawHub）
+
+**自动推断框架和命名空间**：根据技能路径自动确定：
+
+| 路径包含 | 框架 | 命名空间 |
+|---------|------|---------|
+| `openclaw/skills/` | OpenClaw | `sola-openclaw-work` |
+| `claude-code/skills/` | Claude Code | `sola-claude-code-work` |
+| `codex/skills/` | Codex | `sola-codex-work` |
+| `qoder/skills/` | Qoder | `sola-qoder-work` |
+| `hermes-agent/skills/` | Hermes Agent | ⚠️ 暂不支持，提示用户 |
+
+如果用户指定的路径不在上述目录中，主动询问框架和命名空间。

 ### Step 2: 发布前检查清单

@ -47,11 +72,166 @@

 如有未通过项，提示用户先完成对应阶段。

-### Step 3: 平台特定发布流程
+### Step 3: 格式适配

-根据目标平台提供指导：
+根据框架类型，准备符合 SkillHub 规范的发布目录。

-#### ClawHub（OpenClaw）
+#### OpenClaw（原生兼容）
+
+OpenClaw 已有 `SKILL.md`，仅需验证 frontmatter：
+
+```yaml
+---
+name: <skill-name>
+description: >
+  <一句话描述>
+---
+```
+
+检查项：
+- `name` 和 `description` 字段存在且非空
+- `description` 建议使用多行块标量（`>`）格式
+- 如不满足，提示用户修改
+
+直接使用原目录发布，无需转换。
+
+#### Qoder / Codex / Claude Code（需格式适配）
+
+这些框架使用 `skill.json` + `prompt.md`，需要合并生成 `SKILL.md`：
+
+**转换规则**：
+1. 从 `skill.json` 提取 `name` 和 `description`
+2. 生成 YAML frontmatter
+3. 将 `prompt.md` 全部内容作为 SKILL.md 正文
+4. 复制 `references/`、`scripts/` 目录（如存在）
+
+**生成的 SKILL.md 格式**：
+
+```yaml
+---
+name: <从 skill.json 的 name 字段>
+description: >
+  <从 skill.json 的 description 字段>
+---
+
+<prompt.md 的完整内容>
+```
+
+**发布目录生成位置**：
+
+```
+<framework>/publish/.staging/<skill-name>/
+├── SKILL.md              # 合并生成
+├── references/           # 复制（如有）
+└── scripts/              # 复制（如有）
+```
+
+发布完成后清理 `.staging/` 目录。
+
+#### Hermes Agent（不支持）
+
+提示用户：
+
+> SkillHub 目前不支持 Hermes Agent 框架。建议等待官方支持后发布，
+> 或考虑将技能转换为 OpenClaw/Claude Code 格式后发布。
+
+终止发布流程。
+
+### Step 4: Dry-run 校验
+
+在正式发布前，用 dry-run 模式验证：
+
+```bash
+skillhub publish <发布目录路径> \
+  --namespace <命名空间> \
+  --dry-run
+```
+
+**检查 dry-run 输出**：
+- 如果报错，根据错误信息修复后重新 dry-run
+- 常见错误：
+  - `SKILL.md frontmatter 缺 name 或 description` → 检查格式适配结果
+  - `500 Internal Server Error` → 通常是 frontmatter 格式问题
+- 如果通过，进入 Step 5
+
+### Step 5: 正式发布
+
+询问用户可见性：
+
+| 可见性 | 说明 |
+|--------|------|
+| `public` | 所有人可见和安装 |
+| `namespace-only` | 仅命名空间内成员可见 |
+| `private` | 仅自己可见 |
+
+执行发布：
+
+```bash
+skillhub publish <发布目录路径> \
+  --namespace <命名空间> \
+  --visibility <可见性>
+```
+
+**更新已发布技能**：同一 slug 重复 `publish` 即可，SkillHub 按 `namespace/slug` 唯一，版本号自动追加时间戳。
+
+### Step 6: 发布后验证
+
+1. **搜索确认**：
+   ```bash
+   skillhub search <skill-name>
+   ```
+   确认技能在搜索结果中可见
+
+2. **安装测试**（可选）：
+   ```bash
+   skillhub install <namespace>/<skill-name> \
+     --agent <目标Agent> \
+     --dir /tmp/test-install
+   ```
+   确认安装成功且文件完整
+
+3. **信息检查**：确认平台展示的名称、描述是否正确
+
+### Step 7: 更新本地注册表
+
+发布成功后：
+
+1. 更新 `<framework>/publish/registry.json`：
+
+```json
+{
+  "skills": [
+    {
+      "name": "<skill-name>",
+      "slug": "<namespace>/<skill-name>",
+      "version": "<version>",
+      "description": "<description>",
+      "namespace": "<namespace>",
+      "visibility": "<visibility>",
+      "publishedAt": "<date>",
+      "platform": "SkillHub"
+    }
+  ]
+}
+```
+
+2. 在 `CHANGELOG.md` 中添加发布记录：
+
+```markdown
+### Published
+- 发布到 SkillHub (`<namespace>/<skill-name>`)，可见性：<visibility>
+```
+
+3. 清理发布暂存目录（如使用了格式适配）：
+   ```bash
+   rm -rf <framework>/publish/.staging/
+   ```
+
+---
+
+## ClawHub 发布（备选平台）
+
+如果用户选择发布到 ClawHub（仅限 OpenClaw 框架）：

 ```bash
 # 认证
@ -70,50 +250,27 @@ openclaw skills publish <absolute-path> \
 - 使用绝对路径
 - YAML frontmatter 仅含 name 和 description

-#### Qoder
+---

-```bash
-# 发布到 Qoder 技能市场（具体命令待确认）
-qoder skills publish <skill-path>
-```
+## 排坑指南

-#### SkillHub（通用平台）
+| 现象 | 原因 | 解决 |
+|------|------|------|
+| `publish` 报 500 | SKILL.md frontmatter 缺 name 或 description | 补齐 frontmatter，`--dry-run` 先校验 |
+| `publish` 报 401 | Token 过期或缺 publish scope | 重新 `skillhub login` |
+| Agent 参数不识别 | 只认精确 profile 名 | 用 `claude-code`（含短横线），不要用 `claude` |
+| `whoami` 报 401 | Token 过期/被撤销 | 重新 `skillhub login` |

-> 规范待用户提供后补充。
+## SkillHub CLI 命令速查

-#### 其他平台
-
-根据框架类型，参考 `meta-skills/create-<framework>-skill/prompt.md` 中的发布章节。
-
-### Step 4: 更新本地注册表
-
-发布成功后，更新 `<framework>/publish/registry.json`：
-
-```json
-{
-  "skills": [
-    {
-      "name": "<skill-name>",
-      "version": "<version>",
-      "description": "<description>",
-      "publishedAt": "<date>",
-      "platform": "<platform>"
-    }
-  ]
-}
-```
-
-### Step 5: 发布后验证
-
-1. 在目标平台上搜索确认技能可见
-2. 用全新环境安装/加载技能，确认正常工作
-3. 检查平台展示信息是否正确（名称、描述、版本）
-
-### Step 6: 通知和记录
-
-建议在 CHANGELOG.md 中添加发布记录：
-
-```markdown
-### Published
- 发布到 <platform>，版本 <version>
-```
+| 命令 | 用途 |
+|------|------|
+| `skillhub login --registry https://skill.solahqb22.cn --token <TOKEN>` | 登录 |
+| `skillhub whoami` | 查看当前身份 |
+| `skillhub search <keyword>` | 搜索技能 |
+| `skillhub publish <path> --namespace <ns>` | 发布技能 |
+| `skillhub publish <path> --namespace <ns> --dry-run` | 校验不上传 |
+| `skillhub install <slug> --agent <profile>` | 安装技能 |
+| `skillhub list` | 列出本机已安装 |
+| `skillhub remove <slug> --remote --hard --namespace <ns>` | 从服务端删除 |
+| `skillhub doctor` | 扫描本机技能清单 |
--- a/skills/skill-publisher/skill.json
+++ b/skills/skill-publisher/skill.json
@ -1,8 +1,25 @@
 {
  "name": "skill-publisher",
-  "version": "0.1.0",
-  "description": "Publish skills to SkillHub and other platforms with pre-publish checklist and platform-specific guidance.",
+  "version": "0.2.0",
+  "description": "Publish skills to SkillHub and other platforms with format adaptation, pre-publish checklist, and post-publish verification.",
  "type": "lifecycle-stage",
  "stage": "publish",
-  "tags": ["publish", "deploy", "release", "skillhub"]
+  "tags": ["publish", "deploy", "release", "skillhub", "clawhub"],
+  "platforms": {
+    "skillhub": {
+      "url": "https://skill.solahqb22.cn",
+      "cli": "@astron-team/skillhub",
+      "namespaces": {
+        "openclaw": "sola-openclaw-work",
+        "claude-code": "sola-claude-code-work",
+        "codex": "sola-codex-work",
+        "qoder": "sola-qoder-work"
+      }
+    },
+    "clawhub": {
+      "url": "https://clawhub.ai",
+      "cli": "openclaw",
+      "frameworks": ["openclaw"]
+    }
+  }
 }
--- a/skills/skill-retire/CHANGELOG.md
+++ b/skills/skill-retire/CHANGELOG.md
@ -1,5 +1,11 @@
 # Changelog

+## 0.2.0 - 2026-07-01
+
+- 新增 SkillHub 服务端删除支持（`skillhub remove --remote --hard`）
+- 新增 SkillHub 命名空间映射（4 个框架 → 4 个命名空间）
+- 区分本机移除和服务端删除两种操作
+
 ## 0.1.0 - 2026-07-01

 - 初始版本
--- a/skills/skill-retire/prompt.md
+++ b/skills/skill-retire/prompt.md
@ -82,9 +82,32 @@

 | 平台 | 操作 |
 |------|------|
+| **SkillHub** | `skillhub remove <namespace>/<slug> --remote --hard --namespace <namespace>` |
 | **ClawHub** | `openclaw skills deprecate <slug>` 或手动标记 |
 | **Qoder** | 从 `registry.json` 移除，更新技能市场状态 |
-| **SkillHub** | （待规范提供后补充） |
+
+### SkillHub 命名空间映射
+
+| 框架 | 命名空间 |
+|------|---------|
+| OpenClaw | `sola-openclaw-work` |
+| Claude Code | `sola-claude-code-work` |
+| Codex | `sola-codex-work` |
+| Qoder | `sola-qoder-work` |
+
+### SkillHub 删除示例
+
+```bash
+# 从服务端删除（不可逆）
+skillhub remove sola-openclaw-work/my-skill \
+  --remote --hard \
+  --namespace sola-openclaw-work
+
+# 仅从本机 Agent 移除（保留服务端）
+skillhub remove sola-openclaw-work/my-skill --agent openclaw
+```
+
+> ⚠️ `--remote --hard` 操作不可逆，执行前务必确认用户意图。

 ### Step 5: 本地归档

--- a/skills/skill-retire/skill.json
+++ b/skills/skill-retire/skill.json
@ -1,6 +1,6 @@
 {
  "name": "skill-retire",
-  "version": "0.1.0",
+  "version": "0.2.0",
  "description": "Manage skill deprecation with graceful retirement workflow, migration guidance, and archival.",
  "type": "lifecycle-stage",
  "stage": "retire",