# Skill Hub (ClawHub) 兼容性

## 概述

PyClaw 完全兼容 OpenClaw 的 [ClawHub](https://clawhub.ai) 技能生态。任一工具安装的技能对双方都可用。

## 什么是 Skill？

技能是一个包含 `SKILL.md` 的目录 — 带 YAML frontmatter 的 Markdown 文件：

```yaml
---
name: my-skill
description: "这个技能做什么，什么时候用"
metadata:
  openclaw:
    emoji: "🔧"
    requires:
      bins: ["some-binary"]     # 必须全部在 PATH 中
      anyBins: ["alt1", "alt2"] # 至少一个在 PATH 中
      env: ["SOME_API_KEY"]     # 必需的环境变量
    install:
      - kind: brew
        formula: "package-name"
      - kind: node
        package: "@scope/pkg"
      - kind: uv
        package: "httpie"
---

# 技能指令 (Markdown)

这些指令会注入 agent 的系统 prompt...
```

技能不是代码 — 是给 AI agent 的 prompt（指令）。语言无关。

## ClawHub API

Base URL: `https://clawhub.ai`

| Endpoint | 用途 |
|----------|------|
| GET /api/v1/search?q=... | 搜索技能 |
| GET /api/v1/skills/{slug} | 技能详情 |
| GET /api/v1/download?slug=...&version=... | 下载 ZIP |
| GET /api/v1/skills | 列出全部技能 |

认证: `Authorization: Bearer {token}`（来自 `CLAWHUB_TOKEN` 环境变量或 `~/.config/clawhub/config.json`）

## 安装流程

1. GET `/api/v1/skills/{slug}` → 获取元数据 + 最新版本
2. GET `/api/v1/download?slug={slug}&version={version}` → 下载 ZIP
3. 解压 ZIP，验证 SKILL.md 存在
4. 安装到 `{workspace}/skills/{slug}/`
5. 写入 `.clawhub/origin.json`（registry, slug, version, installedAt）
6. 更新 `.clawhub/lock.json`（workspace 级版本跟踪）

## 共享目录

PyClaw 读取 `~/.openclaw/skills/` — 与 OpenClaw 管理技能的目录相同。通过 OpenClaw 的 `clawhub install` 命令安装的技能对 PyClaw 立即可用。

## 发现顺序（高 → 低优先级）

PyClaw 按优先级扫 7 个分层 source。同名 skill 在多个 source 都存在时,优先级最高
的赢。每一层都遵循"越靠近用户/项目越优先 → 越靠近厂商越靠后"的轴。

| # | Source | 默认路径 | 层级 |
|---|---|---|---|
| 1 | workspace | `{workspace}/skills/` | 项目 |
| 2 | project-agents | `{workspace}/.agents/skills/` | 项目 |
| 3 | project-claude | `{workspace}/.claude/skills/` | 项目 |
| 4 | managed | `~/.openclaw/skills/` | 用户/团队 |
| 5 | personal-agents | `~/.agents/skills/` | 个人 |
| 6 | personal-claude | `~/.claude/skills/` | 个人 |
| 7 | bundled | `<package>/skills/`(默认无) | 厂商 |

每个层级内部(项目层 / 个人层),`.agents/skills/` 胜过 `.claude/skills/`。
原因:`.claude/skills/` 是事实上的跨生态默认 —— Claude Code、Cursor 2.4+、
OpenCode、Crush、DeepSeek-TUI 出厂就用这个目录。`.agents/skills/` 是显式 opt-in
的跨生态规范化路径,所以两者都存在时,优先用户的显式选择更符合意图。

### 跨生态兼容(Sprint 4')

PyClaw 原生读 `~/.claude/skills/` 和 `{workspace}/.claude/skills/`。任何按
[Anthropic Agent Skills v1.0](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills/overview)
SKILL.md 规范写的 skill 不用改就能用 —— 包括
[superpowers](https://github.com/obra/superpowers) skill 库,和任何 git 里
checked-in 的项目级 `.claude/skills/` 目录。

合规要求严的部署可以通过环境变量关掉 PyClaw 对 `.claude/skills/` 路径的读取
(不用改 JSON):

```bash
export PYCLAW_DISABLE_CLAUDE_SKILLS=1
```

设了之后,`personal-claude` 和 `project-claude` 两个 source 完全跳过。
其余 5 个 source 照常扫。

### 配置

所有 7 个路径根都可在 `pyclaw.json` 配置:

```jsonc
{
  "skills": {
    "workspace_skills_dir": "skills",
    "project_agents_skills_dir": ".agents/skills",
    "project_claude_skills_dir": ".claude/skills",
    "managed_skills_dir": "~/.openclaw/skills",
    "personal_agents_skills_dir": "~/.agents/skills",
    "personal_claude_skills_dir": "~/.claude/skills",
    "bundled_skills_dir": null
  }
}
```

## Prompt 注入格式

技能以 XML 形式注入系统 prompt：
```xml
<available_skills>
  <skill>
    <name>github</name>
    <description>GitHub CLI 操作...</description>
    <location>~/.openclaw/skills/github/SKILL.md</location>
  </skill>
</available_skills>
```

Agent 决定使用某个技能时通过 `read` 工具加载完整内容。

## 兼容范围

| 兼容 | 不兼容 |
|------|-------|
| family="skill"（Markdown） | family="code-plugin"（TypeScript） |
| SKILL.md 格式 | bundle-plugin（TypeScript） |
| ClawHub REST API | OpenClaw extension 系统 |
| 安装 spec（brew, node, uv, go, download） | TypeScript 特定工具 |
| .clawhub/lock.json + origin.json | |
| Auth token 共享 | |

## Lockfile 格式

`.clawhub/lock.json`:
```json
{
  "version": 1,
  "skills": {
    "weather": { "version": "1.2.3", "installedAt": 1714500000000 }
  }
}
```

每个技能的 `.clawhub/origin.json`:
```json
{
  "version": 1,
  "registry": "https://clawhub.ai",
  "slug": "weather",
  "installedVersion": "1.2.3",
  "installedAt": 1714500000000
}
```
