# 变更日志

本文档记录 find-best-skill 的所有重要变更。

格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。

---

## [Unreleased]

### Changed
- 版本升级：0.4.0 → 0.4.1；默认缓存目录从 `~/.find-best-skill/` 迁移到当前工作目录下 `.bensz-api/skills/find-best-skill/cache/`，同步更新配置与脚本 fallback。

---

## [0.4.0] - 2026-01-18

### Changed
- **搜索方式简化**：社区调研改用 WebSearch 类工具或搜索类 MCP 工具（如 SearXNG、Tavily）
  - 直接利用模型内置搜索能力，无需依赖 GitHub API
  - 提供 `site:github.com "SKILL.md" {关键词}` 等搜索语法示例
  - GitHub SEO 良好，普通搜索即可获得高质量结果

### Removed
- **移除 `search_github_skills.py`**：功能已被 WebSearch 替代，遵循 KISS 原则
- **移除 `references/github-api.md`**：不再需要 GitHub API 相关文档
- **简化 `config.yaml`**：移除 `platforms.github.search_url` 和 `platforms.github.api_url`

---

## [0.3.1] - 2026-01-18

### Added
- **统一配置加载器**（P1）
  - 新增 `scripts/config_loader.py`，为 scripts 提供 `config.yaml` 单一真相来源

### Fixed
- **GitHub 搜索链接类型修复**（P0）
  - `search_github_skills.py` 生成 GitHub code search（`type=code`），避免 repo 搜索 + code 限定符混用导致的误导
  - `config.yaml:platforms.github.search_url` 同步口径
- **缓存健壮性修复**（P0）
  - `cache_manager.py` 的缓存/索引写入改为原子落盘（降低半写入导致损坏的风险）
  - 缓存 JSON 损坏自动备份并自愈
  - 非法 `cached_at` 不再导致 `--stats/--cleanup` 崩溃（视为已过期）
- **README 配置项口径修复**（P2）
  - 修正 `recommendation.min_count/max_count` 等已不存在的字段名，改为以 `config.yaml` 为准

### Changed
- **缓存参数以 `config.yaml:cache` 为准**（P0）
  - `cache_manager.py` 默认从 `config.yaml` 读取 `dir/ttl_days/max_size/similarity_threshold`（CLI 可覆盖）
- **文档口径同步**（P1）
  - `SKILL.md` 补充“配置来源与覆盖优先级”说明

### Quality
- 通过 auto-test-skill A 轮测试（v202601182019）
  - 验证脚本可运行：`search_github_skills.py`、`cache_manager.py`
  - 验证缓存自愈：损坏 JSON 备份并重置
  - 验证非法时间字段容错：`cached_at=not-iso` 不崩溃（判为 expired）
- 通过 auto-test-skill B 轮质量检查（B轮-v202601182024）

---

## [0.3.0] - 2026-01-18

### Added
- **本地缓存机制**（P0）
  - 新增 `scripts/cache_manager.py` 缓存管理脚本
  - 缓存目录：`~/.find-best-skill/`
  - 支持技能元数据缓存、关键词搜索、相似度匹配
  - TTL 硬编码为 180 天（半年）
  - 自动过期清理、访问时间更新
- **缓存配置**（P0）
  - config.yaml 新增 `cache` 节（enabled, dir, ttl_days, max_size, similarity_threshold）
  - config.yaml 新增 `cache_strategy` 节（on_hit, on_miss, after_search 策略）
- **工作流改造**（P0）
  - 第2步增加"缓存查询"环节
  - 第4步增加"结果合并与缓存更新"环节
  - 原第3-5步顺延为第5-7步
- **辅助脚本扩展**（P1）
  - 新增缓存管理命令：`--stats`, `--search`, `--clear`
  - 集成到 SKILL.md"辅助脚本"章节

### Changed
- **版本号升级**：0.2.0 → 0.3.0（新增缓存功能，次版本号更新）

### Quality
- 轻量测试通过：
  - 缓存读写功能正常
  - 关键词搜索功能正常
  - 统计和清理功能正常

---

## [0.1.1] - 2026-01-18

### Fixed
- **P0**：修复 Python 语法错误（scripts/get_skill_info.py:95）
  - 将 `choices["text", "json"]` 修正为 `choices=["text", "json"]`
- **P0**：重新定位技能描述，更符合实际能力
  - 将 YAML description 从"智能推荐"改为"搜索辅助"
  - 明确功能边界：生成搜索链接和研究清单

### Changed
- **P1**：删除过度设计的评价权重配置
  - 移除 config.yaml 中的 `scoring_weights` 节（8个未使用的权重参数）
- **P1**：统一推荐数量配置范围
  - config.yaml 中 `min_count` 从 3 改为 5
  - SKILL.md 同步更新为"目标 8 个（范围 5-10 个）"
- **P1**：修复参考文档时效性问题
  - 将"2025年12月"改为"2025年"（更通用）
- **P1**：改进官方仓库列表维护
  - 添加"最后验证"时间标记
  - 将不存在的仓库注释掉

### Added
- **P1**：输入验证和错误处理
  - search_github_skills.py：添加长度检查（200字符）和空值检查
  - 两个脚本都添加了 try-except 和友好错误消息
- **P2**：参考文档时效性标记
  - 所有 references/*.md 文件添加"最后更新"时间

### Quality
- 通过 auto-test-skill A 轮测试（v202601181359）
- 通过 auto-test-skill B 轮质量检查（B轮-v202601181410）
- 质量评分：109/115（优秀，生产就绪）

---

## [0.1.0] - 2025-12-XX

### Added
- 初始版本发布
- 核心 search_github_skills.py 和 get_skill_info.py 脚本
- GitHub、SkillsMP、Reddit 搜索平台支持
- 配置文件和参考文档

---

## 版本说明

- **主版本号**：不兼容的 API 修改
- **次版本号**：向下兼容的功能性新增
- **修订号**：向下兼容的问题修正

# 技能基本信息
skill_info:
  name: find-best-skill
  version: 0.4.1
  description: 根据用户需求智能推荐最佳 Agent Skills
  author: "Bensz Conan"
  category: 技能发现

# 搜索平台配置
platforms:
  github:
    base_url: https://github.com
    # 使用 WebSearch 工具搜索，语法示例：site:github.com "SKILL.md" {关键词}

  skillsmp:
    base_url: https://skillsmp.com
    # 使用 WebSearch 工具搜索，语法示例：site:skillsmp.com {关键词} skill

  awesome_list:
    repo: VoltAgent/awesome-claude-skills
    url: https://github.com/VoltAgent/awesome-claude-skills

# 搜索关键词模板
search_keywords:
  - "{topic} + claude skill"
  - "{topic} + agent skill"
  - "{topic} + codex skill"
  - "{topic} + claude code"

# 推荐筛选标准
recommendation_criteria:
  min_stars: 10  # 最少 Stars 数量
  max_age_months: 12  # 最大未更新月数
  require_github: true  # 必须有 GitHub 仓库
  require_skill_md: true  # 必须有 SKILL.md 文件

# 推荐数量配置
recommendation:
  default_min: 5        # 默认最少推荐数量
  default_max: 10       # 默认最多推荐数量
  target_count: 8       # 默认目标推荐数量
  absolute_min: 3       # 绝对最少数量（找不到更多时）
  absolute_max: 20      # 绝对最多数量（避免信息过载）
  user_override: true   # 允许用户指定数量覆盖默认值

# 官方仓库列表
# 最后验证时间：2026-01-18
official_repos:
  - anthropics/skills           # Anthropic 官方技能仓库（已验证）
  - openai/skills               # OpenAI Codex Skills Catalog（已验证）

# 知名社区仓库
# 最后验证时间：2026-01-18
notable_repos:
  - VoltAgent/awesome-claude-skills    # 社区精选列表（已验证）
  - vercel-labs/agent-skills          # Vercel Agent Skills（已验证，原 claude-skills 已重命名）

# 输出格式配置
output:
  include_metrics: true  # 包含指标（Stars、Forks 等）
  include_limitations: true  # 包含局限性分析

# 缓存配置
cache:
  enabled: true  # 是否启用缓存
  dir: .bensz-api/skills/find-best-skill/cache  # 缓存目录路径（相对当前工作目录）
  ttl_days: 180  # 缓存过期时间（默认半年，可配置）
  max_size: 1000  # 最大缓存技能数
  similarity_threshold: 0.3  # 关键词相似度匹配阈值（0-1）

# 缓存策略
cache_strategy:
  # 本地缓存命中时的处理方式
  on_hit:
    show_results: true  # 显示本地结果
    ask_user: true  # 询问用户是否联网扩展
    default_action: "ask"  # 默认动作: ask/online_only/local_only

  # 本地缓存未命中时的处理方式
  on_miss:
    auto_search: true  # 自动联网搜索
    save_to_cache: true  # 搜索结果自动写入缓存

  # 联网搜索后的数据处理
  after_search:
    merge_results: true  # 合并本地和联网结果
    dedup_method: "url"  # 去重方法: url/name
    update_cache: true  # 更新缓存
    priority: "online"  # 排序优先级: online/local/merged

# Find Best Skill

本 README 面向**使用者**：如何触发并正确使用 `find-best-skill` skill。

执行指令与硬性规范在 [SKILL.md](SKILL.md)；默认参数在 [config.yaml](config.yaml)。

---

## 用法

### 最推荐 - 简单需求

```
我想找一个能做 TDD 的 skill
```

### 场景化变体

#### 结合需求解构（推荐用于复杂需求）

```
帮我找最适合的数据分析 skill，要求：支持 Python、有可视化功能、社区活跃
```

#### 对比替代方案

```
现在最好的 code review skills 有哪些？帮我对比一下
```

#### 发现专业领域技能

```
找一些做科学计算或材料模拟的 skills
```

---

## 功能概述

**find-best-skill** 是一个智能技能推荐助手，帮你从 GitHub 生态的 37,000+ Agent Skills 中找到最合适的工具。

### 核心价值

- **需求解构**：自动分析你的真实需求
- **社区调研**：搜索 GitHub、SkillsMP、Reddit 等平台
- **舆情分析**：综合社区评价和 AI 评价
- **客观推荐**：提供推荐理由 + 局限性分析

### 工作原理

```
你的需求 → 需求解构 → 多平台搜索 → 舆情分析 → 排序推荐
                    ↓
         (GitHub + SkillsMP + Reddit + awesome-claude-skills)
```

### 与其他技能的区别

| 技能 | 作用 | 配合使用 |
|------|------|----------|
| **get-review-theme** | 解构需求 | find-best-skill 会自动调用它 |
| **find-best-skill** | 推荐技能 | 使用后可直接安装推荐技能 |
| **awesome-code** | 协调多技能开发 | 找到技能后用它来执行开发 |

---

## 使用示例

### 示例 1：寻找测试工具（最简单）

**你**：找一个能做 TDD 的 skill

**find-best-skill** 输出（摘要）：

```markdown
基于您的需求 "测试驱动开发（TDD）"，我为您推荐以下 skills：

## 1. test-driven-development

**GitHub**: [obra/test-driven-development](https://github.com/VoltAgent/awesome-claude-skills)

### 推荐理由

**社区评价**：
- ⭐ 1.2k+ | 🍴 150+ | 📅 2周前更新
- 被多个团队采用，社区活跃讨论

**AI 评价**：
- 强制 Red-Green-Refactor 循环，确保 TDD 严格执行
- 支持多种测试框架
- 渐进式加载设计，性能优秀

### 局限性

- 对测试框架有预设（可能不支持您使用的框架）
- 初次使用需要适应其严格的流程要求

## 2. tdd-workflow

**GitHub**: [anthropics/tdd-workflow](https://github.com/anthropics/skills)

### 推荐理由

**社区评价**：
- ⭐ 官方维护 | 📅 持续更新
- Anthropic 官方最佳实践

**AI 评价**：
- 与 Claude Code 深度集成
- 简洁的工作流设计
- 灵活的测试适配

### 局限性

- 功能相对基础，高级特性较少
- 专注于 Claude Code 生态

[... 继续推荐 3-8 个 skills]
```

---

### 示例 2：寻找复杂功能技能

**你**：找一个能做 Git commit 信息自动生成的 skill，最好支持 Conventional Commits

**find-best-skill** 会：
1. 解构需求 → 关键词：`git`、`commit`、`conventional commits`
2. 搜索平台 → GitHub、SkillsMP、awesome-claude-skills
3. 分析舆情 → Stars、更新时间、社区讨论
4. 推荐输出 → `git-commit`（多个实现，按推荐度排序）

---

### 示例 3：对比同类技能

**你**：现在最好的 debugging skills 有哪些？帮我对比一下

**find-best-skill** 输出特点：
- 并列推荐多个调试技能
- 每个技能的适用场景说明
- 帮你选择最适合你工作流的

---

## 输出格式

每个推荐技能包含：

| 部分 | 内容 |
|------|------|
| **GitHub 链接** | 项目地址（可点击） |
| **推荐理由** | 社区评价 + AI 评价 |
| **局限性** | 潜在短板、适用场景限制 |
| **排序** | 按推荐度降序（最合适在前） |

---

## 配置选项

默认配置在 [config.yaml](config.yaml)，主要参数：

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `recommendation.target_count` | 8 | 目标推荐数量 |
| `recommendation.default_min` | 5 | 默认最少推荐数量 |
| `recommendation.default_max` | 10 | 默认最多推荐数量 |
| `recommendation.absolute_min` | 3 | 绝对最少数量（找不到更多时） |
| `recommendation.absolute_max` | 20 | 绝对最多数量（避免信息过载） |
| `recommendation_criteria.min_stars` | 10 | 最少 Stars 数量 |
| `recommendation_criteria.max_age_months` | 12 | 最大未更新月数 |

如需自定义，可以在调用时说明：
- "只推荐前 3 个"
- "至少找 10 个"
- "只要最近 6 个月更新的"

---

## 备选用法（辅助脚本）

以下脚本主要用于**开发调试**，普通用户无需使用。

### 生成研究清单

```bash
# 为指定仓库生成研究检查清单
python scripts/get_skill_info.py "obra/test-driven-development,anthropics/skills"

# 输出结构化清单，包含需要收集的信息点
```

---

## 常见问题

### Q：推荐结果包含哪些平台？

A：主要从以下平台搜索：
- **GitHub**：开源项目主阵地
- **SkillsMP**：37,000+ 技能市场
- **awesome-claude-skills**：社区精选列表
- **Reddit**（/r/ClaudeCode）：真实用户讨论

### Q：如何保证推荐质量？

A：通过以下筛选标准：
- 必须有 GitHub 仓库
- 必须有有效的 SKILL.md 文件
- 优先推荐高 Stars（>100）
- 优先推荐最近更新（6个月内）
- 排除已归档仓库

### Q：推荐的数量为什么是 5-10 个？

A：这是经验值：
- **少于 3 个**：选择太少，可能错过好工具
- **多于 10 个**：信息过载，难以决策
- **5-8 个**：最佳平衡点（默认目标 8 个）

### Q：如果找不到合适的技能怎么办？

A：可能的原因：
- 需求太新，社区还没有相关技能
- 需求太偏，属于小众领域
- 关键词不够准确

建议：
- 尝试更通用的关键词
- 描述问题而非解决方案
- 考虑创建自定义技能

### Q：可以直接安装推荐的技能吗？

A：推荐报告包含 GitHub 链接，你可以：
1. 克隆仓库到 `~/.claude/skills/`
2. 使用 SkillsMP 的一键安装（如果支持）
3. 手动复制 SKILL.md 到本地

### Q：推荐结果会保存吗？

A：不会自动保存。如需保存，建议：
- 复制推荐报告到 Markdown 文件
- 保存推荐的 GitHub 链接到书签
- 使用 Claude Code 的会话历史功能

---

## 更多文档

- [SKILL.md](SKILL.md) — 完整的工作流和执行规范
- [config.yaml](config.yaml) — 可配置参数
- [references/agent-skills-research.md](references/agent-skills-research.md) — Agent Skills 生态调研
- [references/skillsmp-guide.md](references/skillsmp-guide.md) — SkillsMP 使用指南

## WHICHMODEL - 模型选择最佳实践

**最后更新**：2026-01-25

### 披露信息

- **覆盖厂商**：Anthropic（1/6 = 17%）
- **来源构成**：社区 70%, 官方 20%, 技术博客 10%
- **数据时效**：2024-10 至 2026-01
- **局限性**：未覆盖国产模型，未独立测试技能推荐准确率

---

### 场景化建议

#### 场景 1：标准技能搜索（最常见）

**触发条件**：需要寻找特定功能的 Agent Skill

| 项目 | 建议 |
|------|------|
| **推荐模型** | Claude Sonnet 4.5 |
| **推理强度** | medium |
| **预期成本** | ~$0.02-0.10/次 |

**理由**：
- 技能搜索需要需求解构、多平台搜索、舆情分析和 AI 评价等多个步骤
- Sonnet 在多步骤任务协调中表现出色，能够理解需求并综合多源信息
- [社区对比](https://medium.com/@ayaanhaider.dev/sonnet-4-5-vs-haiku-4-5-vs-opus-4-1-which-claude-model-actually-works-best-in-real-projects-7183c0dc2249) 显示 Sonnet 在复杂场景下的优势
- **技能搜索需要平衡推理能力与效率，Sonnet 的性价比最高**

**避免**：简单搜索不需要 Opus，用 Sonnet 即可

**来源**：社区对比讨论 + 官方模型选择指南

---

#### 场景 2：复杂需求分析

**触发条件**：
- 需要深度理解复杂需求并解构主题
- 需要对比多个技能的优缺点
- 需要分析社区舆情和 AI 评价

| 项目 | 建议 |
|------|------|
| **推荐模型** | Claude Sonnet 4.5 |
| **推理强度** | medium-high |
| **预期成本** | ~$0.05-0.20/次 |

**理由**：
- Sonnet 在复杂分析任务中表现优异，能够理解需求的复杂性并生成准确的推荐
- [社区反馈](https://www.reddit.com/r/ClaudeAI/comments/1por062/claude_opus_45_is_insane_and_it_ruined_other/) 显示 Sonnet 在分析任务中与 Opus 质量相当
- **复杂需求分析需要较强的推理能力，Sonnet 足够胜任**

**避免**：极少需要 Opus，除非需求极其复杂

**来源**：Reddit 社区讨论 + 90 天对比测试

---

### 对比总结

| 模型 | 最适合 | 最不适合 | 相对成本 | 相对速度 | 推荐度 |
|------|-------|---------|---------|---------|-------|
| **Sonnet 4.5** | 所有技能搜索场景（95%） | 极端复杂的需求分析 | $$$$ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| **Haiku 4.5** | 简单关键词搜索 | 复杂需求分析（理解不足） | $$ | ⭐⭐⭐⭐⭐ | ⭐⭐ |
| **Opus 4.5** | **不推荐** | 所有场景（浪费） | $$$$$ | ⭐⭐ | ⭐ |

**说明**：
- Sonnet 覆盖 95% 的技能搜索场景
- Haiku 仅用于简单关键词搜索（单一功能、无复杂分析）
- Opus 对此任务**完全不必要**，成本过高且无性能提升

---

### 通用原则

1. **默认从 Sonnet 开始**：95% 的技能搜索任务 Sonnet 足够，无需 Opus
2. **复杂度判断**：根据需求的复杂程度选择模型
   - 简单搜索（单一关键词）：Sonnet 或 Haiku
   - 标准搜索（多关键词、需要对比）：Sonnet
   - 复杂需求（需要深度解构和分析）：Sonnet（极少需要 Opus）
3. **质量优先**：技能推荐是"找到合适的工具"，不应只追求低成本而牺牲推荐质量
4. **多步骤任务需要推理**：需求解构 + 多平台搜索 + 舆情分析 + AI 评价，需要较强的推理能力
5. **Haiku 的局限性**：虽然 Haiku 速度快、成本低，但 [社区反馈](https://www.reddit.com/r/ClaudeAI/comments/1o856eb/tested_haiku_45_it-is-fast-but-cant-complete/) 显示它在完成复杂多步骤任务时可能遇到困难

---

### ⚠️ 争议点

#### Sonnet vs Haiku：技能搜索可以用 Haiku 吗？

| 观点 | 支持者 | 理由 |
|------|-------|------|
| **Sonnet 更保险** | 社区多数意见 | 技能搜索需要理解需求并综合多源信息，Haiku 可能无法胜任 |
| **Haiku 足够** | 部分开发者 | 简单关键词搜索是简单任务，Haiku 完全胜任 |

**数据支持**：
- [某用户测试](https://medium.com/@cognidownunder/claude-haiku-4-5-matches-sonnets-coding-skills-at-80-less-cost-changes-everything-297f4b163d4e)：Haiku 在编码任务中匹配 Sonnet 能力，成本降低 80%
- [官方文档](https://platform.claude.com/docs/en/about-claude/models/choosing-a-model)：Haiku 专为"高吞吐量、低延迟"场景设计

**建议**：
- **默认使用 Sonnet**：技能搜索需要理解和综合能力，Sonnet 完全胜任
- **仅在以下情况使用 Haiku**：
  - 非常简单的关键词搜索（单一功能、无复杂分析）
  - 快速查找已知的技能名称
  - Sonnet 出现理解错误时（极少见）

---

### 更新记录

- 2026-01-25：首次调研，覆盖 Anthropic
- 建议：2026-07 重新调研（6 个月后）

---

### 来源链接

**官方文档**：
- [Claude Tool Use Documentation](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview)
- [Choosing the right model](https://platform.claude.com/docs/en/about-claude/models/choosing-a-model)
- [Claude Haiku 4.5 System Card](https://www.anthropic.com/claude-haiku-4-5-system-card)

**社区讨论**：
- [Sonnet 4.5 vs Haiku 4.5 vs Opus 4.1](https://medium.com/@ayaanhaider.dev/sonnet-4-5-vs-haiku-4-5-vs-opus-4-1-which-claude-model-actually-works-best-in-real-projects-7183c0dc2249)
- [Claude Opus 4.5 is insane (Reddit)](https://www.reddit.com/r/ClaudeAI/comments/1por062/claude_opus_45_is_insane_and_it_ruined_other/)

**技术博客**：
- [Top Use Cases for Claude Haiku 4.5](https://chatlyai.app/blog/claude-haiku-4-5-use-cases)
- [Claude Haiku 4.5 matches Sonnet's coding skills at 80% less cost](https://medium.com/@cognidownunder/claude-haiku-4-5-matches-sonnets-coding-skills-at-80-less-cost-changes-everything-297f4b163d4e)

---
name: find-best-skill
description: 当用户明确要求搜索、寻找、查找或推荐某个领域的 Agent Skill 时使用。对候选 Skill 进行多来源检索与比较后给出推荐。⚠️ 不适用：只想查看已有技能列表，或没有明确搜索/推荐意图。
metadata:
  author: Bensz Conan
  keywords:
    - find-best-skill
---

# Find Best Skill

## 目标

当用户明确要求"搜索技能"、"寻找 Agent Skill"、"查找某个领域的 skill"、"推荐最佳 skill"时使用。支持多平台搜索（GitHub、SkillsMP、Reddit）和社区/AI 双维度评价，推荐数量可根据用户指令动态调整（默认 5-10 个，支持 3-20 个）。⚠️ 不适用：用户只是询问"有没有某个技能"（应直接回答）、只是想了解技能列表（应直接列举）、没有明确"搜索/寻找/查找/推荐"意图。

## 流程

### 输入

#### 使用场景

当用户需要：
- 寻找特定功能的 Agent Skill
- 了解社区中某个领域的最佳实践方案
- 对比不同技能的优劣
- 发现已有技能的替代方案

#### 依赖关系

**可选依赖**：
- **get-review-theme** skill：用于需求解构（第 1 步）
  - 如果用户未安装该 skill，可直接分析用户需求提取主题和关键词

### 执行步骤

#### 核心工作流

##### 1. 需求解构

分析用户需求，提取核心主题和关键词：

**优先使用** **get-review-theme** skill（如已安装）：
```bash
/skill get-review-theme "用户原始需求描述"
```

**如未安装**：直接分析用户需求，从用户输入中提取核心主题、关键词、具体问题。

##### 2. 缓存查询

**优先检查本地缓存**，快速匹配历史技能：

```bash
# 使用缓存管理器搜索匹配技能
python scripts/cache_manager.py --search "关键词1" "关键词2" --limit 10
```

说明：
- 默认缓存参数来自 `config.yaml:cache`（单一真相来源）
- CLI 参数（如 `--cache-dir`）会覆盖 `config.yaml`

**命中策略**：

| 情况 | 处理方式 |
|------|----------|
| **有命中** | 展示本地结果 → 询问用户"是否联网扩展？" → 用户选择 |
| **无命中** | 直接进入联网搜索（第 3 步） |

**用户交互话术**：
```markdown
基于本地缓存，我找到 {N} 个相关技能：

{展示本地结果}

💡 发现 {N} 个候选，是否联网扩展搜索以获取更多最新结果？
- 回复"是"或"联网"进行在线搜索
- 回复"否"或"直接使用"直接输出以上结果
```

##### 3. 社区调研

基于解构结果，使用 **WebSearch 类工具**或**搜索类 MCP 工具**（如 SearXNG、Tavily）进行多平台搜索。

**搜索平台**：

| 平台 | 搜索语法示例 | 搜索重点 |
|------|-------------|----------|
| **GitHub** | `site:github.com "SKILL.md" {关键词}` | 开源项目、Stars、Forks |
| **SkillsMP** | `site:skillsmp.com {关键词} skill` | 技能市场、人气排序 |
| **awesome-claude-skills** | 直接访问 `github.com/VoltAgent/awesome-claude-skills` | 社区精选 |
| **Reddit** | `site:reddit.com/r/ClaudeCode {关键词}` | 用户讨论、真实反馈 |

**搜索关键词组合**（见 `config.yaml:search_keywords`）：
- `{topic} claude skill`（如 `TDD claude skill`）
- `{topic} agent skill`
- `{topic} claude code`

**搜索示例**：

```
# GitHub 搜索 TDD 相关技能
site:github.com "SKILL.md" TDD claude

# 搜索测试驱动开发技能
"test driven development" agent skill github

# Reddit 社区讨论
site:reddit.com/r/ClaudeCode TDD skill
```

**辅助脚本**（可选）：
```bash
# 生成研究检查清单模板
python scripts/get_skill_info.py "repo1,repo2,repo3"
```

##### 4. 结果合并与缓存更新

**如果联网搜索**：将本地缓存结果与联网搜索结果合并：

| 操作 | 说明 |
|------|------|
| **去重** | 基于 skill_name 或 GitHub URL 去重 |
| **数据源标记** | 本地/联网分别标记（`source: local/online`） |
| **排序优化** | 联网结果优先（最新数据），本地结果补充 |

**缓存更新**：将联网搜索到的新技能写入缓存

```python
from scripts.cache_manager import CacheManager

manager = CacheManager()
manager.add_skill(
    skill_name="skill-name",
    meta={
        "url": "https://github.com/xxx/skill",
        "description": "技能描述",
        "stars": 1234,
        "last_updated": "2026-01-18",
        "source": "online"
    },
    keywords=["tdd", "testing"],
    tags=["official", "workflow"]
)
```

##### 5. 社区舆情分析

对每个候选 skill，收集以下信息：

**社区评价维度**：
- GitHub Stars 数量
- 最近更新时间
- Issue 响应速度
- Fork/Watch 比例
- 社区讨论热度

**质量信号**：
- 是否有官方支持（Anthropic、OpenAI）
- 是否被知名团队使用（Sentry、Vercel）
- 文档完整性
- 代码质量

##### 6. AI 评价

从 AI 视角评估每个 skill：

**技术维度**：
- 工作流设计的合理性
- YAML frontmatter 质量
- Progressive Disclosure 实现程度
- 与现有生态的兼容性

**实用性维度**：
- 使用场景覆盖度
- 配置灵活性
- 扩展性
- 维护活跃度

##### 7. 生成推荐报告

按最合适至最不合适排序，推荐 skills。

**推荐数量规则**（详细参数见 `config.yaml:recommendation`）：

1. **优先级1：用户明确指定**
   - 解析用户指令中的数量关键词（如"推荐 3 个"、"给我 15 个候选"）
   - 示例：`"找 5 个最好的 TDD skill"` → 推荐数量 = 5

2. **优先级2：使用默认范围**
   - 默认目标数量：见 `config.yaml:recommendation.target_count`
   - 可调整范围：见 `config.yaml:recommendation.default_min/default_max`

3. **边界约束**：
   - 最少：见 `config.yaml:recommendation.absolute_min`
   - 最多：见 `config.yaml:recommendation.absolute_max`

每个 skill 包含：

```markdown
## N. {Skill Name}

**GitHub**: [项目地址](https://github.com/xxx/xxx)

### 推荐理由

**社区评价**：
- ⭐ {Stars} | 🍴 {Forks} | 📅 {最后更新}
- {社区使用情况、知名团队引用等}

**AI 评价**：
- {技术优势}
- {工作流设计亮点}
- {与需求匹配度}

### 局限性

- {潜在短板}
- {适用场景限制}
- {依赖或平台要求}
```

#### 辅助脚本

##### 缓存管理

```bash
# 查看缓存统计
python scripts/cache_manager.py --stats

# 搜索缓存中的技能
python scripts/cache_manager.py --search "关键词1" "关键词2" --limit 10

# 清理特定技能缓存
python scripts/cache_manager.py --clear "skill-name"

# 清理所有缓存
python scripts/cache_manager.py --clear
```

##### 批量获取技能信息

```bash
# 生成研究检查清单模板
python scripts/get_skill_info.py "repo1,repo2,repo3"
```

#### 参考资源

- [Agent Skills 调研报告](references/agent-skills-research.md)
- [SkillsMP 搜索指南](references/skillsmp-guide.md)

#### 示例

**用户输入**：`找一个能做 TDD 的 skill`

**输出示例**：

```markdown
基于您的需求 "测试驱动开发（TDD）"，我为您推荐以下 skills：

## 1. test-driven-development

**GitHub**: [obra/test-driven-development](https://github.com/VoltAgent/awesome-claude-skills)

### 推荐理由

**社区评价**：
- ⭐ 1.2k+ | 🍴 150+ | 📅 2周前更新
- 被多个团队采用，社区活跃讨论

**AI 评价**：
- 强制 Red-Green-Refactor 循环，确保 TDD 严格执行
- 支持多种测试框架
- 渐进式加载设计，性能优秀

### 局限性

- 对测试框架有预设（可能不支持您使用的框架）
- 初次使用需要适应其严格的流程要求

## 2. tdd-workflow

**GitHub**: [anthropics/tdd-workflow](https://github.com/anthropics/skills)

### 推荐理由

**社区评价**：
- ⭐ 官方维护 | 📅 持续更新
- Anthropic 官方最佳实践

**AI 评价**：
- 与 Claude Code 深度集成
- 简洁的工作流设计
- 灵活的测试适配

### 局限性

- 功能相对基础，高级特性较少
- 专注于 Claude Code 生态

[... 继续推荐 3-8 个 skills]
```

### 输出

#### 输出规范

##### 推荐数量

**动态确定规则**：

1. **优先级 1：用户明确指定**
   - 解析用户指令中的数量关键词（如"推荐 3 个"、"给我 15 个候选"）
   - 示例：`"找 5 个最好的 TDD skill"` → 推荐数量 = 5

2. **优先级 2：使用默认范围**
   - 用户未指定时，使用 5-10 个
   - 根据候选质量和相关性灵活调整

3. **边界约束**：
   - **最少**：3 个（确实找不到更多时）
   - **最多**：20 个（避免信息过载）

**排序**：按推荐度降序排列

##### 筛选标准

**必须满足**：
- 有 GitHub 仓库地址
- 有有效的 SKILL.md 文件
- 有明确的功能描述

**优先推荐**：
- 官方维护（Anthropic、OpenAI）
- 高 Stars（>100）
- 最近更新（6个月内）
- 有完整文档

**排除条件**：
- 没有 GitHub 链接
- 仓库已归档
- 超过 1 年未更新
- 文档严重缺失

##### 数量解析示例

| 用户指令 | 解析结果 | 说明 |
|---------|---------|------|
| `"推荐 3 个 TDD skill"` | 3 个 | 明确数字 |
| `"给我 15 个候选"` | 15 个 | 超出默认范围但有效 |
| `"找一些 debug 技能"` | 5-10 个 | 未指定，使用默认 |
| `"只要最好的一个"` | 1 个 | 少于最少边界，但用户意图明确 |
| `"列出所有相关的"` | 5-10 个 | 无明确数量，使用默认 |

### 输出管理

#### BenszAPI 任务工作区


### 校验

#### 质量检查清单

**触发验证**（执行前）：
- [ ] 用户明确要求"搜索/寻找/查找/推荐"技能
- [ ] 非简单询问"有没有某个技能"（应直接回答）

**输出验证**（执行后）：
- [ ] 每个推荐都有 GitHub 链接
- [ ] 推荐理由包含社区和 AI 双重视角
- [ ] 局限性分析真实客观
- [ ] 排序逻辑清晰可解释
- [ ] 总数符合"输出规范"的约束（见上文"推荐数量规则"）

### 失败与恢复

#### 搜索、缓存与候选失败

- `get-review-theme` 未安装时直接从用户需求提取主题和关键词，不把可选依赖故障当作任务失败。
- 本地缓存无命中时进入联网搜索；联网来源不可用或部分失败时，明确标记失败来源并使用仍可验证的缓存/搜索结果，不虚构 Stars、更新时间、链接或社区评价。
- 候选缺少 GitHub 链接、有效 `SKILL.md`、明确功能描述，或命中排除条件时剔除并在数量不足时说明原因，不用低质量结果填充数量。
- 缓存写入、辅助脚本或单个平台失败时保留已收集的结果和错误信息；只有满足来源可追溯、排序和数量约束的候选才进入最终推荐报告。


## 约束

<!-- BEGIN COMMON CONSTRAINTS -->
<!-- Source-Hash: sha256:15120201e9e0c7569517261d57ecefb63ac279c26ed13876f8e95b6dc35854d3 -->
<!-- Template-ID: skill-common-constraints; Template-Version: 1; Sync-Policy: exact-block -->

### 公共硬约束

本块由 `docs/templates/skill-common-constraints.md` 统一维护；每个 `SKILL.md` 的 `## 约束` 必须逐字同步本块，不得在副本中改写公共规则。

- 任务需要落盘时，使用唯一的 `./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/` 根目录；共享材料放入 `shared/`，Skill 专属材料放入该 Skill 的 `input/`、`output/`、`log/`。
- 正式交付物、源代码和正式计划按项目约定保存，不写入任务工作区；未经授权不覆盖、删除、迁移或远程写入。
- 项目维护变更检查 BAC 可用性并记录需求、AI 产出、工具结果、文件改动和验证摘要；BAC 只做过程审计，不替代署名、责任或合规判断。
- 不记录 API Key、访问令牌、密码、Cookie、环境/凭据文件、私有 Prompt、身份信息、本地用户名、主机名或不必要的大体积原始数据。
- 文件路径必须规范化并限制在授权项目范围内；外部 URL、子进程和网络访问遵循最小权限，防止路径遍历、SSRF 和命令注入。
- Skill 版本唯一记录在自身 `config.yaml:skill_info.version`；公开 API、协议、目录或配置变更同步文档与 `CHANGELOG.md`。
- `bensz-collect-bugs` 是一个 Agent Skill；仅将 Bensz Agent Skill 或 Bensz 基础设施本身的设计缺陷交给它。先脱敏写入 `~/.bensz-skills/bugs/`，当前任务不中断，只有用户明确要求才公开上报，禁止直接修改用户已安装的 Skill 源码。

<!-- End of canonical common constraints. -->
<!-- END COMMON CONSTRAINTS -->