Initial commit

2025-11-30 09:01:22 +08:00
commit 4cbc82fbd4
9 changed files with 2670 additions and 0 deletions
--- a/skills/skill/references/best-practices-checklist.md
+++ b/skills/skill/references/best-practices-checklist.md
@@ -0,0 +1,292 @@
+# Anthropic Best Practices Checklist
+
+Evaluation criteria for assessing Claude Skill quality based on official Anthropic guidelines.
+
+## Purpose
+
+Use this checklist to evaluate skills found on GitHub. Each criterion contributes to the overall quality score (0-10).
+
+## Evaluation Criteria
+
+### 1. Description Quality (Weight: 2.0)
+
+**What to check:**
+- [ ] Description is specific, not vague
+- [ ] Includes what the skill does
+- [ ] Includes when to use it (trigger conditions)
+- [ ] Contains key terms users would mention
+- [ ] Written in third person
+- [ ] Under 1024 characters
+- [ ] No XML tags
+
+**Scoring:**
+- 2.0: All criteria met, very clear and specific
+- 1.5: Most criteria met, good clarity
+- 1.0: Basic description, somewhat vague
+- 0.5: Very vague or generic
+- 0.0: Missing or completely unclear
+
+**Examples:**
+
+**Good (2.0):**
+```yaml
+description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when working with Excel files, spreadsheets, tabular data, or .xlsx files.
+```
+
+**Bad (0.5):**
+```yaml
+description: Helps with documents
+```
+
+### 2. Name Convention (Weight: 0.5)
+
+**What to check:**
+- [ ] Uses lowercase letters, numbers, hyphens only
+- [ ] Under 64 characters
+- [ ] Follows naming pattern (gerund form preferred)
+- [ ] Descriptive, not vague
+- [ ] No reserved words ("anthropic", "claude")
+
+**Scoring:**
+- 0.5: Follows all conventions
+- 0.25: Minor issues (e.g., not gerund but still clear)
+- 0.0: Violates conventions or very vague
+
+**Good:** `processing-pdfs`, `analyzing-spreadsheets`
+**Bad:** `helper`, `utils`, `claude-tool`
+
+### 3. Conciseness (Weight: 1.5)
+
+**What to check:**
+- [ ] SKILL.md body under 500 lines
+- [ ] No unnecessary explanations
+- [ ] Assumes Claude's intelligence
+- [ ] Gets to the point quickly
+- [ ] Additional content in separate files if needed
+
+**Scoring:**
+- 1.5: Very concise, well-edited, <300 lines
+- 1.0: Reasonable length, <500 lines
+- 0.5: Long but not excessive, 500-800 lines
+- 0.0: Very verbose, >800 lines
+
+### 4. Progressive Disclosure (Weight: 1.0)
+
+**What to check:**
+- [ ] SKILL.md serves as overview/table of contents
+- [ ] Additional details in separate files
+- [ ] Clear references to other files
+- [ ] Files organized by domain/feature
+- [ ] No deeply nested references (max 1 level deep)
+
+**Scoring:**
+- 1.0: Excellent use of progressive disclosure
+- 0.75: Good organization with some references
+- 0.5: Some separation, could be better
+- 0.25: All content in SKILL.md, no references
+- 0.0: Poorly organized or deeply nested
+
+### 5. Examples and Workflows (Weight: 1.0)
+
+**What to check:**
+- [ ] Has concrete examples (not abstract)
+- [ ] Includes code snippets
+- [ ] Shows input/output pairs
+- [ ] Has clear workflows for complex tasks
+- [ ] Examples use real patterns, not placeholders
+
+**Scoring:**
+- 1.0: Excellent examples and clear workflows
+- 0.75: Good examples, some workflows
+- 0.5: Basic examples, no workflows
+- 0.25: Few or abstract examples
+- 0.0: No examples
+
+### 6. Appropriate Degree of Freedom (Weight: 0.5)
+
+**What to check:**
+- [ ] Instructions match task fragility
+- [ ] High freedom for flexible tasks (text instructions)
+- [ ] Low freedom for fragile tasks (specific scripts)
+- [ ] Clear when to use exact commands vs adapt
+
+**Scoring:**
+- 0.5: Perfect match of freedom to task type
+- 0.25: Reasonable but could be better
+- 0.0: Inappropriate level (too rigid or too loose)
+
+### 7. Dependencies Documentation (Weight: 0.5)
+
+**What to check:**
+- [ ] Required packages listed
+- [ ] Installation instructions provided
+- [ ] Dependencies verified as available
+- [ ] No assumption of pre-installed packages
+
+**Scoring:**
+- 0.5: All dependencies documented and verified
+- 0.25: Dependencies mentioned but not fully documented
+- 0.0: Dependencies assumed or not mentioned
+
+### 8. Structure and Organization (Weight: 1.0)
+
+**What to check:**
+- [ ] Clear section headings
+- [ ] Logical flow of information
+- [ ] Table of contents for long files
+- [ ] Consistent formatting
+- [ ] Unix-style paths (forward slashes)
+
+**Scoring:**
+- 1.0: Excellently organized
+- 0.75: Well organized with minor issues
+- 0.5: Basic organization
+- 0.25: Poor organization
+- 0.0: No clear structure
+
+### 9. Error Handling (Weight: 0.5)
+
+**What to check (for skills with scripts):**
+- [ ] Scripts handle errors explicitly
+- [ ] Clear error messages
+- [ ] Fallback strategies provided
+- [ ] Validation loops for critical operations
+- [ ] No "voodoo constants"
+
+**Scoring:**
+- 0.5: Excellent error handling
+- 0.25: Basic error handling
+- 0.0: No error handling or punts to Claude
+
+### 10. Avoids Anti-Patterns (Weight: 1.0)
+
+**What to avoid:**
+- [ ] Time-sensitive information
+- [ ] Inconsistent terminology
+- [ ] Windows-style paths
+- [ ] Offering too many options without guidance
+- [ ] Deeply nested references
+- [ ] Vague or generic content
+
+**Scoring:**
+- 1.0: No anti-patterns
+- 0.75: 1-2 minor anti-patterns
+- 0.5: Multiple anti-patterns
+- 0.0: Severe anti-patterns
+
+### 11. Testing and Validation (Weight: 0.5)
+
+**What to check:**
+- [ ] Evidence of testing mentioned
+- [ ] Evaluation examples provided
+- [ ] Clear success criteria
+- [ ] Feedback loops for quality
+
+**Scoring:**
+- 0.5: Clear testing approach
+- 0.25: Some testing mentioned
+- 0.0: No testing mentioned
+
+## Scoring System
+
+**Total possible: 10.0 points**
+
+Calculate weighted score:
+```
+quality_score = (
+  description_score * 2.0 +
+  name_score * 0.5 +
+  conciseness_score * 1.5 +
+  progressive_disclosure_score * 1.0 +
+  examples_score * 1.0 +
+  freedom_score * 0.5 +
+  dependencies_score * 0.5 +
+  structure_score * 1.0 +
+  error_handling_score * 0.5 +
+  anti_patterns_score * 1.0 +
+  testing_score * 0.5
+)
+```
+
+## Quality Tiers
+
+**Excellent (8.0-10.0):**
+- Follows all best practices
+- Clearly professional
+- Ready for production use
+- **Recommendation:** Strongly recommended
+
+**Good (6.0-7.9):**
+- Follows most best practices
+- Minor improvements needed
+- Usable but not perfect
+- **Recommendation:** Recommended with minor notes
+
+**Fair (4.0-5.9):**
+- Follows some best practices
+- Several improvements needed
+- May work but needs review
+- **Recommendation:** Consider with caution
+
+**Poor (0.0-3.9):**
+- Violates many best practices
+- Significant issues
+- High risk of problems
+- **Recommendation:** Not recommended
+
+## Quick Evaluation Process
+
+For rapid assessment during search:
+
+1. **Read SKILL.md frontmatter** (30 sec)
+   - Check description quality (most important)
+   - Check name convention
+
+2. **Scan SKILL.md body** (1-2 min)
+   - Check length (<500 lines?)
+   - Look for examples
+   - Check for references to other files
+   - Note any obvious anti-patterns
+
+3. **Check file structure** (30 sec)
+   - Look for reference files
+   - Check for scripts/utilities
+   - Verify organization
+
+4. **Calculate quick score** (30 sec)
+   - Focus on weighted criteria
+   - Estimate tier (Excellent/Good/Fair/Poor)
+
+**Total time per skill: ~3-4 minutes**
+
+## Automation Tips
+
+When evaluating multiple skills:
+
+```bash
+# Check SKILL.md length
+wc -l SKILL.md
+
+# Count reference files
+find . -name "*.md" -not -name "SKILL.md" | wc -l
+
+# Check for common anti-patterns
+grep -i "claude can help\|I can help\|you can use" SKILL.md
+
+# Verify Unix paths
+grep -E '\\\|\\\\' SKILL.md
+
+# Check description length
+head -10 SKILL.md | grep "description:" | wc -c
+```
+
+## Reference
+
+Based on official Anthropic documentation:
+- [Agent Skills Overview](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills/overview)
+- [Best Practices Guide](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills/best-practices)
+- [Claude Code Skills](https://docs.anthropic.com/en/docs/claude-code/skills)
+
+---
+
+**Usage:** Use this checklist when evaluating skills found through skill-finder to provide quality scores and recommendations to users.
--- a/skills/skill/references/installation-workflow.md
+++ b/skills/skill/references/installation-workflow.md
@@ -0,0 +1,547 @@
+# Installation Workflow for Claude Skills
+
+Complete guide to previewing, downloading, and installing Claude skills from GitHub.
+
+## Installation Process Overview
+
+1. **Preview** - Show skill details and requirements
+2. **Confirm** - Get user approval
+3. **Download** - Fetch skill files from GitHub
+4. **Install** - Place in correct directory structure
+5. **Verify** - Confirm installation success
+6. **Setup** - Run any required setup steps
+
+## Step 1: Preview Skill
+
+### Fetch SKILL.md Content
+
+```bash
+# Get direct link to SKILL.md
+skill_url="https://github.com/OWNER/REPO/blob/main/PATH/SKILL.md"
+skill_path="PATH/SKILL.md"
+
+# Fetch content (first 50 lines for preview)
+gh api repos/OWNER/REPO/contents/$skill_path | \
+  jq -r '.content' | base64 -d | head -50
+```
+
+### Extract Key Information
+
+```bash
+# Parse SKILL.md for important details
+skill_content=$(gh api repos/OWNER/REPO/contents/$skill_path | jq -r '.content' | base64 -d)
+
+# Extract name (first # heading)
+skill_name=$(echo "$skill_content" | grep -m1 '^# ' | sed 's/^# //')
+
+# Extract description (first paragraph after title)
+description=$(echo "$skill_content" | sed -n '/^# /,/^$/p' | grep -v '^#' | head -1)
+
+# Extract dependencies
+dependencies=$(echo "$skill_content" | grep -A10 -i "dependencies\|requirements\|prerequisites" | head -10)
+
+# Extract usage examples
+examples=$(echo "$skill_content" | grep -A10 -i "usage\|example\|quick start" | head -15)
+```
+
+### Display Preview
+
+```bash
+cat <<EOF
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📦 Skill Preview: $skill_name
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📝 Description:
+$description
+
+⭐ Repository: $repo_full_name
+🌟 Stars: $stars
+🔄 Last Updated: $days_ago days ago
+
+📋 Dependencies:
+$dependencies
+
+💡 Usage Example:
+$examples
+
+📎 Full Documentation:
+$skill_url
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+EOF
+```
+
+## Step 2: Confirm Installation
+
+### Check Existing Installation
+
+```bash
+# Determine skill directory name
+skill_dir_name=$(echo "$skill_name" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
+skill_dir=".claude/skills/$skill_dir_name"
+
+# Check if already installed
+if [ -d "$skill_dir" ]; then
+  echo "⚠️  Skill '$skill_name' is already installed at: $skill_dir"
+  echo ""
+  echo "Options:"
+  echo "  [U] Update (overwrite existing)"
+  echo "  [K] Keep existing (cancel)"
+  echo "  [B] Backup and install new"
+  echo ""
+  read -p "Choose option [U/K/B]: " choice
+
+  case $choice in
+    [Uu])
+      echo "Overwriting existing installation..."
+      ;;
+    [Kk])
+      echo "Keeping existing installation. Cancelled."
+      exit 0
+      ;;
+    [Bb])
+      backup_dir="${skill_dir}.backup.$(date +%s)"
+      mv "$skill_dir" "$backup_dir"
+      echo "✅ Backed up to: $backup_dir"
+      ;;
+    *)
+      echo "Invalid option. Cancelled."
+      exit 1
+      ;;
+  esac
+fi
+```
+
+### Get User Confirmation
+
+```bash
+echo ""
+echo "Install '$skill_name' to $skill_dir?"
+echo ""
+read -p "Continue? [y/N]: " confirm
+
+if [[ ! "$confirm" =~ ^[Yy] ]]; then
+  echo "Installation cancelled."
+  exit 0
+fi
+```
+
+## Step 3: Download Skill Files
+
+### Determine Skill Structure
+
+Skills can have different structures:
+
+1. **Simple** - Single SKILL.md file
+2. **Standard** - SKILL.md + reference files
+3. **Plugin** - Nested in `skills/` subdirectory
+4. **Complex** - Multiple files, scripts, dependencies
+
+```bash
+# Detect structure type
+structure_type=$(detect_skill_structure "$repo" "$skill_path")
+
+case $structure_type in
+  "simple")
+    download_simple_skill "$repo" "$skill_path" "$skill_dir"
+    ;;
+  "standard")
+    download_standard_skill "$repo" "$skill_path" "$skill_dir"
+    ;;
+  "plugin")
+    download_plugin_skill "$repo" "$skill_path" "$skill_dir"
+    ;;
+  "complex")
+    download_complex_skill "$repo" "$skill_path" "$skill_dir"
+    ;;
+esac
+```
+
+### Download Simple Skill (SKILL.md only)
+
+```bash
+download_simple_skill() {
+  local repo=$1
+  local skill_path=$2
+  local dest_dir=$3
+
+  echo "📥 Downloading simple skill..."
+
+  # Create destination directory
+  mkdir -p "$dest_dir"
+
+  # Download SKILL.md
+  gh api "repos/$repo/contents/$skill_path" | \
+    jq -r '.content' | base64 -d > "$dest_dir/SKILL.md"
+
+  if [ -f "$dest_dir/SKILL.md" ]; then
+    echo "✅ Downloaded SKILL.md"
+  else
+    echo "❌ Failed to download SKILL.md"
+    return 1
+  fi
+}
+```
+
+### Download Standard Skill (with references)
+
+```bash
+download_standard_skill() {
+  local repo=$1
+  local skill_path=$2
+  local dest_dir=$3
+
+  echo "📥 Downloading standard skill..."
+
+  # Get skill directory path from SKILL.md path
+  skill_dir_path=$(dirname "$skill_path")
+
+  # Get all files in skill directory
+  gh api "repos/$repo/contents/$skill_dir_path?recursive=1" | \
+    jq -r '.tree[] | select(.type == "blob") | .path' | \
+    while read file_path; do
+      # Calculate relative path
+      rel_path=${file_path#$skill_dir_path/}
+      dest_file="$dest_dir/$rel_path"
+
+      # Create subdirectories
+      mkdir -p "$(dirname "$dest_file")"
+
+      # Download file
+      gh api "repos/$repo/contents/$file_path" | \
+        jq -r '.content' | base64 -d > "$dest_file"
+
+      echo "  ✓ $rel_path"
+    done
+
+  echo "✅ Downloaded all skill files"
+}
+```
+
+### Download Plugin Skill (nested structure)
+
+```bash
+download_plugin_skill() {
+  local repo=$1
+  local skill_path=$2
+  local dest_dir=$3
+
+  echo "📥 Downloading plugin skill..."
+  echo "   (This may take a moment...)"
+
+  # Clone repository to temporary location
+  temp_dir=$(mktemp -d)
+  gh repo clone "$repo" "$temp_dir" -- --depth 1 --quiet
+
+  # Extract skill directory from SKILL.md path
+  # Example: skills/playwright-skill/SKILL.md -> skills/playwright-skill
+  skill_subdir=$(dirname "$skill_path")
+
+  # Copy skill directory to destination
+  if [ -d "$temp_dir/$skill_subdir" ]; then
+    cp -r "$temp_dir/$skill_subdir/"* "$dest_dir/"
+    echo "✅ Copied skill from $skill_subdir"
+  else
+    echo "❌ Skill directory not found: $skill_subdir"
+    rm -rf "$temp_dir"
+    return 1
+  fi
+
+  # Cleanup
+  rm -rf "$temp_dir"
+}
+```
+
+### Download Complex Skill (with setup)
+
+```bash
+download_complex_skill() {
+  local repo=$1
+  local skill_path=$2
+  local dest_dir=$3
+
+  echo "📥 Downloading complex skill..."
+
+  # Use plugin download method
+  download_plugin_skill "$repo" "$skill_path" "$dest_dir"
+
+  # Check for dependencies
+  if [ -f "$dest_dir/package.json" ]; then
+    echo ""
+    echo "📦 This skill has npm dependencies."
+    echo "   Run: cd $dest_dir && npm install"
+  fi
+
+  if [ -f "$dest_dir/requirements.txt" ]; then
+    echo ""
+    echo "🐍 This skill has Python dependencies."
+    echo "   Run: cd $dest_dir && pip install -r requirements.txt"
+  fi
+
+  if [ -f "$dest_dir/setup.sh" ]; then
+    echo ""
+    echo "🔧 This skill has a setup script."
+    read -p "   Run setup.sh now? [y/N]: " run_setup
+    if [[ "$run_setup" =~ ^[Yy] ]]; then
+      (cd "$dest_dir" && bash setup.sh)
+    fi
+  fi
+}
+```
+
+## Step 4: Verify Installation
+
+### Check Required Files
+
+```bash
+verify_installation() {
+  local skill_dir=$1
+  local errors=0
+
+  echo ""
+  echo "🔍 Verifying installation..."
+
+  # Check SKILL.md exists
+  if [ ! -f "$skill_dir/SKILL.md" ]; then
+    echo "  ❌ Missing SKILL.md"
+    ((errors++))
+  else
+    echo "  ✅ SKILL.md present"
+  fi
+
+  # Check file permissions
+  if [ ! -r "$skill_dir/SKILL.md" ]; then
+    echo "  ❌ SKILL.md not readable"
+    ((errors++))
+  else
+    echo "  ✅ File permissions OK"
+  fi
+
+  # Check for reference files (optional but good)
+  if [ -d "$skill_dir/references" ]; then
+    ref_count=$(find "$skill_dir/references" -type f | wc -l)
+    echo "  ✅ Found $ref_count reference files"
+  fi
+
+  # Check for examples (optional)
+  if [ -d "$skill_dir/examples" ]; then
+    example_count=$(find "$skill_dir/examples" -type f | wc -l)
+    echo "  ✅ Found $example_count example files"
+  fi
+
+  return $errors
+}
+```
+
+### Validate SKILL.md Content
+
+```bash
+validate_skill_content() {
+  local skill_file=$1
+
+  # Check for required sections
+  local has_title=$(grep -q '^# ' "$skill_file" && echo "yes" || echo "no")
+  local has_description=$(grep -qi 'description\|what.*does' "$skill_file" && echo "yes" || echo "no")
+  local has_usage=$(grep -qi 'usage\|example\|how.*use' "$skill_file" && echo "yes" || echo "no")
+
+  if [ "$has_title" = "yes" ] && [ "$has_description" = "yes" ]; then
+    echo "  ✅ SKILL.md structure valid"
+    return 0
+  else
+    echo "  ⚠️  SKILL.md may be incomplete (missing title or description)"
+    return 1
+  fi
+}
+```
+
+## Step 5: Post-Installation
+
+### Run Setup Scripts
+
+```bash
+# Check for and run setup
+if [ -f "$skill_dir/setup.sh" ]; then
+  echo ""
+  echo "🔧 Running setup script..."
+  (cd "$skill_dir" && bash setup.sh)
+
+  if [ $? -eq 0 ]; then
+    echo "✅ Setup completed successfully"
+  else
+    echo "⚠️  Setup script had warnings (check above)"
+  fi
+fi
+```
+
+### Install Dependencies
+
+```bash
+# npm dependencies
+if [ -f "$skill_dir/package.json" ]; then
+  echo ""
+  echo "📦 Installing npm dependencies..."
+  (cd "$skill_dir" && npm install --silent)
+  echo "✅ npm dependencies installed"
+fi
+
+# Python dependencies
+if [ -f "$skill_dir/requirements.txt" ]; then
+  echo ""
+  echo "🐍 Installing Python dependencies..."
+  pip install -q -r "$skill_dir/requirements.txt"
+  echo "✅ Python dependencies installed"
+fi
+```
+
+### Create Usage Instructions
+
+```bash
+cat <<EOF
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ Installation Complete!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📁 Installed to: $skill_dir
+
+🚀 Usage:
+   Invoke the skill by typing: /$skill_dir_name
+   Or let Claude auto-invoke when relevant
+
+📖 Documentation:
+   Read: $skill_dir/SKILL.md
+   Examples: $skill_dir/examples/ (if available)
+
+🔄 Update:
+   Re-run installation to update to latest version
+
+❌ Uninstall:
+   rm -rf $skill_dir
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+EOF
+```
+
+## Complete Installation Script
+
+```bash
+#!/bin/bash
+
+install_skill() {
+  local repo=$1
+  local skill_path=$2
+  local skill_name=$3
+
+  # 1. Determine destination
+  skill_dir_name=$(echo "$skill_name" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
+  skill_dir=".claude/skills/$skill_dir_name"
+
+  # 2. Preview
+  echo "Fetching skill preview..."
+  skill_content=$(gh api "repos/$repo/contents/$skill_path" | jq -r '.content' | base64 -d)
+  description=$(echo "$skill_content" | sed -n '/^# /,/^$/p' | grep -v '^#' | head -1)
+
+  echo ""
+  echo "📦 $skill_name"
+  echo "📝 $description"
+  echo "📁 Will install to: $skill_dir"
+  echo ""
+
+  # 3. Confirm
+  read -p "Install this skill? [y/N]: " confirm
+  [[ ! "$confirm" =~ ^[Yy] ]] && { echo "Cancelled."; return 1; }
+
+  # 4. Check existing
+  if [ -d "$skill_dir" ]; then
+    read -p "Skill exists. Overwrite? [y/N]: " overwrite
+    [[ ! "$overwrite" =~ ^[Yy] ]] && { echo "Cancelled."; return 1; }
+    rm -rf "$skill_dir"
+  fi
+
+  # 5. Download
+  mkdir -p "$skill_dir"
+
+  # Detect if plugin format or simple
+  if [[ "$skill_path" == *"/skills/"* ]]; then
+    # Plugin format - clone and extract
+    temp_dir=$(mktemp -d)
+    gh repo clone "$repo" "$temp_dir" -- --depth 1 --quiet
+    skill_subdir=$(dirname "$skill_path")
+    cp -r "$temp_dir/$skill_subdir/"* "$skill_dir/"
+    rm -rf "$temp_dir"
+  else
+    # Simple format - direct download
+    gh api "repos/$repo/contents/$skill_path" | \
+      jq -r '.content' | base64 -d > "$skill_dir/SKILL.md"
+  fi
+
+  # 6. Verify
+  if [ -f "$skill_dir/SKILL.md" ]; then
+    echo "✅ Installation successful!"
+    echo "📁 Location: $skill_dir"
+    echo "🚀 Use: /$skill_dir_name"
+  else
+    echo "❌ Installation failed"
+    return 1
+  fi
+}
+
+# Usage:
+# install_skill "lackeyjb/playwright-skill" "skills/playwright-skill/SKILL.md" "playwright-skill"
+```
+
+## Error Handling
+
+### Common Issues
+
+**Issue: Repository not found**
+```bash
+if ! gh api "repos/$repo" &>/dev/null; then
+  echo "❌ Repository not found or not accessible: $repo"
+  echo "   Check if the repository exists and is public"
+  exit 1
+fi
+```
+
+**Issue: SKILL.md not found**
+```bash
+if ! gh api "repos/$repo/contents/$skill_path" &>/dev/null; then
+  echo "❌ SKILL.md not found at: $skill_path"
+  echo "   Searching for SKILL.md in repository..."
+
+  # Try to find it
+  found_paths=$(gh api "repos/$repo/git/trees/main?recursive=1" | \
+    jq -r '.tree[] | select(.path | contains("SKILL.md")) | .path')
+
+  if [ -n "$found_paths" ]; then
+    echo "   Found SKILL.md at:"
+    echo "$found_paths" | sed 's/^/     /'
+  else
+    echo "   No SKILL.md found in repository"
+  fi
+  exit 1
+fi
+```
+
+**Issue: Permission denied**
+```bash
+if [ ! -w ".claude/skills" ]; then
+  echo "❌ Cannot write to .claude/skills directory"
+  echo "   Check permissions: ls -la .claude/skills"
+  exit 1
+fi
+```
+
+**Issue: Network/API error**
+```bash
+if ! ping -c 1 api.github.com &>/dev/null; then
+  echo "❌ Cannot reach GitHub API"
+  echo "   Check your internet connection"
+  exit 1
+fi
+```
+
+---
+
+**Summary:** The installation workflow ensures safe, verified installation of Claude skills with proper error handling, user confirmation, and post-installation setup.
--- a/skills/skill/references/ranking-algorithm.md
+++ b/skills/skill/references/ranking-algorithm.md
@@ -0,0 +1,359 @@
+# Ranking Algorithm for Claude Skills
+
+Comprehensive scoring system to rank skills by popularity, freshness, and quality.
+
+## Core Ranking Formula
+
+```
+final_score = (base_stars * freshness_multiplier * quality_bonus)
+```
+
+## Component 1: Base Stars
+
+Direct indicator of community validation and popularity.
+
+```bash
+base_stars = repository.stargazers_count
+
+# Minimum threshold: 10 stars (filter out experiments)
+if [ $base_stars -lt 10 ]; then
+  skip_result=true
+fi
+```
+
+## Component 2: Freshness Multiplier
+
+Recent updates indicate active maintenance and modern practices.
+
+### Calculate Days Since Last Update
+
+```bash
+# Get pushed_at timestamp from repository
+pushed_at="2025-10-28T12:00:00Z"
+
+# Calculate days old (macOS)
+days_old=$(( ($(date +%s) - $(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$pushed_at" +%s)) / 86400 ))
+
+# Calculate days old (Linux)
+days_old=$(( ($(date +%s) - $(date -d "$pushed_at" +%s)) / 86400 ))
+```
+
+### Apply Freshness Multiplier
+
+```bash
+if [ $days_old -lt 30 ]; then
+  freshness_multiplier=1.5
+  freshness_badge="🔥"
+  freshness_label="Hot"
+elif [ $days_old -lt 90 ]; then
+  freshness_multiplier=1.2
+  freshness_badge="📅"
+  freshness_label="Recent"
+elif [ $days_old -lt 180 ]; then
+  freshness_multiplier=1.0
+  freshness_badge="📆"
+  freshness_label="Active"
+else
+  freshness_multiplier=0.5
+  freshness_badge="⏰"
+  freshness_label="Older"
+fi
+```
+
+### Freshness Tiers
+
+| Age Range | Multiplier | Badge | Label | Reasoning |
+|-----------|------------|-------|-------|-----------|
+| < 30 days | 1.5x | 🔥 | Hot | Very active, likely works with latest Claude |
+| 30-90 days | 1.2x | 📅 | Recent | Active maintenance |
+| 90-180 days | 1.0x | 📆 | Active | Stable, still maintained |
+| > 180 days | 0.5x | ⏰ | Older | May be outdated or abandoned |
+
+## Component 3: Quality Bonus (Optional)
+
+Additional signals of skill quality beyond stars and freshness.
+
+### Quality Signals
+
+```bash
+quality_bonus=1.0  # Start at neutral
+
+# Has comprehensive description
+if [ ${#description} -gt 100 ]; then
+  quality_bonus=$(echo "$quality_bonus + 0.1" | bc)
+fi
+
+# Has reference files
+reference_count=$(gh api "repos/$repo/contents" | jq '[.[] | select(.name | test("references|docs|examples"))] | length')
+if [ $reference_count -gt 0 ]; then
+  quality_bonus=$(echo "$quality_bonus + 0.1" | bc)
+fi
+
+# Has dependencies documentation
+if gh api "repos/$repo/contents" | jq -e '.[] | select(.name == "package.json")' > /dev/null; then
+  quality_bonus=$(echo "$quality_bonus + 0.05" | bc)
+fi
+
+# Active issues/PRs indicate engagement
+open_issues=$(gh api "repos/$repo" | jq '.open_issues_count')
+if [ $open_issues -gt 0 ] && [ $open_issues -lt 20 ]; then
+  quality_bonus=$(echo "$quality_bonus + 0.05" | bc)
+fi
+
+# Has recent commits (beyond just pushed_at)
+recent_commits=$(gh api "repos/$repo/commits?per_page=10" | jq 'length')
+if [ $recent_commits -ge 5 ]; then
+  quality_bonus=$(echo "$quality_bonus + 0.1" | bc)
+fi
+
+# Cap quality bonus at 1.5x
+if (( $(echo "$quality_bonus > 1.5" | bc -l) )); then
+  quality_bonus=1.5
+fi
+```
+
+### Quality Tier Examples
+
+| Quality Bonus | Characteristics |
+|---------------|-----------------|
+| 1.0x (baseline) | Basic SKILL.md only |
+| 1.1x | + Good description |
+| 1.2x | + Reference files |
+| 1.3x | + Dependencies documented |
+| 1.4x | + Active community (issues/PRs) |
+| 1.5x (max) | All of the above |
+
+## Complete Scoring Implementation
+
+### Bash Implementation
+
+```bash
+#!/bin/bash
+
+calculate_score() {
+  local repo=$1
+  local stars=$2
+  local pushed_at=$3
+
+  # Calculate days since last update
+  days_old=$(( ($(date +%s) - $(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$pushed_at" +%s)) / 86400 ))
+
+  # Freshness multiplier
+  if [ $days_old -lt 30 ]; then
+    freshness=1.5
+    badge="🔥"
+  elif [ $days_old -lt 90 ]; then
+    freshness=1.2
+    badge="📅"
+  elif [ $days_old -lt 180 ]; then
+    freshness=1.0
+    badge="📆"
+  else
+    freshness=0.5
+    badge="⏰"
+  fi
+
+  # Calculate final score
+  score=$(echo "$stars * $freshness" | bc)
+
+  echo "$score|$badge|$days_old"
+}
+
+# Example usage
+result=$(calculate_score "lackeyjb/playwright-skill" 612 "2025-10-28T12:00:00Z")
+score=$(echo "$result" | cut -d'|' -f1)
+badge=$(echo "$result" | cut -d'|' -f2)
+days=$(echo "$result" | cut -d'|' -f3)
+
+echo "Score: $score, Badge: $badge, Days: $days"
+# Output: Score: 918.0, Badge: 🔥, Days: 2
+```
+
+### JQ Implementation (More Portable)
+
+```bash
+gh search repos "claude skills" --json name,stargazersCount,pushedAt --limit 20 | \
+  jq -r --arg now "$(date -u +%s)" '.[] |
+    . as $repo |
+    ($repo.pushedAt | fromdateiso8601) as $pushed |
+    (($now | tonumber) - $pushed) / 86400 | floor as $days |
+    (if $days < 30 then 1.5 elif $days < 90 then 1.2 elif $days < 180 then 1.0 else 0.5 end) as $multiplier |
+    (if $days < 30 then "🔥" elif $days < 90 then "📅" elif $days < 180 then "📆" else "⏰" end) as $badge |
+    ($repo.stargazersCount * $multiplier) as $score |
+    "\($score)|\($repo.name)|\($repo.stargazersCount)|\($badge)|\($days)"
+  ' | sort -t'|' -k1 -nr | head -10
+```
+
+## Ranking Examples
+
+### Real-World Scores
+
+| Skill | Stars | Days Old | Freshness | Multiplier | Final Score | Rank |
+|-------|-------|----------|-----------|------------|-------------|------|
+| playwright-skill | 612 | 2 | 🔥 | 1.5x | **918** | #1 |
+| agent-skill-creator | 96 | 5 | 🔥 | 1.5x | **144** | #2 |
+| skill-codex | 153 | 9 | 🔥 | 1.5x | **229.5** | Would be #2, but bumped by age |
+| ios-simulator-skill | 77 | 2 | 🔥 | 1.5x | **115.5** | #3 |
+| claude-skills-mcp | 85 | 2 | 🔥 | 1.5x | **127.5** | #4 |
+
+*With hot multiplier, even 77 stars beats 96 stars from 30+ days ago*
+
+### Score Comparison Scenarios
+
+**Scenario 1: Fresh skill vs. Popular old skill**
+- Skill A: 50 stars, 10 days old → 50 × 1.5 = **75 points** 🔥
+- Skill B: 100 stars, 200 days old → 100 × 0.5 = **50 points** ⏰
+- **Winner: Skill A** (freshness wins)
+
+**Scenario 2: Very popular but older skill**
+- Skill A: 1000 stars, 365 days old → 1000 × 0.5 = **500 points** ⏰
+- Skill B: 200 stars, 15 days old → 200 × 1.5 = **300 points** 🔥
+- **Winner: Skill A** (massive popularity overcomes age)
+
+**Scenario 3: Moderate skill, regularly updated**
+- Skill A: 50 stars, 85 days old → 50 × 1.2 = **60 points** 📅
+- Skill B: 60 stars, 95 days old → 60 × 1.0 = **60 points** 📆
+- **Tie** (freshness threshold matters)
+
+## Handling Edge Cases
+
+### Newly Created Skills (< 7 days old)
+
+```bash
+# New skills may have inflated scores, add small penalty
+if [ $days_old -lt 7 ]; then
+  new_skill_penalty=0.9
+  score=$(echo "$score * $new_skill_penalty" | bc)
+  note="⚠️ Very new skill - limited validation"
+fi
+```
+
+### Archived or Deprecated Skills
+
+```bash
+# Check if repository is archived
+is_archived=$(gh api "repos/$repo" | jq -r '.archived')
+
+if [ "$is_archived" = "true" ]; then
+  score=0  # Exclude from results
+  note="🔒 Archived - no longer maintained"
+fi
+```
+
+### Fork vs. Original
+
+```bash
+# Check if repository is a fork
+is_fork=$(gh api "repos/$repo" | jq -r '.fork')
+
+if [ "$is_fork" = "true" ]; then
+  # Check if fork has more stars than parent
+  parent_stars=$(gh api "repos/$repo" | jq -r '.parent.stargazers_count')
+  if [ $stars -gt $parent_stars ]; then
+    # Fork is more popular, keep it
+    note="🍴 Popular fork"
+  else
+    # Prefer original
+    score=$(echo "$score * 0.8" | bc)
+    note="🍴 Fork - see original"
+  fi
+fi
+```
+
+## Sorting and Display
+
+### Final Sort Order
+
+```bash
+# Sort by score (descending), then by stars (descending)
+results | sort -t'|' -k1,1nr -k3,3nr | head -10
+```
+
+### Ties
+
+When scores are identical:
+1. Sort by stars (higher first)
+2. If still tied, sort by freshness (newer first)
+3. If still tied, sort alphabetically
+
+```bash
+# Multi-level sort
+jq -r '.[] | "\(.score)|\(.stars)|\(.days_old)|\(.name)"' | \
+  sort -t'|' -k1,1nr -k2,2nr -k3,3n -k4,4
+```
+
+## Performance Optimization
+
+### Bulk Scoring
+
+```bash
+# Score all repos in one pass
+gh search repos "claude skills" --json name,stargazersCount,pushedAt,fullName --limit 50 | \
+  jq -r --arg now "$(date -u +%s)" '
+    .[] |
+    . as $repo |
+    ($repo.pushedAt | fromdateiso8601) as $pushed |
+    (($now | tonumber) - $pushed) / 86400 | floor as $days |
+    (if $days < 30 then 1.5 elif $days < 90 then 1.2 elif $days < 180 then 1.0 else 0.5 end) as $mult |
+    ($repo.stargazersCount * $mult) as $score |
+    {
+      name: $repo.name,
+      full_name: $repo.fullName,
+      stars: $repo.stargazersCount,
+      days_old: $days,
+      score: $score
+    }
+  ' | jq -s 'sort_by(-.score) | .[0:10]'
+```
+
+### Caching Scores
+
+```bash
+# Cache scores to avoid recalculation
+score_cache=".skill-scores.json"
+
+# Generate or load cache
+if [ ! -f "$score_cache" ] || [ $(($(date +%s) - $(stat -f %m "$score_cache"))) -gt 3600 ]; then
+  # Regenerate cache (older than 1 hour)
+  calculate_all_scores > "$score_cache"
+fi
+
+# Use cached scores
+cat "$score_cache" | jq '.[] | select(.score > 50)'
+```
+
+## Customization
+
+### User-Defined Weights
+
+Allow users to adjust ranking preferences:
+
+```bash
+# Default weights
+STAR_WEIGHT=1.0
+FRESHNESS_WEIGHT=1.0
+QUALITY_WEIGHT=0.5
+
+# Calculate weighted score
+weighted_score=$(echo "$stars * $STAR_WEIGHT + $freshness_score * $FRESHNESS_WEIGHT + $quality_score * $QUALITY_WEIGHT" | bc)
+```
+
+### Category-Specific Ranking
+
+Different categories may value different factors:
+
+```bash
+# For automation skills: prioritize quality (working code)
+if [ "$category" = "automation" ]; then
+  QUALITY_WEIGHT=1.5
+fi
+
+# For research skills: prioritize freshness (up-to-date sources)
+if [ "$category" = "research" ]; then
+  FRESHNESS_WEIGHT=1.5
+fi
+```
+
+---
+
+**Summary:** The ranking algorithm balances popularity (stars) with recency (freshness), ensuring users see both well-established skills and cutting-edge new capabilities. Quality signals provide additional nuance for edge cases.
--- a/skills/skill/references/search-strategies.md
+++ b/skills/skill/references/search-strategies.md
@@ -0,0 +1,334 @@
+# Search Strategies for Finding Claude Skills
+
+Comprehensive guide to searching GitHub for Claude skills using multiple approaches.
+
+## Overview
+
+Use a **multi-method approach** combining repository search, code search, and pattern matching to find the maximum number of relevant skills.
+
+## Method 1: Repository Search
+
+Find repositories dedicated to Claude skills.
+
+### Basic Repository Search
+
+```bash
+gh search repos "claude skills" --sort stars --order desc --limit 20 \
+  --json name,stargazersCount,description,url,createdAt,pushedAt,owner
+```
+
+### Advanced Repository Queries
+
+```bash
+# Skills specifically for Claude Code
+gh search repos "claude code skills" --sort stars --limit 20 --json name,stargazersCount,url,pushedAt
+
+# Recent skills (last 30 days)
+gh search repos "claude skills" "created:>$(date -v-30d +%Y-%m-%d)" --sort stars --limit 20
+
+# Highly starred skills
+gh search repos "claude skills" "stars:>50" --sort stars --limit 20
+
+# Active repositories (recently updated)
+gh search repos "claude skills" --sort updated --limit 20
+
+# Repositories with specific topics
+gh search repos "topic:claude topic:skills" --sort stars --limit 20
+```
+
+### Filter Out Noise
+
+```bash
+# Exclude awesome-lists and collections
+gh search repos "claude skills" --sort stars --limit 30 | \
+  jq '[.[] | select(.name | test("awesome|collection|curated") | not)]'
+```
+
+## Method 2: Code Search for SKILL.md
+
+Directly find SKILL.md files across all repositories.
+
+### Basic Code Search
+
+```bash
+gh search code "filename:SKILL.md" --limit 30 \
+  --json repository,path,url,sha
+```
+
+### Path-Specific Searches
+
+```bash
+# Skills in .claude/skills directory
+gh search code "path:.claude/skills" "filename:SKILL.md" --limit 30
+
+# Skills in skills/ subdirectory (plugin format)
+gh search code "path:skills/" "filename:SKILL.md" --limit 30
+
+# Root-level SKILL.md files
+gh search code "filename:SKILL.md" "NOT path:/" --limit 30
+```
+
+### Content-Based Search
+
+```bash
+# Find skills mentioning specific capabilities
+gh search code "browser automation" "filename:SKILL.md" --limit 20
+
+# Find MCP-related skills
+gh search code "MCP server" "filename:SKILL.md" --limit 20
+
+# Find research/analysis skills
+gh search code "web search OR data analysis" "filename:SKILL.md" --limit 20
+```
+
+## Method 3: Skill-Specific Pattern Matching
+
+Search for known skill patterns and structures.
+
+### Known Skill Repositories
+
+```bash
+# Check popular skill collections
+repos=(
+  "BehiSecc/awesome-claude-skills"
+  "travisvn/awesome-claude-skills"
+  "simonw/claude-skills"
+  "mrgoonie/claudekit-skills"
+)
+
+for repo in "${repos[@]}"; do
+  gh api "repos/$repo/git/trees/main?recursive=1" | \
+    jq -r '.tree[] | select(.path | contains("SKILL.md")) | .path'
+done
+```
+
+### Plugin Format Detection
+
+```bash
+# Repositories following .claude-plugin structure
+gh search code "filename:.claude-plugin" --limit 20 | \
+  jq -r '.[] | .repository.full_name' | \
+  while read repo; do
+    # Check for skills subdirectory
+    gh api "repos/$repo/contents/skills" 2>/dev/null | \
+      jq -r '.[].name'
+  done
+```
+
+## Method 4: Organization/User-Based Search
+
+Find skills from known skill creators.
+
+### Popular Skill Authors
+
+```bash
+# Search by user
+users=(
+  "lackeyjb"        # playwright-skill
+  "FrancyJGLisboa"  # agent-skill-creator
+  "alirezarezvani"  # skill factory
+)
+
+for user in "${users[@]}"; do
+  gh search repos "user:$user" "SKILL.md" --limit 10
+done
+```
+
+### Organization Search
+
+```bash
+# Search within organizations
+gh search repos "org:anthropics" "skills" --limit 20
+gh search repos "org:skills-directory" --limit 20
+```
+
+## Combining Results
+
+### Deduplication Strategy
+
+```bash
+# Collect all results
+all_repos=()
+
+# From repository search
+repos1=$(gh search repos "claude skills" --json name,owner | jq -r '.[] | "\(.owner.login)/\(.name)"')
+
+# From code search
+repos2=$(gh search code "filename:SKILL.md" --json repository | jq -r '.[].repository.full_name' | sort -u)
+
+# Combine and deduplicate
+all_repos=($(echo "$repos1 $repos2" | tr ' ' '\n' | sort -u))
+
+# Fetch metadata for unique repos
+for repo in "${all_repos[@]}"; do
+  gh api "repos/$repo" --jq '{
+    name: .name,
+    full_name: .full_name,
+    stars: .stargazers_count,
+    updated: .pushed_at,
+    description: .description
+  }'
+done
+```
+
+## Search Optimization
+
+### Parallel Execution
+
+```bash
+# Run all searches in parallel for speed
+{
+  gh search repos "claude skills" --limit 20 > repos.json &
+  gh search code "filename:SKILL.md" --limit 30 > code.json &
+  gh search code "path:.claude/skills" --limit 20 > paths.json &
+  wait
+}
+
+# Merge results
+jq -s 'add | unique_by(.repository.full_name)' repos.json code.json paths.json
+```
+
+### Caching Results
+
+```bash
+# Cache results to avoid hitting rate limits
+cache_file=".skill-finder-cache.json"
+cache_ttl=3600  # 1 hour
+
+if [ -f "$cache_file" ] && [ $(($(date +%s) - $(stat -f %m "$cache_file"))) -lt $cache_ttl ]; then
+  # Use cached results
+  cat "$cache_file"
+else
+  # Fetch fresh results and cache
+  gh search repos "claude skills" --limit 50 > "$cache_file"
+  cat "$cache_file"
+fi
+```
+
+## Category-Specific Searches
+
+### Automation Skills
+
+```bash
+gh search code "playwright OR selenium OR puppeteer" "filename:SKILL.md"
+gh search code "browser automation OR web automation" "filename:SKILL.md"
+```
+
+### Research Skills
+
+```bash
+gh search code "web search OR research OR analysis" "filename:SKILL.md"
+gh search code "data collection OR scraping" "filename:SKILL.md"
+```
+
+### Development Skills
+
+```bash
+gh search code "git OR github OR code review" "filename:SKILL.md"
+gh search code "testing OR linting OR formatting" "filename:SKILL.md"
+```
+
+### Integration Skills
+
+```bash
+gh search code "MCP server OR API integration" "filename:SKILL.md"
+gh search code "webhook OR external service" "filename:SKILL.md"
+```
+
+## Quality Filters
+
+### Star-Based Filtering
+
+```bash
+# Only repos with 10+ stars
+gh search repos "claude skills" "stars:>=10" --limit 20
+
+# Trending (many stars, recently created)
+gh search repos "claude skills" "stars:>50" "created:>2025-01-01" --limit 20
+```
+
+### Activity-Based Filtering
+
+```bash
+# Updated in last 30 days
+gh search repos "claude skills" "pushed:>$(date -v-30d +%Y-%m-%d)" --limit 20
+
+# Active development (multiple commits recently)
+gh api graphql -f query='
+{
+  search(query: "claude skills sort:updated", type: REPOSITORY, first: 20) {
+    nodes {
+      ... on Repository {
+        name
+        stargazerCount
+        pushedAt
+        defaultBranchRef {
+          target {
+            ... on Commit {
+              history(first: 10) {
+                totalCount
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}'
+```
+
+## Error Handling
+
+### Rate Limit Checking
+
+```bash
+# Check remaining API calls
+gh api rate_limit | jq '.rate.remaining'
+
+# If low, wait or authenticate
+if [ $(gh api rate_limit | jq '.rate.remaining') -lt 10 ]; then
+  echo "⚠️  Low on API calls. Waiting..."
+  sleep 60
+fi
+```
+
+### Fallback Strategies
+
+```bash
+# If authenticated search fails, try unauthenticated
+gh search repos "claude skills" --limit 10 2>/dev/null || \
+  curl -s "https://api.github.com/search/repositories?q=claude+skills&per_page=10"
+```
+
+## Performance Benchmarks
+
+| Method | API Calls | Results | Speed | Best For |
+|--------|-----------|---------|-------|----------|
+| Repository search | 1 | 20-30 | Fast | Popular skills |
+| Code search | 1 | 30-50 | Medium | All skills |
+| Recursive tree | N repos | 50+ | Slow | Completeness |
+| Combined | 3-5 | 100+ | Medium | Best coverage |
+
+## Recommended Workflow
+
+1. **Quick search** (1 API call, <5 sec):
+   ```bash
+   gh search repos "claude skills" --limit 20
+   ```
+
+2. **Comprehensive search** (3 API calls, ~15 sec):
+   ```bash
+   # Parallel execution
+   gh search repos "claude skills" &
+   gh search code "filename:SKILL.md" &
+   gh search code "path:.claude/skills" &
+   wait
+   ```
+
+3. **Deep search** (10+ API calls, ~60 sec):
+   - All of the above
+   - Repository tree traversal
+   - Organization searches
+   - Known author searches
+
+Choose based on user needs and time constraints.