Gardening Skills Wiki

#!/usr/bin/env bash
# Analyze failed skills-search queries to identify missing skills

set -euo pipefail

SKILLS_DIR="${HOME}/.claude/skills"
LOG_FILE="${SKILLS_DIR}/.search-log.jsonl"

if [[ ! -f "$LOG_FILE" ]]; then
    echo "No search log found at $LOG_FILE"
    exit 0
fi

echo "Skills Search Gap Analysis"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""

# Count total searches
total=$(wc -l < "$LOG_FILE")
echo "Total searches: $total"
echo ""

# Extract and count unique queries
echo "Most common searches:"
jq -r '.query' "$LOG_FILE" 2>/dev/null | sort | uniq -c | sort -rn | head -20

echo ""
echo "Recent searches (last 10):"
tail -10 "$LOG_FILE" | jq -r '"\(.timestamp) - \(.query)"' 2>/dev/null

echo ""
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
echo "High-frequency searches indicate missing skills."
echo "Review patterns and create skills as needed."

#!/bin/bash
# Check that all skills are properly listed in INDEX files

SKILLS_DIR="${1:-$HOME/Documents/GitHub/dotfiles/.claude/skills}"

echo "## INDEX Coverage"
# For each category with an INDEX
for category_dir in "$SKILLS_DIR"/*/; do
    category=$(basename "$category_dir")

    # Skip if not a directory
    [[ ! -d "$category_dir" ]] && continue

    index_file="$category_dir/INDEX.md"

    # Skip if no INDEX (meta directories might not have one)
    [[ ! -f "$index_file" ]] && continue

    # Find all SKILL.md files in this category
    skill_count=0
    indexed_count=0
    missing_count=0

    while IFS= read -r skill_file; do
        skill_count=$((skill_count + 1))
        skill_name=$(basename $(dirname "$skill_file"))

        # Check if skill is referenced in INDEX
        if grep -q "@$skill_name/SKILL.md" "$index_file"; then
            indexed_count=$((indexed_count + 1))
        else
            echo "  ❌ NOT INDEXED: $skill_name/SKILL.md"
            missing_count=$((missing_count + 1))
        fi
    done < <(find "$category_dir" -mindepth 2 -type f -name "SKILL.md")

    if [ $skill_count -gt 0 ] && [ $missing_count -eq 0 ]; then
        echo "  ✅ $category: all $skill_count skills indexed"
    elif [ $missing_count -gt 0 ]; then
        echo "  ⚠️  $category: $missing_count/$skill_count skills missing"
    fi
done

echo ""
# Verify INDEX entries have descriptions
find "$SKILLS_DIR" -type f -name "INDEX.md" | while read -r index_file; do
    category=$(basename $(dirname "$index_file"))

    # Extract skill references
    grep -o '@[a-zA-Z0-9-]*/SKILL\.md' "$index_file" | while read -r ref; do
        skill_name=${ref#@}
        skill_name=${skill_name%/SKILL.md}

        # Get the line with the reference
        line_num=$(grep -n "$ref" "$index_file" | cut -d: -f1)

        # Check if there's a description on the same line or next line
        description=$(sed -n "${line_num}p" "$index_file" | sed "s|.*$ref *- *||")

        if [[ -z "$description" || "$description" == *"$ref"* ]]; then
            # No description on same line, check next line
            next_line=$((line_num + 1))
            description=$(sed -n "${next_line}p" "$index_file")

            if [[ -z "$description" ]]; then
                echo "  ⚠️  NO DESCRIPTION: $category/INDEX.md reference to $skill_name"
            fi
        fi
    done
done

#!/bin/bash
# Check for @ links (force-load context) and validate skill path references

SKILLS_DIR="${1:-$HOME/Documents/GitHub/dotfiles/.claude/skills}"

echo "## Links & References"
broken_refs=0
backticked_refs=0
relative_refs=0
at_links=0

while IFS= read -r file; do
    # Extract @ references - must start line, be after space/paren/dash, or be standalone
    # Exclude: emails, decorators, code examples with @staticmethod/@example

    # First, check for backtick-wrapped @ links
    grep -nE '`[^`]*@[a-zA-Z0-9._~/-]+\.(md|sh|ts|js|py)[^`]*`' "$file" | while IFS=: read -r line_num match; do
        # Get actual line to check if in code block
        actual_line=$(sed -n "${line_num}p" "$file")

        # Skip if line is indented (code block) or in fenced code
        if [[ "$actual_line" =~ ^[[:space:]]{4,} ]]; then
            continue
        fi

        code_block_count=$(sed -n "1,${line_num}p" "$file" | grep -c '^```')
        if [ $((code_block_count % 2)) -eq 1 ]; then
            continue
        fi

        ref=$(echo "$match" | grep -o '@[a-zA-Z0-9._~/-]*\.[a-zA-Z0-9]*')
        echo "  ❌ BACKTICKED: $ref on line $line_num"
        echo "     File: $(basename $(dirname "$file"))/$(basename "$file")"
        echo "     Fix: Remove backticks - use bare @ reference"
        backticked_refs=$((backticked_refs + 1))
    done

    # Check for ANY @ links to .md/.sh/.ts/.js/.py files (force-loads, burns context)
    grep -nE '(^|[ \(>-])@[a-zA-Z0-9._/-]+\.(md|sh|ts|js|py)' "$file" | \
        grep -v '@[a-zA-Z0-9._%+-]*@' | \
        grep -v 'email.*@' | \
        grep -v '`.*@.*`' | while IFS=: read -r line_num match; do

        ref=$(echo "$match" | grep -o '@[a-zA-Z0-9._/-]+\.(md|sh|ts|js|py)')
        ref_path="${ref#@}"

        # Skip if in fenced code block
        actual_line=$(sed -n "${line_num}p" "$file")
        if [[ "$actual_line" =~ ^[[:space:]]{4,} ]]; then
            continue
        fi

        code_block_count=$(sed -n "1,${line_num}p" "$file" | grep -c '^```')
        if [ $((code_block_count % 2)) -eq 1 ]; then
            continue
        fi

        # Any @ link is wrong - should use skills/path format
        echo "  ❌ @ LINK: $ref on line $line_num"
        echo "     File: $(basename $(dirname "$file"))/$(basename "$file")"

        # Suggest correct format
        if [[ "$ref_path" == skills/* ]]; then
            # @skills/category/name/SKILL.md → skills/category/name
            corrected="${ref_path#skills/}"
            corrected="${corrected%/SKILL.md}"
            echo "     Fix: $ref → skills/$corrected"
        elif [[ "$ref_path" == ../* ]]; then
            echo "     Fix: Convert to skills/category/skill-name format"
        else
            echo "     Fix: Convert to skills/category/skill-name format"
        fi

        at_links=$((at_links + 1))
    done
done < <(find "$SKILLS_DIR" -type f -name "*.md")

# Summary
total_issues=$((backticked_refs + at_links))
if [ $total_issues -eq 0 ]; then
    echo "  ✅ All skill references OK"
else
    [ $backticked_refs -gt 0 ] && echo "  ❌ $backticked_refs backticked references"
    [ $at_links -gt 0 ] && echo "  ❌ $at_links @ links (force-load context)"
fi

echo ""
echo "Correct format: skills/category/skill-name"
echo "  ❌ Bad:  @skills/path/SKILL.md (force-loads) or @../path (brittle)"
echo "  ✅ Good: skills/category/skill-name (load with Read tool when needed)"

echo ""
# Verify all skills mentioned in INDEX files exist
find "$SKILLS_DIR" -type f -name "INDEX.md" | while read -r index_file; do
    index_dir=$(dirname "$index_file")

    # Extract skill references (format: @skill-name/SKILL.md)
    grep -o '@[a-zA-Z0-9-]*/SKILL\.md' "$index_file" | while read -r skill_ref; do
        skill_path="$index_dir/${skill_ref#@}"

        if [[ ! -f "$skill_path" ]]; then
            echo "  ❌ BROKEN: $skill_ref in $(basename "$index_dir")/INDEX.md"
            echo "     Expected: $skill_path"
        fi
    done
done

echo ""
find "$SKILLS_DIR" -type f -path "*/*/SKILL.md" | while read -r skill_file; do
    skill_dir=$(basename $(dirname "$skill_file"))
    category_dir=$(dirname $(dirname "$skill_file"))
    index_file="$category_dir/INDEX.md"

    if [[ -f "$index_file" ]]; then
        if ! grep -q "@$skill_dir/SKILL.md" "$index_file"; then
            echo "  ⚠️  ORPHANED: $skill_dir/SKILL.md not in $(basename "$category_dir")/INDEX.md"
        fi
    fi
done

#!/bin/bash
# Check naming consistency in skills wiki

SKILLS_DIR="${1:-$HOME/Documents/GitHub/dotfiles/.claude/skills}"

echo "## Naming & Structure"
issues=0

find "$SKILLS_DIR" -type d -mindepth 2 -maxdepth 2 | while read -r dir; do
    dir_name=$(basename "$dir")

    # Skip if it's an INDEX or top-level category
    if [[ "$dir_name" == "INDEX.md" ]] || [[ $(dirname "$dir") == "$SKILLS_DIR" ]]; then
        continue
    fi

    # Check for naming issues
    if [[ "$dir_name" =~ [A-Z] ]]; then
        echo "  ⚠️  Mixed case: $dir_name (should be kebab-case)"
        issues=$((issues + 1))
    fi

    if [[ "$dir_name" =~ _ ]]; then
        echo "  ⚠️  Underscore: $dir_name (should use hyphens)"
        issues=$((issues + 1))
    fi

    # Check if name follows gerund pattern for process skills
    if [[ -f "$dir/SKILL.md" ]]; then
        type=$(grep "^type:" "$dir/SKILL.md" | head -1 | cut -d: -f2 | xargs)

        if [[ "$type" == "technique" ]] && [[ ! "$dir_name" =~ ing$ ]] && [[ ! "$dir_name" =~ -with- ]] && [[ ! "$dir_name" =~ ^test- ]]; then
            # Techniques might want -ing but not required
            :
        fi
    fi
done

[ $issues -eq 0 ] && echo "  ✅ Directory names OK" || echo "  ⚠️  $issues naming issues"

echo ""
find "$SKILLS_DIR" -type d -empty | while read -r empty_dir; do
    echo "  ⚠️  EMPTY: $(realpath --relative-to="$SKILLS_DIR" "$empty_dir" 2>/dev/null || echo "$empty_dir")"
done

echo ""
find "$SKILLS_DIR" -type f -name "SKILL.md" | while read -r skill_file; do
    skill_name=$(basename $(dirname "$skill_file"))

    # Check for required fields
    if ! grep -q "^name:" "$skill_file"; then
        echo "  ❌ MISSING 'name': $skill_name/SKILL.md"
    fi

    if ! grep -q "^description:" "$skill_file"; then
        echo "  ❌ MISSING 'description': $skill_name/SKILL.md"
    fi

    if ! grep -q "^when_to_use:" "$skill_file"; then
        echo "  ❌ MISSING 'when_to_use': $skill_name/SKILL.md"
    fi

    if ! grep -q "^version:" "$skill_file"; then
        echo "  ⚠️  MISSING 'version': $skill_name/SKILL.md"
    fi

    # Check for active voice in name (should not start with "How to")
    name_value=$(grep "^name:" "$skill_file" | head -1 | cut -d: -f2- | xargs)
    if [[ "$name_value" =~ ^How\ to ]]; then
        echo "  ⚠️  Passive name: $skill_name has 'How to' prefix (prefer active voice)"
    fi
done

#!/bin/bash
# Master gardening script for skills wiki maintenance

SKILLS_DIR="${1:-$HOME/Documents/GitHub/dotfiles/.claude/skills}"
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

echo "=== Skills Wiki Health Check ==="
echo ""

# Make scripts executable if not already
chmod +x "$SCRIPT_DIR"/*.sh 2>/dev/null

# Run all checks
bash "$SCRIPT_DIR/check-naming.sh" "$SKILLS_DIR"
echo ""

bash "$SCRIPT_DIR/check-links.sh" "$SKILLS_DIR"
echo ""

bash "$SCRIPT_DIR/check-index-coverage.sh" "$SKILLS_DIR"

echo ""
echo "=== Health Check Complete ==="
echo ""
echo "Fix: ❌ errors (broken/missing) | Consider: ⚠️  warnings | ✅ = correct"