Skill Search Optimizer

User query → OpenAI embedding → Vector similarity search → Ranked results
             (text-embedding-*)    (Convex vector index)

PRIMARY:   description field (frontmatter)
SECONDARY: name/slug field
TERTIARY:  skill content (body markdown) — likely summarized or truncated before embedding

The description field is your search ranking. Everything else is secondary.

# How search is called internally
# POST https://clawdhub.com/api/cli/search
# Body: { "query": "user search terms", "limit": 10 }
# Returns: ranked list of skills with similarity scores

# CLI search
npx molthub@latest search "your query"

# Pattern:
# [Action verb] + [specific scope]. Use when [trigger 1], [trigger 2], [trigger 3].
# Also covers [related topic].

# Example (strong):
description: >-
  Schedule and manage recurring tasks with cron and systemd timers.
  Use when setting up cron jobs, writing systemd timer units,
  handling timezone-aware scheduling, monitoring failed jobs,
  implementing retry patterns, or debugging why a scheduled task didn't run.

# Why it works:
# - "Schedule and manage recurring tasks" → broad match for scheduling queries
# - "cron and systemd timers" → exact match for specific tool queries
# - "Use when..." triggers → matches natural-language questions
# - "debugging why a scheduled task didn't run" → matches troubleshooting queries

description: >-
  [Verb] with [tool/technology]. Use when [task 1], [task 2], [task 3].
  Covers [sub-topic 1], [sub-topic 2], and [sub-topic 3].

description: >-
  Debug Docker containers and Compose stacks. Use when inspecting
  container logs, diagnosing networking issues, troubleshooting
  build failures, or investigating resource usage. Covers exec,
  health checks, multi-stage builds, and distroless containers.

description: >-
  [Topic] patterns for [scope]. Use when [task 1], [task 2], [task 3].
  Also covers [related scope].

description: >-
  Regex patterns for validation, parsing, and text extraction across
  JavaScript, Python, Go, and grep. Use when writing regex for emails,
  URLs, IPs, dates, or custom formats. Also covers lookahead,
  lookbehind, and search-and-replace for code refactoring.

description: >-
  [Process description] from [start] to [end]. Use when [scenario 1],
  [scenario 2], [scenario 3].

description: >-
  CI/CD pipeline configuration from commit to deployment. Use when
  setting up GitHub Actions, creating matrix builds, caching
  dependencies, building Docker images, or managing deployment secrets.

# Include both the formal term AND common synonyms
description: >-
  SSH tunneling and port forwarding for remote access.
  Use when creating SSH tunnels, setting up port forwards,
  connecting through jump hosts (bastion hosts), managing
  SSH keys, or transferring files with scp and rsync.

# "tunneling" and "port forwarding" are related but distinct queries
# "jump hosts" and "bastion hosts" are synonyms — include both
# "scp and rsync" catches file transfer queries

TOO SHORT (< 50 chars):
  "Make things with Makefiles"
  → Not enough semantic surface for the embedding model

SWEET SPOT (80-200 chars):
  "Write Makefiles for any project type. Use when setting up build
   automation, defining multi-target builds, or using Make for Go,
   Python, Docker, and Node.js. Also covers Just and Task."
  → Rich semantic content, multiple match angles

TOO LONG (> 250 chars):
  [Long paragraph trying to list everything]
  → Gets truncated in search results display
  → Dilutes the embedding with low-signal words
  → Harder to read in listings

# GOOD: Heading matches likely search query
## Port Forwarding
## Key Management
## Connection Debugging

# BAD: Generic headings with no search value
## Getting Started
## Advanced Usage
## Miscellaneous

# GOOD
# SSH Tunnel

Create and manage SSH tunnels for secure remote access. Covers local,
remote, and dynamic port forwarding, jump hosts, key management,
agent forwarding, and file transfers with scp and rsync.

# BAD
# SSH Tunnel

This skill provides information about SSH.

# Test with the exact queries users would type

# Broad query (should your skill appear?)
npx molthub@latest search "docker"
npx molthub@latest search "testing"
npx molthub@latest search "build automation"

# Specific query (should your skill rank #1?)
npx molthub@latest search "debug docker container"
npx molthub@latest search "write makefile for go project"
npx molthub@latest search "cron job not running"

# Problem-oriented query (does your skill match troubleshooting?)
npx molthub@latest search "container networking not working"
npx molthub@latest search "why is my cron job not executing"

# Synonym query (does your skill match alternative terms?)
npx molthub@latest search "bastion host" # should match ssh-tunnel
npx molthub@latest search "scheduled task" # should match cron-scheduling

SEARCH VISIBILITY MATRIX
Skill: [your-skill-slug]

Query                              | Appears? | Rank | Competitor
─────────────────────────────────────────────────────────────────
[broad term]                       | Y/N      | #__  | [who ranks above]
[specific use case]                | Y/N      | #__  | [who ranks above]
[problem/troubleshooting query]    | Y/N      | #__  | [who ranks above]
[synonym for main topic]           | Y/N      | #__  | [who ranks above]
[related but different topic]      | Y/N      | #__  | [expected?]

TARGET: Appear in top 3 for specific queries, top 10 for broad queries

# 1. Publish initial version
npx molthub@latest publish ./skills/my-skill \
  --slug my-skill --name "My Skill" --version 1.0.0

# 2. Test search visibility
npx molthub@latest search "primary query"
npx molthub@latest search "secondary query"

# 3. If ranking is poor, update the description
# Edit SKILL.md frontmatter

# 4. Publish updated version
npx molthub@latest publish ./skills/my-skill \
  --slug my-skill --name "My Skill" --version 1.0.1 \
  --changelog "Improve description for search visibility"

# 5. Re-test (embeddings update on publish)
npx molthub@latest search "primary query"