Merge pull request #52 from upalkhouski/claude/fix-skill-version-property-0LwK3

Fixes spec compliance — version belongs under metadata, not top-level. Fixes Claude Desktop skill loading.

skills/ab-test-setup/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: ab-test-setup
-version: 1.0.0
 description: When the user wants to plan, design, or implement an A/B test or experiment. Also use when the user mentions "A/B test," "split test," "experiment," "test this change," "variant copy," "multivariate test," or "hypothesis." For tracking implementation, see analytics-tracking.
+metadata:
+  version: 1.0.0
 ---
 
 # A/B Test Setup

skills/analytics-tracking/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: analytics-tracking
-version: 1.0.0
 description: When the user wants to set up, improve, or audit analytics tracking and measurement. Also use when the user mentions "set up tracking," "GA4," "Google Analytics," "conversion tracking," "event tracking," "UTM parameters," "tag manager," "GTM," "analytics implementation," or "tracking plan." For A/B test measurement, see ab-test-setup.
+metadata:
+  version: 1.0.0
 ---
 
 # Analytics Tracking

skills/competitor-alternatives/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: competitor-alternatives
-version: 1.0.0
 description: "When the user wants to create competitor comparison or alternative pages for SEO and sales enablement. Also use when the user mentions 'alternative page,' 'vs page,' 'competitor comparison,' 'comparison page,' '[Product] vs [Product],' '[Product] alternative,' or 'competitive landing pages.' Covers four formats: singular alternative, plural alternatives, you vs competitor, and competitor vs competitor. Emphasizes deep research, modular content architecture, and varied section types beyond feature tables."
+metadata:
+  version: 1.0.0
 ---
 
 # Competitor & Alternative Pages

skills/content-strategy/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: content-strategy
-version: 1.0.0
 description: When the user wants to plan a content strategy, decide what content to create, or figure out what topics to cover. Also use when the user mentions "content strategy," "what should I write about," "content ideas," "blog strategy," "topic clusters," or "content planning." For writing individual pieces, see copywriting. For SEO-specific audits, see seo-audit.
+metadata:
+  version: 1.0.0
 ---
 
 # Content Strategy

skills/copy-editing/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: copy-editing
-version: 1.0.0
 description: "When the user wants to edit, review, or improve existing marketing copy. Also use when the user mentions 'edit this copy,' 'review my copy,' 'copy feedback,' 'proofread,' 'polish this,' 'make this better,' or 'copy sweep.' This skill provides a systematic approach to editing marketing copy through multiple focused passes."
+metadata:
+  version: 1.0.0
 ---
 
 # Copy Editing

skills/copywriting/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: copywriting
-version: 1.0.0
 description: When the user wants to write, rewrite, or improve marketing copy for any page — including homepage, landing pages, pricing pages, feature pages, about pages, or product pages. Also use when the user says "write copy for," "improve this copy," "rewrite this page," "marketing copy," "headline help," or "CTA copy." For email copy, see email-sequence. For popup copy, see popup-cro.
+metadata:
+  version: 1.0.0
 ---
 
 # Copywriting

skills/email-sequence/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: email-sequence
-version: 1.0.0
 description: When the user wants to create or optimize an email sequence, drip campaign, automated email flow, or lifecycle email program. Also use when the user mentions "email sequence," "drip campaign," "nurture sequence," "onboarding emails," "welcome sequence," "re-engagement emails," "email automation," or "lifecycle emails." For in-app onboarding, see onboarding-cro.
+metadata:
+  version: 1.0.0
 ---
 
 # Email Sequence Design

skills/form-cro/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: form-cro
-version: 1.0.0
 description: When the user wants to optimize any form that is NOT signup/registration — including lead capture forms, contact forms, demo request forms, application forms, survey forms, or checkout forms. Also use when the user mentions "form optimization," "lead form conversions," "form friction," "form fields," "form completion rate," or "contact form." For signup/registration forms, see signup-flow-cro. For popups containing forms, see popup-cro.
+metadata:
+  version: 1.0.0
 ---
 
 # Form CRO

skills/free-tool-strategy/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: free-tool-strategy
-version: 1.0.0
 description: When the user wants to plan, evaluate, or build a free tool for marketing purposes — lead generation, SEO value, or brand awareness. Also use when the user mentions "engineering as marketing," "free tool," "marketing tool," "calculator," "generator," "interactive tool," "lead gen tool," "build a tool for leads," or "free resource." This skill bridges engineering and marketing — useful for founders and technical marketers.
+metadata:
+  version: 1.0.0
 ---
 
 # Free Tool Strategy (Engineering as Marketing)

skills/launch-strategy/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: launch-strategy
-version: 1.0.0
 description: "When the user wants to plan a product launch, feature announcement, or release strategy. Also use when the user mentions 'launch,' 'Product Hunt,' 'feature release,' 'announcement,' 'go-to-market,' 'beta launch,' 'early access,' 'waitlist,' or 'product update.' This skill covers phased launches, channel strategy, and ongoing launch momentum."
+metadata:
+  version: 1.0.0
 ---
 
 # Launch Strategy

skills/marketing-ideas/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: marketing-ideas
-version: 1.0.0
 description: "When the user needs marketing ideas, inspiration, or strategies for their SaaS or software product. Also use when the user asks for 'marketing ideas,' 'growth ideas,' 'how to market,' 'marketing strategies,' 'marketing tactics,' 'ways to promote,' or 'ideas to grow.' This skill provides 139 proven marketing approaches organized by category."
+metadata:
+  version: 1.0.0
 ---
 
 # Marketing Ideas for SaaS

skills/marketing-psychology/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: marketing-psychology
-version: 1.0.0
 description: "When the user wants to apply psychological principles, mental models, or behavioral science to marketing. Also use when the user mentions 'psychology,' 'mental models,' 'cognitive bias,' 'persuasion,' 'behavioral science,' 'why people buy,' 'decision-making,' or 'consumer behavior.' This skill provides 70+ mental models organized for marketing application."
+metadata:
+  version: 1.0.0
 ---
 
 # Marketing Psychology & Mental Models

skills/onboarding-cro/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: onboarding-cro
-version: 1.0.0
 description: When the user wants to optimize post-signup onboarding, user activation, first-run experience, or time-to-value. Also use when the user mentions "onboarding flow," "activation rate," "user activation," "first-run experience," "empty states," "onboarding checklist," "aha moment," or "new user experience." For signup/registration optimization, see signup-flow-cro. For ongoing email sequences, see email-sequence.
+metadata:
+  version: 1.0.0
 ---
 
 # Onboarding CRO

skills/page-cro/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: page-cro
-version: 1.0.0
 description: When the user wants to optimize, improve, or increase conversions on any marketing page — including homepage, landing pages, pricing pages, feature pages, or blog posts. Also use when the user says "CRO," "conversion rate optimization," "this page isn't converting," "improve conversions," or "why isn't this page working." For signup/registration flows, see signup-flow-cro. For post-signup activation, see onboarding-cro. For forms outside of signup, see form-cro. For popups/modals, see popup-cro.
+metadata:
+  version: 1.0.0
 ---
 
 # Page Conversion Rate Optimization (CRO)

skills/paid-ads/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: paid-ads
-version: 1.0.0
 description: "When the user wants help with paid advertising campaigns on Google Ads, Meta (Facebook/Instagram), LinkedIn, Twitter/X, or other ad platforms. Also use when the user mentions 'PPC,' 'paid media,' 'ad copy,' 'ad creative,' 'ROAS,' 'CPA,' 'ad campaign,' 'retargeting,' or 'audience targeting.' This skill covers campaign strategy, ad creation, audience targeting, and optimization."
+metadata:
+  version: 1.0.0
 ---
 
 # Paid Ads

skills/paywall-upgrade-cro/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: paywall-upgrade-cro
-version: 1.0.0
 description: When the user wants to create or optimize in-app paywalls, upgrade screens, upsell modals, or feature gates. Also use when the user mentions "paywall," "upgrade screen," "upgrade modal," "upsell," "feature gate," "convert free to paid," "freemium conversion," "trial expiration screen," "limit reached screen," "plan upgrade prompt," or "in-app pricing." Distinct from public pricing pages (see page-cro) — this skill focuses on in-product upgrade moments where the user has already experienced value.
+metadata:
+  version: 1.0.0
 ---
 
 # Paywall and Upgrade Screen CRO

skills/popup-cro/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: popup-cro
-version: 1.0.0
 description: When the user wants to create or optimize popups, modals, overlays, slide-ins, or banners for conversion purposes. Also use when the user mentions "exit intent," "popup conversions," "modal optimization," "lead capture popup," "email popup," "announcement banner," or "overlay." For forms outside of popups, see form-cro. For general page conversion optimization, see page-cro.
+metadata:
+  version: 1.0.0
 ---
 
 # Popup CRO

skills/pricing-strategy/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: pricing-strategy
-version: 1.0.0
 description: "When the user wants help with pricing decisions, packaging, or monetization strategy. Also use when the user mentions 'pricing,' 'pricing tiers,' 'freemium,' 'free trial,' 'packaging,' 'price increase,' 'value metric,' 'Van Westendorp,' 'willingness to pay,' or 'monetization.' This skill covers pricing research, tier structure, and packaging strategy."
+metadata:
+  version: 1.0.0
 ---
 
 # Pricing Strategy

skills/product-marketing-context/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: product-marketing-context
-version: 1.0.0
 description: "When the user wants to create or update their product marketing context document. Also use when the user mentions 'product context,' 'marketing context,' 'set up context,' 'positioning,' or wants to avoid repeating foundational information across marketing tasks. Creates `.claude/product-marketing-context.md` that other marketing skills reference."
+metadata:
+  version: 1.0.0
 ---
 
 # Product Marketing Context

skills/programmatic-seo/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: programmatic-seo
-version: 1.0.0
 description: When the user wants to create SEO-driven pages at scale using templates and data. Also use when the user mentions "programmatic SEO," "template pages," "pages at scale," "directory pages," "location pages," "[keyword] + [city] pages," "comparison pages," "integration pages," or "building many pages for SEO." For auditing existing SEO issues, see seo-audit.
+metadata:
+  version: 1.0.0
 ---
 
 # Programmatic SEO

skills/referral-program/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: referral-program
-version: 1.0.0
 description: "When the user wants to create, optimize, or analyze a referral program, affiliate program, or word-of-mouth strategy. Also use when the user mentions 'referral,' 'affiliate,' 'ambassador,' 'word of mouth,' 'viral loop,' 'refer a friend,' or 'partner program.' This skill covers program design, incentive structure, and growth optimization."
+metadata:
+  version: 1.0.0
 ---
 
 # Referral & Affiliate Programs

skills/schema-markup/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: schema-markup
-version: 1.0.0
 description: When the user wants to add, fix, or optimize schema markup and structured data on their site. Also use when the user mentions "schema markup," "structured data," "JSON-LD," "rich snippets," "schema.org," "FAQ schema," "product schema," "review schema," or "breadcrumb schema." For broader SEO issues, see seo-audit.
+metadata:
+  version: 1.0.0
 ---
 
 # Schema Markup

skills/seo-audit/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: seo-audit
-version: 1.0.0
 description: When the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions "SEO audit," "technical SEO," "why am I not ranking," "SEO issues," "on-page SEO," "meta tags review," or "SEO health check." For building pages at scale to target keywords, see programmatic-seo. For adding structured data, see schema-markup.
+metadata:
+  version: 1.0.0
 ---
 
 # SEO Audit

skills/signup-flow-cro/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: signup-flow-cro
-version: 1.0.0
 description: When the user wants to optimize signup, registration, account creation, or trial activation flows. Also use when the user mentions "signup conversions," "registration friction," "signup form optimization," "free trial signup," "reduce signup dropoff," or "account creation flow." For post-signup onboarding, see onboarding-cro. For lead capture forms (not account creation), see form-cro.
+metadata:
+  version: 1.0.0
 ---
 
 # Signup Flow CRO

skills/social-content/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: social-content
-version: 1.0.0
 description: "When the user wants help creating, scheduling, or optimizing social media content for LinkedIn, Twitter/X, Instagram, TikTok, Facebook, or other platforms. Also use when the user mentions 'LinkedIn post,' 'Twitter thread,' 'social media,' 'content calendar,' 'social scheduling,' 'engagement,' or 'viral content.' This skill covers content creation, repurposing, and platform-specific strategies."
+metadata:
+  version: 1.0.0
 ---
 
 # Social Content

validate-skills-official.sh

@@ -0,0 +1,85 @@
+#!/bin/bash
+
+# Validation script using official skills-ref library
+# https://github.com/agentskills/agentskills/tree/main/skills-ref
+
+SKILLS_DIR="skills"
+SKILLS_REF_DIR="/tmp/agentskills/skills-ref"
+
+echo "🔍 Validating Skills Using Official skills-ref Library"
+echo "========================================================"
+echo "Reference: https://github.com/agentskills/agentskills"
+echo ""
+
+# Check if skills-ref is already installed
+if [ ! -d "$SKILLS_REF_DIR/.venv" ]; then
+    echo "📦 Installing skills-ref library..."
+    echo ""
+
+    if [ ! -d "$SKILLS_REF_DIR" ]; then
+        cd /tmp
+        git clone https://github.com/agentskills/agentskills.git
+    fi
+
+    cd "$SKILLS_REF_DIR"
+
+    if command -v uv &> /dev/null; then
+        echo "Using uv to install..."
+        uv sync
+    else
+        echo "Using pip to install..."
+        python3 -m venv .venv
+        source .venv/bin/activate
+        pip install -e .
+    fi
+    echo ""
+fi
+
+# Activate the virtual environment
+source "$SKILLS_REF_DIR/.venv/bin/activate"
+
+# Return to the original directory
+cd "$(dirname "$0")"
+
+# Track results
+PASSED=0
+FAILED=0
+FAILED_SKILLS=()
+
+echo "Running validation..."
+echo ""
+
+# Validate each skill
+for skill_dir in "$SKILLS_DIR"/*/; do
+    skill_name=$(basename "$skill_dir")
+    printf "  %-30s" "$skill_name"
+
+    output=$(skills-ref validate "$skill_dir" 2>&1)
+    if echo "$output" | grep -q "Valid skill"; then
+        echo "✓"
+        ((PASSED++))
+    else
+        echo "✗"
+        ((FAILED++))
+        FAILED_SKILLS+=("$skill_name")
+        echo "$output" | sed 's/^/    /'
+    fi
+done
+
+echo ""
+echo "========================================================"
+echo "Summary:"
+echo "  ✓ Passed: $PASSED"
+echo "  ✗ Failed: $FAILED"
+echo ""
+
+if [ $FAILED -eq 0 ]; then
+    echo "✅ All skills are valid!"
+    exit 0
+else
+    echo "❌ Failed skills:"
+    for skill in "${FAILED_SKILLS[@]}"; do
+        echo "  - $skill"
+    done
+    exit 1
+fi

validate-skills.sh

@@ -0,0 +1,169 @@
+#!/bin/bash
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+SKILLS_DIR="skills"
+ISSUES=0
+WARNINGS=0
+PASSED=0
+
+echo "🔍 Auditing Skills Against Agent Skills Specification"
+echo "======================================================"
+echo ""
+echo "Reference: https://agentskills.io/specification.md"
+echo ""
+
+# Validation rules from CLAUDE.md
+# REQUIRED: name, description
+# OPTIONAL: license, metadata
+# name: 1-64 chars, lowercase a-z, numbers, hyphens only, must match directory
+# description: 1-1024 chars with trigger phrases
+# SKILL.md: under 500 lines
+# Optional dirs: references/, scripts/, assets/
+
+for skill_dir in "$SKILLS_DIR"/*/; do
+    skill_name=$(basename "$skill_dir")
+    skill_file="$skill_dir/SKILL.md"
+    skill_errors=()
+    skill_warnings=()
+
+    # Check if SKILL.md exists
+    if [[ ! -f "$skill_file" ]]; then
+        echo -e "${RED}❌ $skill_name${NC}"
+        echo "   Missing SKILL.md"
+        ((ISSUES++))
+        continue
+    fi
+
+    # Extract frontmatter
+    frontmatter=$(sed -n '/^---$/,/^---$/p' "$skill_file" | head -n -1 | tail -n +2)
+
+    # Validate frontmatter exists
+    if [[ -z "$frontmatter" ]]; then
+        echo -e "${RED}❌ $skill_name${NC}"
+        echo "   Missing YAML frontmatter (---)"
+        ((ISSUES++))
+        continue
+    fi
+
+    # ===== NAME VALIDATION =====
+    name_in_file=$(echo "$frontmatter" | grep "^name:" | sed 's/^name: //' | tr -d ' ')
+
+    if [[ -z "$name_in_file" ]]; then
+        skill_errors+=("Missing 'name' field in frontmatter")
+    elif [[ "$name_in_file" != "$skill_name" ]]; then
+        skill_errors+=("Name mismatch: directory='$skill_name' but frontmatter='$name_in_file'")
+    elif ! [[ "$name_in_file" =~ ^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$ ]]; then
+        skill_errors+=("Invalid name format: '$name_in_file' (must be lowercase, alphanumeric + hyphens only)")
+    elif [[ ${#name_in_file} -lt 1 || ${#name_in_file} -gt 64 ]]; then
+        skill_errors+=("Name length invalid: ${#name_in_file} chars (must be 1-64)")
+    fi
+
+    # ===== DESCRIPTION VALIDATION =====
+    # Handle both quoted and unquoted descriptions
+    description=$(echo "$frontmatter" | grep "^description:" | head -1)
+    if [[ $description == *'description: "'* ]]; then
+        # Quoted description - extract between quotes
+        description=$(echo "$description" | sed 's/^description: "//' | sed 's/"$//')
+    else
+        # Unquoted description
+        description=$(echo "$description" | sed 's/^description: //')
+    fi
+
+    if [[ -z "$description" ]]; then
+        skill_errors+=("Missing 'description' field in frontmatter")
+    else
+        desc_len=${#description}
+        if [[ $desc_len -lt 1 || $desc_len -gt 1024 ]]; then
+            skill_errors+=("Description length invalid: $desc_len chars (must be 1-1024)")
+        fi
+
+        # Check for trigger phrases (When, when to use, mentions, etc.)
+        if ! echo "$description" | grep -qi "when\|mention\|use"; then
+            skill_warnings+=("Description lacks clear trigger phrases ('when', 'mention', 'use')")
+        fi
+
+        # Check for related skills reference (scope boundaries)
+        if ! echo "$description" | grep -qi "see\|for\|ref"; then
+            skill_warnings+=("Description lacks related skills reference (e.g., 'For X, see Y')")
+        fi
+    fi
+
+    # ===== OPTIONAL FIELDS VALIDATION =====
+    license=$(echo "$frontmatter" | grep "^license:" | sed 's/^license: //' | tr -d ' ')
+    if [[ -n "$license" && "$license" != "MIT" && "$license" != "Apache-2.0" && "$license" != "ISC" ]]; then
+        skill_warnings+=("License '$license' is non-standard (default: MIT)")
+    fi
+
+    # Check metadata structure
+    metadata=$(echo "$frontmatter" | grep -A 10 "^metadata:")
+    if [[ -n "$metadata" ]]; then
+        # If metadata exists, check for version placement
+        if echo "$frontmatter" | grep -q "^version:"; then
+            skill_errors+=("'version' is top-level (should be under 'metadata:')")
+        fi
+        # Could add more metadata validation here
+    fi
+
+    # ===== FILE STRUCTURE VALIDATION =====
+    line_count=$(wc -l < "$skill_file")
+    if [[ $line_count -gt 500 ]]; then
+        skill_warnings+=("SKILL.md is $line_count lines (should be <500, move details to references/)")
+    fi
+
+    # Check for optional directories
+    for optdir in references scripts assets; do
+        if [[ -d "$skill_dir/$optdir" ]]; then
+            # Just note its presence - no validation required
+            :
+        fi
+    done
+
+    # ===== REPORT RESULTS =====
+    if [[ ${#skill_errors[@]} -gt 0 ]]; then
+        echo -e "${RED}❌ $skill_name${NC}"
+        for error in "${skill_errors[@]}"; do
+            echo -e "   ${RED}Error:${NC} $error"
+        done
+        if [[ ${#skill_warnings[@]} -gt 0 ]]; then
+            for warning in "${skill_warnings[@]}"; do
+                echo -e "   ${YELLOW}Warning:${NC} $warning"
+            done
+        fi
+        ((ISSUES++))
+    elif [[ ${#skill_warnings[@]} -gt 0 ]]; then
+        echo -e "${YELLOW}⚠️  $skill_name${NC}"
+        for warning in "${skill_warnings[@]}"; do
+            echo -e "   ${YELLOW}Warning:${NC} $warning"
+        done
+        ((WARNINGS++))
+    else
+        echo -e "${GREEN}✓ $skill_name${NC}"
+        ((PASSED++))
+    fi
+done
+
+echo ""
+echo "======================================================"
+echo "Summary:"
+echo -e "  ${GREEN}✓ Passed: $PASSED${NC}"
+if [[ $WARNINGS -gt 0 ]]; then
+    echo -e "  ${YELLOW}⚠️  Warnings: $WARNINGS${NC}"
+fi
+if [[ $ISSUES -gt 0 ]]; then
+    echo -e "  ${RED}❌ Issues: $ISSUES${NC}"
+fi
+echo ""
+
+if [[ $ISSUES -eq 0 ]]; then
+    echo -e "${GREEN}All skills are valid! ✓${NC}"
+    exit 0
+else
+    echo -e "${RED}Found $ISSUES issue(s) that need fixing.${NC}"
+    exit 1
+fi