Skill Search Optimizer

Optimize skills for discoverability on the ClawdHub registry. Covers how search works, how to write descriptions that rank well, content strategies for semantic matching, testing visibility, and competitive positioning.

When to Use

• - A published skill isn't appearing in relevant searches
• Writing a skill description for maximum discoverability
• Understanding how ClawdHub's search indexes and ranks skills
• Comparing your skill's visibility against competitors
• Improving an existing skill's search performance

How ClawdHub Search Works

Architecture

ClawdHub uses vector-based semantic search, not keyword matching:

CODEBLOCK0

Key implications:

1. 1. Meaning matters more than exact keywords — "container debugging" matches "Docker troubleshooting"
2. But keywords still help — the embedding model encodes specific terms with high signal
3. Description is the primary indexed field — content may contribute but description is dominant
4. Short queries match broad descriptions — "docker" matches skills about containers generally
5. Specific queries match specific descriptions — "debug crashed Docker container" favors skills that mention debugging and crashes

What Gets Indexed

CODEBLOCK1

Search API

CODEBLOCK2

Description Optimization

The anatomy of a high-ranking description

CODEBLOCK3

Description formulas

Formula 1: Tool-focused skill

CODEBLOCK4

Example:
CODEBLOCK5

Formula 2: Pattern/reference skill

CODEBLOCK6

Example:
CODEBLOCK7

Formula 3: Workflow/process skill

CODEBLOCK8

Example:
CODEBLOCK9

Keyword strategy

Semantic search understands synonyms, but being explicit helps:

CODEBLOCK10

Terms to include:

• - Primary tool names: docker, git, curl, INLINECODE3
• Action verbs: debug, test, deploy, monitor, INLINECODE8
• Common synonyms: container / Docker, CI/CD / pipeline / INLINECODE13
• Problem descriptions: debugging why X doesn't work, INLINECODE15

Description length

CODEBLOCK11

Content Optimization

How body content affects search

The skill body (markdown content after frontmatter) likely contributes to search in two ways:

1. 1. Skill preview/summary: The registry may extract or summarize content for display
2. Secondary embedding signal: Full content may be embedded separately or appended to description

Optimization strategy:

• - Front-load important terms in the first paragraph after the title
• Use headings that match search queries — "## Encode and Decode" matches better than "## Section 2"
• Repeat key terms naturally throughout the document (don't stuff, but don't avoid them either)

CODEBLOCK12

First paragraph optimization

The first paragraph after the title is prime search real estate:

CODEBLOCK13

Testing Search Visibility

Manual testing

CODEBLOCK14

Test matrix

Build a test matrix for your skill:

CODEBLOCK15

Iterative improvement

CODEBLOCK16

Competitive Positioning

Analyzing competing skills

CODEBLOCK17

Differentiation strategies

CODEBLOCK18

Filling gaps vs. competing head-on

CODEBLOCK19

Registry Dynamics

Search behavior patterns

CODEBLOCK20

Timing and freshness

CODEBLOCK21

Optimization Checklist

CODEBLOCK22

Tips

• - The description field is worth more than the entire rest of the skill for search ranking. Spend 30% of your optimization effort on those 1-2 sentences.
• "Use when..." phrases in descriptions are powerful because they match how users naturally frame searches: "I need something for when X happens."
• Include both the specific tool name AND the general category. "Docker containers" matches both "docker" queries and "container" queries. Just "Docker" misses people searching for "container debugging."
• Problem-oriented language ("debugging why X fails", "troubleshooting Y") matches a huge category of searches that purely descriptive skills miss entirely.
• Test with at least 5 different search queries before publishing. If your skill doesn't appear for its own primary topic, the description needs work.
• Slug names contribute to search matching. container-debug is better than cd-tool because the slug itself contains searchable terms.
• Don't optimize for queries your skill can't actually answer. Ranking for a query and then disappointing the user is worse than not ranking at all — it leads to reports and uninstalls.
• The registry is young. First-mover advantage is real — claim descriptive slugs and publish quality content now while competition is low.
• Re-publish with a version bump after optimizing your description. The embedding is regenerated on each publish, so description changes take effect immediately.