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：品質評価

best-practices-checklist.md を使って評価します。

各スキルについて、以下を評価します。

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）を計算します。 詳しい採点方法については、best-practices-checklist.md を参照してください。

フェーズ 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. フロントマターを読む（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 の内容を読む（メタデータだけに頼らない）
• ベストプラクティスのチェックリストに照らして評価する
• ユーザー固有のクエリへの適合度を採点する
• スキルが適合する、または適合しない理由を説明する
• スターだけでなく、品質評価を示す

---

覚えておいてください： 目標は人気のあるスキルを表示することではなく、ユーザーの具体的なニーズに合った適切なスキルを見つけることです。