Claude Code 接入 SkillHub 指南

[FenjuFu]

Claude Code 接入 SkillHub 指南

本指南介绍如何让 Claude Code 使用 SkillHub 私有技能注册中心:通过 ClawHub 兼容层把技能装进 Claude Code 会自动发现的目录,实现搜索、安装、发布。

SkillHub 没有专门的 claude 插件命令——它对接 Claude Code 的方式,是把技能下载到 Claude Code 默认扫描的 .claude/skills/(或 .agent/skills/)目录,Claude Code 启动时自动加载。

前置条件

• 已安装 Claude Code
• Node.js 18+(用于运行 ClawHub CLI)
• 一个可访问的 SkillHub 实例地址(自建或团队提供)

1. 安装 ClawHub CLI

SkillHub 提供与 ClawHub 兼容的 Registry API,直接用 clawhub CLI 对接:

npm install -g clawhub
# 或免安装直接用:npx clawhub ...

2. 指向你的 SkillHub 实例

通过环境变量把 Registry 指到 SkillHub,而不是公共 ClawHub。

Linux / macOS (bash/zsh):

# 写入 ~/.bashrc 或 ~/.zshrc
export CLAWHUB_REGISTRY=https://skillhub.your-company.com
export CLAWHUB_SITE=https://skillhub.your-company.com

Windows (PowerShell):

# 永久(当前用户)
[Environment]::SetEnvironmentVariable('CLAWHUB_REGISTRY', 'https://skillhub.your-company.com', 'User')
[Environment]::SetEnvironmentVariable('CLAWHUB_SITE',     'https://skillhub.your-company.com', 'User')

# 或临时(仅当前会话)
$env:CLAWHUB_REGISTRY = 'https://skillhub.your-company.com'

把 skillhub.your-company.com 换成你的实例地址。也可在单条命令上用标志覆盖:
clawhub --registry https://skillhub.your-company.com install <skill>

3. 登录认证(按需)

场景	是否需要登录
@global 命名空间下的 PUBLIC 技能(下载)	❌ 无需登录
团队命名空间的技能(任意可见性)	✅ 需要
NAMESPACE_ONLY / PRIVATE 技能	✅ 需要
发布、收藏等写操作	✅ 需要

获取并使用 API Token:

1. 登录 SkillHub Web UI
2. 进入 个人设置 → API Tokens → 创建新 Token,设置名称与权限范围
3. 复制 Token 后登录:

clawhub login --token sk_your_api_token_here

4. 搜索与安装技能

clawhub search email                 # 搜索技能
clawhub info my-skill                # 查看技能详情
clawhub install my-skill             # 安装最新已发布版本
clawhub install my-skill@1.2.0       # 安装指定版本
clawhub install my-skill@beta        # 按标签安装
clawhub install team-name--my-skill  # 安装团队命名空间下的技能

命名空间映射:SkillHub 内部用 @{namespace}/{skill} 坐标,兼容层会自动转换为 ClawHub 风格的 canonical slug:

• @global/my-skill → my-skill
• @my-team/my-skill → my-team--my-skill

5. Claude Code 自动加载

安装后,技能按下列优先级落盘,Claude Code 会自动发现并加载,无需额外配置:

优先级	路径	说明
1	./.agent/skills/	项目级(universal 模式)
2	~/.agent/skills/	全局级(universal 模式)
3	./.claude/skills/	项目级(Claude 默认)
4	~/.claude/skills/	全局级(Claude 默认)

• 只想在当前项目用 → 装到项目级路径(./.claude/skills/)
• 想在所有项目都可用 → 装到全局级路径(~/.claude/skills/)

回到 Claude Code,输入 /<skill-name> 即可调用。

6. 发布技能(可选)

clawhub publish ./my-skill

权限要求:

• 发布到全局命名空间(@global)需要 SUPER_ADMIN 权限
• 发布到团队命名空间需要是该命名空间的 OWNER 或 ADMIN

验证连接

# Well-known 发现(应返回 {"apiBase":"/api/v1"})
curl https://skillhub.your-company.com/.well-known/clawhub.json

# 当前用户(需带 Token)
curl https://skillhub.your-company.com/api/v1/whoami \
  -H "Authorization: Bearer YOUR_TOKEN"

# 搜索
curl "https://skillhub.your-company.com/api/v1/search?q=test"

常见问题

Q:下载技能时提示 403 Forbidden?
可能是:① 技能属于团队命名空间需登录;② 技能为 NAMESPACE_ONLY/PRIVATE;③ 你不是该命名空间成员;④ Token 已过期。重新 clawhub login --token <新 Token> 后再试。

Q:如何切换回公共 ClawHub?

unset CLAWHUB_REGISTRY   # Windows: [Environment]::SetEnvironmentVariable('CLAWHUB_REGISTRY', $null, 'User')

Q:启用调试日志?

DEBUG=clawhub:* npx clawhub search my-skill
# 或
npx clawhub --verbose install my-skill

进一步阅读

• OpenClaw 集成指南
• CLI 兼容层
• 技能协议规范