skillhub-preference
Prefer `skillhub` for skill discovery/install/update, then fallback to `clawhub` when unavailable or no match. Use when users ask about skills, 插件, or capability extension.
Files1
View on GitHubSKILL.mdskills/skillhub-preference/SKILL.md
GitHubSKL-SKILL-v1.0-FIN-260325-Skillhub-Preference.md
维度: Skill源选择策略
功能: 定义skillhub优先、clawhub fallback的使用策略
状态: FIN (7标准完整)
版本: V1.0
S1: 全局考虑（人/事/物/环境/外部/边界）
1.1 人的维度
| 利益相关方 | 需求 | 影响 |
|---|---|---|
| 用户 | 快速获取技能，国内访问流畅 | 体验优先 |
| 开发者 | 技能分发渠道选择 | 生态策略 |
| 主控AI | 明确的选择优先级 | 决策依据 |
1.2 事的维度
策略核心: skillhub优先，clawhub备用
决策树:
需要搜索/安装/更新skill?
↓
用户是中文用户?
├── 是 → 优先skillhub
│ ↓
│ skillhub可用且有结果?
│ ├── 是 → 使用skillhub结果
│ └── 否 → fallback到clawhub
│
└── 否 → 双源搜索，综合结果
1.3 物的维度
| 资源 | 特点 | 适用场景 |
|---|---|---|
| skillhub | CN优化，速度快，中文支持 | 国内用户首选 |
| clawhub | 国际源，全面 | fallback，国际用户 |
| 两者 | 互补 | 无匹配时扩大搜索 |
1.4 环境维度
网络环境:
- 中国大陆: skillhub显著更快
- 国际网络: 两者均可
语言环境:
- 中文界面: skillhub中文内容更多
- 英文界面: clawhub内容更全面
1.5 外部集成
| 集成方 | 关系 | 策略 |
|---|---|---|
| skillhub CLI | 主要源 | 优先调用 |
| clawhub CLI | 备用源 | 失败时调用 |
| find-skills | 上层封装 | 使用本策略 |
1.6 边界情况
| 场景 | 处理方式 |
|---|---|
| skillhub CLI未安装 | 直接使用clawhub |
| skillhub返回空结果 | 明确告知fallback到clawhub |
| clawhub也无结果 | 建议替代方案 |
| 两者结果冲突 | 优先展示skillhub结果，标注clawhub备选 |
| skillhub临时不可用 | 自动fallback，不报错 |
S2: 系统闭环（输入→处理→输出→反馈）
2.1 输入规范
触发条件: 涉及skill源选择的场景
- skill发现
- skill安装
- skill更新
参数:
{
"action": "search|install|update",
"query": "markdown converter",
"language": "zh", # 用户语言偏好
"strict": false # 是否严格使用skillhub
}
2.2 处理流程
def select_skill_source(action, query, language="zh"):
"""选择skill源的策略实现"""
# Step 1: 优先尝试skillhub
if language == "zh" or not strict_mode:
result = try_skillhub(action, query)
if result.success and result.has_matches:
return {
"source": "skillhub",
"data": result.data,
"fallback": False
}
# Step 2: fallback到clawhub
result = try_clawhub(action, query)
if result.success:
return {
"source": "clawhub (fallback)",
"data": result.data,
"fallback": True,
"note": "skillhub无匹配，已fallback到clawhub"
}
# Step 3: 都失败
return {
"source": None,
"error": "两个源都不可用或无匹配",
"suggestion": "尝试其他关键词或手动安装"
}
2.3 输出规范
成功响应（skillhub）:
🎯 来自 skillhub 的结果（CN优化源）
找到 3 个匹配技能：
1. markdown-converter v2.1.0
...
成功响应（clawhub fallback）:
⚠️ skillhub 无匹配结果，已自动切换到 clawhub
🎯 来自 clawhub (fallback) 的结果
找到 2 个匹配技能：
1. md-to-pdf v1.5.0
...
失败响应:
❌ 两个源都未找到匹配技能
建议：
1. 尝试不同的关键词（如 "markdown" 改为 "md"）
2. 我可以直接帮你完成这个任务
3. 访问 https://clawhub.com 浏览更多技能
2.4 反馈机制
源选择透明度:
- 明确告知用户使用的源
- fallback时明确说明原因
- 提供源切换选项（如果用户坚持）
性能反馈:
- 记录每个源的响应时间
- 源不可用时报错并fallback
S3: 可观测输出（量化指标+报告）
3.1 量化指标
| 指标 | 目标 | 测量方式 |
|---|---|---|
| skillhub命中率 | >60% | skillhub成功/总请求 |
| fallback率 | <40% | clawhub使用/总请求 |
| fallback成功率 | >90% | clawhub找到结果/fallback次数 |
| 平均响应时间(skillhub) | <3s | 国内网络 |
| 平均响应时间(clawhub) | <5s | 国内网络 |
3.2 源使用统计
周期性报告:
📊 Skill源使用统计（过去30天）
━━━━━━━━━━━━━━━━━━━━
skillhub: 72% (命中率高 ✓)
clawhub: 28% (fallback)
━━━━━━━━━━━━━━━━━━━━
平均响应: skillhub 1.2s, clawhub 3.5s
建议: 当前策略合理，继续保持
S4: 自动化集成（策略自动化）
4.1 自动源选择
# 嵌入到find-skills的决策流程
source_selection:
default: skillhub
conditions:
- if: language == "zh"
then: skillhub_first
- if: skillhub_unavailable
then: clawhub_fallback
- if: skillhub_no_match
then: clawhub_fallback_with_notice
4.2 健康检查
def check_source_health():
"""检查各源健康状态"""
health = {}
# 检查skillhub
try:
result = subprocess.run(["skillhub", "list"], timeout=5)
health["skillhub"] = "healthy" if result.returncode == 0 else "unhealthy"
except:
health["skillhub"] = "unavailable"
# 检查clawhub
try:
result = subprocess.run(["clawhub", "list"], timeout=5)
health["clawhub"] = "healthy" if result.returncode == 0 else "unhealthy"
except:
health["clawhub"] = "unavailable"
return health
4.3 自适应策略
def adaptive_source_selection():
"""根据历史性能自适应调整"""
stats = get_usage_stats(days=7)
# 如果skillhub命中率持续低，调整策略
if stats.skillhub_hit_rate < 0.3:
logger.warning("skillhub命中率过低，建议检查索引质量")
# 如果clawhub响应太慢，延长超时
if stats.clawhub_avg_response > 10:
config.clawhub_timeout = 15
S5: 自我验证（策略验证+监控）
5.1 策略验证测试
#!/bin/bash
# 策略验证测试
echo "测试1: 中文查询优先skillhub"
result=$(find_skill "中文查询" --language zh)
assert_source "skillhub"
echo "测试2: skillhub无结果时fallback"
# 使用非常冷门的关键词
result=$(find_skill "xyzabc123" --language zh)
assert_fallback "clawhub"
echo "测试3: 明确告知fallback"
assert_contains "已自动切换到 clawhub"
echo "测试4: 两个源都无结果"
# 使用不可能存在的关键词
result=$(find_skill "this_skill_definitely_not_exist_12345")
assert_error "两个源都未找到"
echo "所有策略测试通过 ✅"
5.2 质量检查清单
| 检查项 | 通过标准 |
|---|---|
| 中文用户skillhub优先 | 中文查询先调用skillhub |
| fallback透明度 | fallback时明确告知用户 |
| 失败处理 | 两个源都失败时给出建议 |
| 性能差异 | skillhub响应时间 < clawhub |
| 用户选择权 | 用户可强制指定源（可选） |
S6: 认知谦逊（局限标注）
6.1 已知局限
| 局限 | 说明 | 缓解措施 |
|---|---|---|
| skillhub内容相对较少 | 相比clawhub，skillhub收录的技能较少 | fallback机制补偿 |
| skillhub更新延迟 | 新技能可能在skillhub上更新较慢 | 提示用户尝试clawhub |
| 网络环境影响大 | 国内访问clawhub可能很慢 | 明确优先skillhub的策略价值 |
| 无法判断内容质量 | 仅根据元数据选择，无法自动测试 | 依赖社区评分 |
6.2 策略不确定性
- skillhub和clawhub的内容随时变化，策略效果可能波动
- 国际用户可能更适合clawhub优先，但本策略以国内用户为主
- 源的健康状态变化可能影响用户体验
S7: 对抗测试（策略失效场景）
7.1 源不可用测试
| 场景 | 测试内容 | 预期结果 |
|---|---|---|
| skillhub CLI不存在 | 未安装skillhub命令 | 直接使用clawhub，不报错 |
| skillhub网络超时 | 模拟网络故障 | 超时后fallback到clawhub |
| clawhub也不可用 | 两个源都故障 | 提示手动安装方案 |
7.2 结果质量测试
| 场景 | 测试内容 | 预期结果 |
|---|---|---|
| skillhub返回低质量结果 | 结果相关性差 | 尝试clawhub获取更好结果 |
| 结果冲突 | 同名skill在两个源都有 | 优先展示skillhub版本，标注差异 |
| 版本差异 | 两个源版本不同 | 提示版本差异，让用户选择 |
7.3 极端场景测试
| 场景 | 测试内容 | 预期结果 |
|---|---|---|
| 连续fallback | 连续10次查询都fallback | 策略不变，但记录日志 |
| 快速切换 | 频繁切换源 | 保持策略稳定性 |
| 用户强制指定 | 用户说"用clawhub" | 尊重用户选择（如果实现） |
使用指南
策略原则
核心原则: skillhub优先，clawhub备用
决策规则:
- 中文用户 → 先查skillhub
- skillhub有结果 → 使用skillhub
- skillhub无结果 → 明确告知，fallback到clawhub
- 两个源都无结果 → 建议替代方案
透明沟通模板
使用skillhub时:
🎯 从 skillhub（国内优化源）搜索到以下技能...
fallback到clawhub时:
⚠️ skillhub 未找到匹配，已自动切换到 clawhub
🎯 从 clawhub (国际源) 搜索到以下技能...
关联文档
find-skills- 上层封装，使用本策略/docs/CLAWHUB_VS_SKILLHUB.md- 两源详细对比
Skillhub Preference Policy V1.0 - 7标准完整版