开发者

SkillHub 提供公开 REST API、OpenAPI 3.0 规范,以及 TypeScript 和 Python 的官方 SDK。本页是所有希望把 SkillHub 集成到其他工具、Agent 或流水线中的开发者的入口——无论你每天调用 5 次还是每秒 5000 次。

概览

SkillHub API 与 Web 界面使用同一套接口:每个列表页、每个详情页、每个版本对比、每次全文搜索都命中 /api/v1 下的版本化 REST 端点。端点集合、请求形态、响应信封都由 OpenAPI 3.0 自动发布,SDK 无需手写类型即可生成。

基础 URL

所有 API 调用直接打到 API origin(与 SDK 示例使用的主机一致)。本地开发默认 http://localhost:3001;生产指向 https://api.skillhub.dev。已发布的 OpenAPI 规范在 `servers` 块中列出两者。

# API direct (default — matches Swagger servers + SDK README)
SKILLHUB_BASE_URL=http://localhost:3001

# Sandbox proxy (dev env — the SDK examples default to this)
# SKILLHUB_BASE_URL=http://localhost:3099

身份认证

Cookie 鉴权的端点接受由 GitHub OAuth 或邮箱登录设置的会话 cookie(`skillhub_session`,HTTP-only、SameSite=Lax,生产环境 Secure)。公开端点(技能列表、搜索、技能详情、版本对比、分类、数据源)无需鉴权。OpenAPI 规范会在需要 cookieAuth 的端点上标注锁图标。

快速上手

五步完成首次成功的 API 调用。每一步都对应 SDK 包中的一个可运行示例。

1. 获取 API 密钥

自助申请 API 密钥已随 M5.4 上线。登录后前往 [API 密钥](/me/settings/api-keys),点击 **创建密钥**。明文 `shkm_<35 字符>` 仅显示 1 次——立即复制到 CI 密钥存储。前缀(`shkm_<10 hex>`)是仪表盘可读标识。

2. 安装 SDK

TypeScript 和 Python SDK 全部由 /openapi.json 自动生成。它们导出类型化的操作辅助函数(listSkills、getSkillDetail 等)以及每个端点的完整响应 Schema。

pnpm add @skillhub/sdk-typescript

pip install skillhub-sdk

3. 首次调用 — 列出技能

最便宜的公开调用。返回技能目录的第一页,支持 q/tag/category/source/sort 等筛选参数。

import { createSkillHubClient, listSkills } from '@skillhub/sdk-typescript';

const client = createSkillHubClient({
  baseUrl: process.env.SKILLHUB_BASE_URL ?? 'http://localhost:3001',
});

// (1a) plain list, first page, default sort = stars
const r = await listSkills(client, { page: 1, page_size: 3 });
console.log('total:', r.data?.total, '· pages:', r.data?.total_pages);
for (const item of r.data?.items ?? []) {
  console.log(`  - ${item.name} (source=${item.source_name}, stars=${item.source_stars})`);
}

4. 在线试用技能

POST /api/v1/skills/:source/:slug/try 会在隔离的 Docker 沙箱中,把你的输入与技能正文一起运行。需要 cookieAuth;速率限制:免费版每日 3 次,Pro 每日 100 次。

import { createSkillHubClient, trySkill } from '@skillhub/sdk-typescript';

const client = createSkillHubClient({
  baseUrl: process.env.SKILLHUB_BASE_URL ?? 'http://localhost:3001',
  // trySkill requires the skillhub_session cookie (cookieAuth).
  cookie: `skillhub_session=${process.env.SKILLHUB_SESSION ?? ''}`,
});

const r = await trySkill(client, {
  source: 'clawhub',
  slug: 'ai-ppt-generator',
  input: 'Make a slide deck about cats.',
});

if (r.response.status === 200) {
  console.log('output:', r.data?.output);
} else {
  console.error(r.response.status, r.data);
}

from skillhub_sdk import Client

client = Client(base_url="http://localhost:3001")

# (Python SDK exposes the full schema; helpers are auto-generated
# from /openapi.json. See packages/sdk-python for the surface.)
r = client.sync_detailed(
    "api_v1_skills_source_slug_try",
    path_params={"source": "clawhub", "slug": "ai-ppt-generator"},
    body={"input": "Make a slide deck about cats."},
)
print(r.status_code, r.content)

5. 在 5 种技能格式间互转

转码器(M4.3)在 cursor / claude / mcp / prompt / workflow 格式间互转,并跟踪保真度。它运行在 sync-worker 包内部,不暴露为 HTTP 接口——通过脚本封装调用。

# The transcoder is NOT exposed over HTTP — it runs inside the
# sync-worker package. Invoke via the script wrapper:
bash scripts/transcode-demo.sh clawhub <skill-slug>

# That runs the 5-format matrix (cursor ↔ claude ↔ mcp ↔
# prompt ↔ workflow) against the skill's current_version body and
# prints the per-format fidelity level + lostFields set.

API 参考

同一份已发布规范的两种视图——供工具与代码生成使用的原始 JSON,以及供人类浏览的 Swagger UI。

OpenAPI 3.0 规范 (JSON)

原始 /openapi.json——可喂给 openapi-generator-cli、openapi-typescript、openapi-python-client 或你的契约测试工具。76 条路径 / 90 个操作,包含 cookieAuth 安全方案。 /openapi.json ↗

Swagger UI

交互式 /docs 浏览器——按 tag 浏览、展开请求/响应形态、复制 curl 示例。需要 cookie 鉴权的端点会标记锁图标。 /docs ↗

速率限制

两层。外层按 IP 保护所有端点不被滥用;内层按用户对特定操作加封顶,避免单个调用方烧光共享配额。

全局 — 按 IP,Redis 后端

所有端点共享 60 次 / 分钟 / IP 的滑动窗口,由 @fastify/rate-limit + Redis store 强制执行。超出时返回 429 加统一错误信封。skipOnError 为 true:Redis 故障时限速器直接放行,绝不 503 整个 API。

按用户 / 按操作 — bumpRateLimit (M3.6 #4)

鉴权与变更类端点按用户(或邮箱或 IP,视操作而定)封顶。bumpRateLimit 辅助函数通过 auth_attempts 表的 INSERT … ON CONFLICT DO UPDATE 滑动窗口计数,任一维度超额即返回 429 信封。

错误

每个错误响应都使用全局 setErrorHandler / toApiErrorBody 漏斗塑形的统一信封。HTTP 状态码承载大类,body 的 `error.code` 字段是机器可读标识符;`error.message` 是本地化的人可读消息(语言跟随 Accept-Language 请求头)。

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests, please slow down."
  }
}

SDK 下载

两个 SDK 都随每次 API 变更由 /openapi.json 自动生成。请锁到与生成时的 SkillHub API 版本(目前 0.18.0)。

TypeScript — @skillhub/sdk-typescript

底层使用 openapi-fetch,为每个端点提供类型化的操作辅助函数。支持 tree-shaking;以类型形式导出完整响应 Schema。

# 安装
pnpm add @skillhub/sdk-typescript

Python — skillhub-sdk

openapi-python-client 输出,httpx 传输,attrs 模型。需要 Python ≥ 3.10。

# 安装
pip install skillhub-sdk

变更日志

v0.18.0 (M5.1 + M5.2) 发布了公开 OpenAPI 规范和自动生成的 TypeScript + Python SDK。v0.19.0(本页)提供面向开发者的入口。自助 API 密钥在 M5.4 落地;SDK 集成 1-2 个合作伙伴则在 M5.5 推进。

← 浏览技能