skill-finder

技能查找器

通过智能语义搜索、质量评估和适配度评分，为你的特定需求查找并评估 Claude 技能。

此技能的功能

Skill-finder 是一个由查询驱动的评估引擎，它可以：

• 在 GitHub 上搜索符合你特定使用场景的技能
• 获取并阅读实际的 SKILL.md 内容
• 根据 Anthropic 的最佳实践评估技能
• 评估技能与你的具体需求的适配度
• 提供可执行的质量评估和建议

这不是一个“给我看看热门技能”的工具，而是一个语义匹配器，用于为你的特定需求找到合适的技能。

适用场景

• 用户要求查找满足特定用途的技能：“帮我找一个用于制作推介演示文稿的技能”
• 用户需要帮助在相似的技能之间做出选择
• 用户想要经过质量评估的建议，而不只是按人气排名的结果
• 用户询问“[特定任务] 最适合用什么技能”

快速入门示例

# Find skills for specific use case
"Find me a skill for creating pitch decks"
"What's the best skill for automated data analysis"
"Find skills that help with git commit messages"

# NOT: "Show me popular skills" (too generic)
# NOT: "List all skills" (use skill list command instead)

核心工作流

阶段 1：理解查询

从用户查询中提取语义词：

用户：“帮我找一个用于制作推介演示文稿的技能”

提取词语：

• 主要： “推介演示文稿”、“演示文稿”
• 次要： “幻灯片”、“powerpoint”、“keynote”
• 相关： “商业”、“模板”

阶段 2：多源搜索

搜索策略：

# 1. Repository search with semantic terms
gh search repos "claude skills pitch deck OR presentation OR slides" \
  --sort stars --limit 20 --json name,stargazersCount,description,url,pushedAt,owner

# 2. Code search for SKILL.md with keywords
gh search code "pitch deck OR presentation" "filename:SKILL.md" \
  --limit 20 --json repository,path,url

# 3. Search awesome-lists separately
gh search repos "awesome-claude-skills" --sort stars --limit 5 \
  --json name,url,owner

去重： 汇总搜索结果中的所有唯一仓库。

阶段 3：获取内容

针对每个候选技能：

# 1. Find SKILL.md location
gh api repos/OWNER/REPO/git/trees/main?recursive=1 | \
  jq -r '.tree[] | select(.path | contains("SKILL.md")) | .path'

# 2. Fetch full SKILL.md content
gh api repos/OWNER/REPO/contents/PATH/TO/SKILL.md | \
  jq -r '.content' | base64 -d > temp_skill.md

# 3. Fetch repository metadata
gh api repos/OWNER/REPO --jq '{
  stars: .stargazers_count,
  updated: .pushed_at,
  description: .description
}'

**重要：**务必阅读 SKILL.md 内容。不要只使用元数据。

阶段 4：质量评估

使用 最佳实践检查清单 进行评估：

针对每个技能，评估：

1. 描述质量（2.0 分）

   • 是否具体而非含糊？
   • 是否说明了技能的功能和适用场景？
   • 是否使用第三人称？

2. 名称规范（0.5 分）

   • 是否遵循命名规则？
   • 是否具有描述性？

3. 简洁性（1.5 分）

   • 是否少于 500 行？
   • 是否没有冗余内容？

4. 渐进式披露（1.0 分）

   • 是否使用参考文件？
   • 组织是否合理？

5. 示例和工作流（1.0 分）

   • 是否包含具体示例？
   • 工作流是否清晰？

6. 自由度是否恰当（0.5 分）

   • 是否与任务复杂度相匹配？

7. 依赖项（0.5 分）

   • 是否有记录？
   • 是否已确认可用？

8. 结构（1.0 分）

   • 组织是否合理？
   • 各部分是否清晰？

9. 错误处理（0.5 分）

   • 脚本是否能处理错误？
   • 是否包含验证循环？

10. 避免反模式（1.0 分）

    • 是否没有时效性信息？
    • 术语是否一致？
    • 是否使用 Unix 路径？

11. 测试（0.5 分）

    • 是否有测试证据？

计算 quality_score（0–10）： 详细评分方法请参阅 最佳实践检查清单。

阶段 5：适配度评分

语义匹配计算：

# Pseudo-code for semantic matching
user_query_terms = ["pitch", "deck", "presentation"]
skill_content = read_skill_md(skill_path)

# Check occurrences of user terms in skill
matches = []
for term in user_query_terms:
    if term.lower() in skill_content.lower():
        matches.append(term)

semantic_match_score = len(matches) / len(user_query_terms) * 10

适配度公式：

fitness_score = (
  semantic_match * 0.4 +          # How well does it solve the problem?
  quality_score * 0.3 +            # Follows best practices?
  (stars/100) * 0.2 +              # Community validation
  freshness_multiplier * 0.1       # Recent updates
)

Where:
- semantic_match: 0-10 (keyword matching in SKILL.md content)
- quality_score: 0-10 (from evaluation checklist)
- stars: repository star count
- freshness_multiplier: 0-10 based on days since update

时效性乘数：

days_old=$(( ($(date +%s) - $(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$pushed_at" +%s)) / 86400 ))

if [ $days_old -lt 30 ]; then
  freshness_score=10
  freshness_badge="🔥"
elif [ $days_old -lt 90 ]; then
  freshness_score=7
  freshness_badge="📅"
elif [ $days_old -lt 180 ]; then
  freshness_score=5
  freshness_badge="📆"
else
  freshness_score=2
  freshness_badge="⏰"
fi

阶段 6：Awesome 列表处理

从 awesome 列表中提取技能：

# For each awesome-list found
for repo in awesome_lists; do
  # Fetch README or main content
  gh api repos/$repo/readme | jq -r '.content' | base64 -d > readme.md

  # Extract GitHub links to potential skills
  grep -oE 'https://github.com/[^/]+/[^/)]+' readme.md | sort -u

  # For each linked repo, check if it contains SKILL.md
  # If yes, evaluate same as other skills
done

在结果中单独显示 awesome 列表中的技能，以便进行比较。

阶段 7：结果排序和展示

按 fitness_score 降序排序

输出格式：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎯 Skills for: "[USER QUERY]"
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🏆 #1 skill-name ⭐ STARS FRESHNESS | FITNESS: X.X/10

   Quality Assessment:
   ✅ Description: Excellent (2.0/2.0)
   ✅ Structure: Well organized (0.9/1.0)
   ⚠️  Length: 520 lines (over recommended 500)
   ✅ Examples: Clear workflows included

   Overall Quality: 8.5/10 (Excellent)

   Why it fits your request:
   • Specifically designed for [relevant aspect]
   • Mentions [user's key terms] 3 times
   • Has [relevant feature]
   • Includes [useful capability]

   Why it's high quality:
   • Follows Anthropic best practices
   • Has comprehensive examples
   • Clear workflows and validation
   • Well-tested and maintained

   📎 https://github.com/OWNER/REPO/blob/main/PATH/SKILL.md

   [Preview Full Analysis] [Install]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🏆 #2 another-skill ⭐ STARS FRESHNESS | FITNESS: Y.Y/10

   Quality Assessment:
   ✅ Good description and examples
   ⚠️  Some best practices not followed
   ❌ No progressive disclosure

   Overall Quality: 6.2/10 (Good)

   Why it fits your request:
   • Partially addresses [need]
   • Has [some relevant feature]

   Why it's not ideal:
   • Not specifically focused on [user's goal]
   • Quality could be better
   • Missing [important feature]

   📎 https://github.com/OWNER/REPO/blob/main/SKILL.md

   [Preview] [Install]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📚 From Awesome Lists:

Found in awesome-claude-skills (BehiSecc):
  • related-skill-1 (FITNESS: 7.5/10) - Good match
  • related-skill-2 (FITNESS: 5.2/10) - Partial match

Found in awesome-claude-skills (travisvn):
  • another-option (FITNESS: 6.8/10) - Consider this

[Evaluate All] [Show Details]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💡 Recommendation: skill-name (FITNESS: 8.7/10)

   Best match for your needs. High quality, well-maintained,
   and specifically designed for [user's goal].

   Next best: another-skill (FITNESS: 7.2/10) if you need [alternative approach]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

与通用搜索的主要区别

通用／不佳的做法：

• “给我看看最受欢迎的 10 个技能”
• 仅按星标数排名
• 不评估实际内容
• 不评估与用户特定需求的适配度

查询驱动／良好的做法：

• “查找适用于[特定使用场景]的技能”
• 阅读实际的 SKILL.md 内容
• 根据最佳实践进行评估
• 评估技能与用户查询的适配度
• 解释为什么它是合适的选择

评估工作流

快速评估（每个技能约需 3-4 分钟）

1. 获取 SKILL.md（30 秒）
2. 阅读 frontmatter（30 秒）
   • 检查描述质量
   • 检查名称规范
3. 浏览正文（1-2 分钟）
   • 检查长度
   • 查找示例
   • 检查是否有引用
   • 记录反模式
4. 检查结构（30 秒）
   • 是否有引用文件？
   • 是否有脚本/实用工具？
5. 计算分数（30 秒）
   • 质量分数
   • 语义匹配度
   • 适用度分数

完整评估（针对优选候选项）

针对适用度分数排名前 3-5 的候选项，提供详细分析：

Full Analysis for: [skill-name]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Quality Breakdown
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Description Quality:      2.0/2.0 ✅
  • Specific and clear
  • Includes what and when to use
  • Written in third person

Name Convention:          0.5/0.5 ✅
  • Follows naming rules
  • Descriptive gerund form

Conciseness:              1.3/1.5 ⚠️
  • 520 lines (over 500 recommended)
  • Could be more concise

Progressive Disclosure:   1.0/1.0 ✅
  • Excellent use of reference files
  • Well-organized structure

Examples & Workflows:     1.0/1.0 ✅
  • Clear concrete examples
  • Step-by-step workflows

Degree of Freedom:        0.5/0.5 ✅
  • Appropriate for task type

Dependencies:             0.5/0.5 ✅
  • All documented
  • Verified available

Structure:                0.9/1.0 ✅
  • Well organized
  • Minor heading inconsistencies

Error Handling:           0.4/0.5 ⚠️
  • Good scripts
  • Could improve validation

Anti-Patterns:            0.9/1.0 ✅
  • Mostly clean
  • One instance of inconsistent terminology

Testing:                  0.5/0.5 ✅
  • Clear testing approach

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total Quality Score: 8.5/10 (Excellent)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🎯 Semantic Match Analysis

User Query: "pitch deck creation"
Skill Content Analysis:
  ✅ "pitch deck" mentioned 5 times
  ✅ "presentation" mentioned 12 times
  ✅ "slides" mentioned 8 times
  ✅ Has templates section
  ✅ Has business presentation examples

Semantic Match Score: 9.2/10

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Final FITNESS Score: 8.8/10
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Recommendation: Highly Recommended ⭐⭐⭐⭐⭐

参考文件

• best-practices-checklist.md - Anthropic 的最佳实践评估标准
• search-strategies.md - 高级搜索模式
• ranking-algorithm.md - 详细的评分算法
• installation-workflow.md - 安装流程

示例用法

完整的输出示例请参见 examples/sample-output.md。

错误处理

未找到结果：

No skills found for: "[user query]"

Suggestions:
• Try broader search terms
• Check if query is too specific
• Search awesome-lists directly
• Consider creating a custom skill

适用度分数较低（全部 < 5.0）：

⚠️  Found skills but none are a strong match.

Best partial matches:
1. [skill-name] (FITNESS: 4.2/10) - Missing [key feature]
2. [skill-name] (FITNESS: 3.8/10) - Different focus

Consider:
• Combine multiple skills
• Request skill from awesome-list curators
• Create custom skill for your specific need

GitHub API 速率限制：

⚠️  GitHub API rate limit reached.

Current: 0/60 requests remaining (unauthenticated)
Resets: in 42 minutes

Solution:
export GH_TOKEN="your_github_token"

This increases limit to 5000/hour.

性能优化

并行执行：

# Run searches in parallel
{
  gh search repos "claude skills $QUERY" > repos.json &
  gh search code "$QUERY" "filename:SKILL.md" > code.json &
  gh search repos "awesome-claude-skills" > awesome.json &
  wait
}

缓存：

# Cache skill evaluations for 1 hour
cache_file=".skill-eval-cache/$repo_owner-$repo_name.json"
if [ -f "$cache_file" ] && [ $(($(date +%s) - $(stat -f %m "$cache_file"))) -lt 3600 ]; then
  cat "$cache_file"
else
  evaluate_skill | tee "$cache_file"
fi

质量等级

根据适用度分数划分：

• 9.0-10.0： 完美匹配 - 强烈推荐 ⭐⭐⭐⭐⭐
• 7.0-8.9： 极佳匹配 - 推荐 ⭐⭐⭐⭐
• 5.0-6.9： 良好匹配 - 可考虑 ⭐⭐⭐
• 3.0-4.9： 部分匹配 - 请仔细评估 ⭐⭐
• 0.0-2.9： 匹配度低 - 不推荐 ⭐

重要说明

这不是：

• 一个“展示热门技能”的工具
• 根据星标数进行通用排名
• 所有技能的列表

这是：

• 一个由查询驱动的语义匹配器
• 一个依据 Anthropic 最佳实践进行质量评估的工具
• 一个针对你特定需求的适用度评分器
• 一个推荐引擎

始终要：

• 阅读实际的 SKILL.md 内容（不要只看元数据）
• 对照最佳实践清单进行评估
• 根据用户的具体查询评估适用度
• 说明技能适合或不适合的原因
• 展示质量评估，而不只是星标

---

请记住： 目标是为用户的特定需求找到合适的技能，而不只是展示热门技能。