{ "schemaVersion": "1.0", "item": { "slug": "skill-search-optimizer", "name": "Skill Search Optimizer", "source": "tencent", "type": "skill", "category": "开发工具", "sourceUrl": "https://clawhub.ai/gitgoodordietrying/skill-search-optimizer", "canonicalUrl": "https://clawhub.ai/gitgoodordietrying/skill-search-optimizer", "targetPlatform": "OpenClaw" }, "install": { "downloadMode": "redirect", "downloadUrl": "/downloads/skill-search-optimizer", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=skill-search-optimizer", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "includedAssets": [ "SKILL.md" ], "primaryDoc": "SKILL.md", "quickSetup": [ "Download the package from Yavira.", "Extract the archive and review SKILL.md first.", "Import or place the package into your OpenClaw setup." ], "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "sourceHealth": { "source": "tencent", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-05-07T17:22:31.273Z", "expiresAt": "2026-05-14T17:22:31.273Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-annual-report", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-annual-report", "contentDisposition": "attachment; filename=\"afrexai-annual-report-1.0.0.zip\"", "redirectLocation": null, "bodySnippet": null }, "scope": "source", "summary": "Source download looks usable.", "detail": "Yavira can redirect you to the upstream package for this source.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/skill-search-optimizer" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] }, "downloadPageUrl": "https://openagent3.xyz/downloads/skill-search-optimizer", "agentPageUrl": "https://openagent3.xyz/skills/skill-search-optimizer/agent", "manifestUrl": "https://openagent3.xyz/skills/skill-search-optimizer/agent.json", "briefUrl": "https://openagent3.xyz/skills/skill-search-optimizer/agent.md" }, "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "Skill Search Optimizer", "body": "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." }, { "title": "When to Use", "body": "A published skill isn't appearing in relevant searches\nWriting a skill description for maximum discoverability\nUnderstanding how ClawdHub's search indexes and ranks skills\nComparing your skill's visibility against competitors\nImproving an existing skill's search performance" }, { "title": "Architecture", "body": "ClawdHub uses vector-based semantic search, not keyword matching:\n\nUser query → OpenAI embedding → Vector similarity search → Ranked results\n (text-embedding-*) (Convex vector index)\n\nKey implications:\n\nMeaning matters more than exact keywords — \"container debugging\" matches \"Docker troubleshooting\"\nBut keywords still help — the embedding model encodes specific terms with high signal\nDescription is the primary indexed field — content may contribute but description is dominant\nShort queries match broad descriptions — \"docker\" matches skills about containers generally\nSpecific queries match specific descriptions — \"debug crashed Docker container\" favors skills that mention debugging and crashes" }, { "title": "What Gets Indexed", "body": "PRIMARY: description field (frontmatter)\nSECONDARY: name/slug field\nTERTIARY: skill content (body markdown) — likely summarized or truncated before embedding\n\nThe description field is your search ranking. Everything else is secondary." }, { "title": "Search API", "body": "# How search is called internally\n# POST https://clawdhub.com/api/cli/search\n# Body: { \"query\": \"user search terms\", \"limit\": 10 }\n# Returns: ranked list of skills with similarity scores\n\n# CLI search\nnpx molthub@latest search \"your query\"" }, { "title": "The anatomy of a high-ranking description", "body": "# Pattern:\n# [Action verb] + [specific scope]. Use when [trigger 1], [trigger 2], [trigger 3].\n# Also covers [related topic].\n\n# Example (strong):\ndescription: >-\n Schedule and manage recurring tasks with cron and systemd timers.\n Use when setting up cron jobs, writing systemd timer units,\n handling timezone-aware scheduling, monitoring failed jobs,\n implementing retry patterns, or debugging why a scheduled task didn't run.\n\n# Why it works:\n# - \"Schedule and manage recurring tasks\" → broad match for scheduling queries\n# - \"cron and systemd timers\" → exact match for specific tool queries\n# - \"Use when...\" triggers → matches natural-language questions\n# - \"debugging why a scheduled task didn't run\" → matches troubleshooting queries" }, { "title": "Description formulas", "body": "Formula 1: Tool-focused skill\n\ndescription: >-\n [Verb] with [tool/technology]. Use when [task 1], [task 2], [task 3].\n Covers [sub-topic 1], [sub-topic 2], and [sub-topic 3].\n\nExample:\n\ndescription: >-\n Debug Docker containers and Compose stacks. Use when inspecting\n container logs, diagnosing networking issues, troubleshooting\n build failures, or investigating resource usage. Covers exec,\n health checks, multi-stage builds, and distroless containers.\n\nFormula 2: Pattern/reference skill\n\ndescription: >-\n [Topic] patterns for [scope]. Use when [task 1], [task 2], [task 3].\n Also covers [related scope].\n\nExample:\n\ndescription: >-\n Regex patterns for validation, parsing, and text extraction across\n JavaScript, Python, Go, and grep. Use when writing regex for emails,\n URLs, IPs, dates, or custom formats. Also covers lookahead,\n lookbehind, and search-and-replace for code refactoring.\n\nFormula 3: Workflow/process skill\n\ndescription: >-\n [Process description] from [start] to [end]. Use when [scenario 1],\n [scenario 2], [scenario 3].\n\nExample:\n\ndescription: >-\n CI/CD pipeline configuration from commit to deployment. Use when\n setting up GitHub Actions, creating matrix builds, caching\n dependencies, building Docker images, or managing deployment secrets." }, { "title": "Keyword strategy", "body": "Semantic search understands synonyms, but being explicit helps:\n\n# Include both the formal term AND common synonyms\ndescription: >-\n SSH tunneling and port forwarding for remote access.\n Use when creating SSH tunnels, setting up port forwards,\n connecting through jump hosts (bastion hosts), managing\n SSH keys, or transferring files with scp and rsync.\n\n# \"tunneling\" and \"port forwarding\" are related but distinct queries\n# \"jump hosts\" and \"bastion hosts\" are synonyms — include both\n# \"scp and rsync\" catches file transfer queries\n\nTerms to include:\n\nPrimary tool names: docker, git, curl, make\nAction verbs: debug, test, deploy, monitor, parse\nCommon synonyms: container / Docker, CI/CD / pipeline / GitHub Actions\nProblem descriptions: debugging why X doesn't work, troubleshooting Y" }, { "title": "Description length", "body": "TOO SHORT (< 50 chars):\n \"Make things with Makefiles\"\n → Not enough semantic surface for the embedding model\n\nSWEET SPOT (80-200 chars):\n \"Write Makefiles for any project type. Use when setting up build\n automation, defining multi-target builds, or using Make for Go,\n Python, Docker, and Node.js. Also covers Just and Task.\"\n → Rich semantic content, multiple match angles\n\nTOO LONG (> 250 chars):\n [Long paragraph trying to list everything]\n → Gets truncated in search results display\n → Dilutes the embedding with low-signal words\n → Harder to read in listings" }, { "title": "How body content affects search", "body": "The skill body (markdown content after frontmatter) likely contributes to search in two ways:\n\nSkill preview/summary: The registry may extract or summarize content for display\nSecondary embedding signal: Full content may be embedded separately or appended to description\n\nOptimization strategy:\n\nFront-load important terms in the first paragraph after the title\nUse headings that match search queries — \"## Encode and Decode\" matches better than \"## Section 2\"\nRepeat key terms naturally throughout the document (don't stuff, but don't avoid them either)\n\n# GOOD: Heading matches likely search query\n## Port Forwarding\n## Key Management\n## Connection Debugging\n\n# BAD: Generic headings with no search value\n## Getting Started\n## Advanced Usage\n## Miscellaneous" }, { "title": "First paragraph optimization", "body": "The first paragraph after the title is prime search real estate:\n\n# GOOD\n# SSH Tunnel\n\nCreate and manage SSH tunnels for secure remote access. Covers local,\nremote, and dynamic port forwarding, jump hosts, key management,\nagent forwarding, and file transfers with scp and rsync.\n\n# BAD\n# SSH Tunnel\n\nThis skill provides information about SSH." }, { "title": "Manual testing", "body": "# Test with the exact queries users would type\n\n# Broad query (should your skill appear?)\nnpx molthub@latest search \"docker\"\nnpx molthub@latest search \"testing\"\nnpx molthub@latest search \"build automation\"\n\n# Specific query (should your skill rank #1?)\nnpx molthub@latest search \"debug docker container\"\nnpx molthub@latest search \"write makefile for go project\"\nnpx molthub@latest search \"cron job not running\"\n\n# Problem-oriented query (does your skill match troubleshooting?)\nnpx molthub@latest search \"container networking not working\"\nnpx molthub@latest search \"why is my cron job not executing\"\n\n# Synonym query (does your skill match alternative terms?)\nnpx molthub@latest search \"bastion host\" # should match ssh-tunnel\nnpx molthub@latest search \"scheduled task\" # should match cron-scheduling" }, { "title": "Test matrix", "body": "Build a test matrix for your skill:\n\nSEARCH VISIBILITY MATRIX\nSkill: [your-skill-slug]\n\nQuery | Appears? | Rank | Competitor\n─────────────────────────────────────────────────────────────────\n[broad term] | Y/N | #__ | [who ranks above]\n[specific use case] | Y/N | #__ | [who ranks above]\n[problem/troubleshooting query] | Y/N | #__ | [who ranks above]\n[synonym for main topic] | Y/N | #__ | [who ranks above]\n[related but different topic] | Y/N | #__ | [expected?]\n\nTARGET: Appear in top 3 for specific queries, top 10 for broad queries" }, { "title": "Iterative improvement", "body": "# 1. Publish initial version\nnpx molthub@latest publish ./skills/my-skill \\\n --slug my-skill --name \"My Skill\" --version 1.0.0\n\n# 2. Test search visibility\nnpx molthub@latest search \"primary query\"\nnpx molthub@latest search \"secondary query\"\n\n# 3. If ranking is poor, update the description\n# Edit SKILL.md frontmatter\n\n# 4. Publish updated version\nnpx molthub@latest publish ./skills/my-skill \\\n --slug my-skill --name \"My Skill\" --version 1.0.1 \\\n --changelog \"Improve description for search visibility\"\n\n# 5. Re-test (embeddings update on publish)\nnpx molthub@latest search \"primary query\"" }, { "title": "Analyzing competing skills", "body": "# Find skills in your category\nnpx molthub@latest search \"your topic\"\n\n# For each competing skill:\n# 1. Install it\nnpx molthub@latest install competitor-skill\n\n# 2. Read the description\nhead -10 skills/competitor-skill/SKILL.md\n\n# 3. Compare:\n# - Does their description cover queries yours doesn't?\n# - Are they using terms you should add?\n# - What's their content depth vs. yours?" }, { "title": "Differentiation strategies", "body": "STRATEGY 1: Broader scope\n Competitor covers Docker. You cover Docker + Podman + containerd.\n Your description mentions all three → matches more queries.\n\nSTRATEGY 2: Deeper specificity\n Competitor covers \"git commands\". You cover \"git workflows\" with\n specific scenarios like bisect, worktree, and reflog recovery.\n Your description matches specific troubleshooting queries.\n\nSTRATEGY 3: Problem-oriented framing\n Competitor: \"Docker container management\"\n You: \"Debug Docker containers — logs, networking, crashes, resource issues\"\n Problem-oriented descriptions match how people actually search.\n\nSTRATEGY 4: Cross-tool coverage\n Competitor covers Make only. You cover Make + Just + Task.\n Your description mentions all three → broader match surface." }, { "title": "Filling gaps vs. competing head-on", "body": "MARKET ANALYSIS:\n\n1. Search for your intended topic\n2. Count results:\n 0 results → Blue ocean. Any reasonable skill will rank #1.\n 1-2 results → Low competition. A better skill wins easily.\n 3+ results → Competitive. Need clear differentiation.\n\nFor competitive categories, check the existing skills' quality:\n- Are their descriptions optimized? (Many aren't)\n- Are their examples working? (Test a few)\n- Do they cover the full scope? (Often they're narrow)\n\nA well-written skill with an optimized description will outrank\na mediocre skill even in a competitive category." }, { "title": "Search behavior patterns", "body": "COMMON SEARCH PATTERNS:\n\n1. Tool name: \"docker\", \"git\", \"terraform\"\n → Match with explicit tool name in description\n\n2. Task description: \"deploy to production\", \"parse CSV\"\n → Match with action verbs and task phrases\n\n3. Problem statement: \"container not starting\", \"cron job failed\"\n → Match with troubleshooting language in description\n\n4. Comparison: \"jest vs vitest\", \"make vs just\"\n → Match by mentioning multiple tools in description\n\n5. How-to: \"how to set up CI/CD\", \"how to forward ports\"\n → Match with \"Use when setting up...\" pattern" }, { "title": "Timing and freshness", "body": "- New skills get indexed immediately on publish\n- Updated skills get re-indexed on version bump\n- No known freshness bias (older skills don't rank lower)\n- The registry is young — early publishers have first-mover advantage\n- Slug ownership is permanent — claim good slugs early" }, { "title": "Optimization Checklist", "body": "PRE-PUBLISH SEARCH OPTIMIZATION:\n\n[ ] Description follows the [Action] + [Scope] + [Use when] pattern\n[ ] Description is 80-200 characters\n[ ] Primary tool/topic names are in the description explicitly\n[ ] Common synonyms are included (jump host / bastion host)\n[ ] Troubleshooting/problem language is included\n[ ] Action verbs match how users search (debug, test, deploy, parse)\n[ ] First paragraph after title reinforces key terms\n[ ] Section headings use searchable phrases, not generic labels\n[ ] Slug is descriptive and matches the primary search term\n[ ] No competing skill has a clearly better description for the same queries\n\nPOST-PUBLISH VERIFICATION:\n\n[ ] Skill appears in top 3 for its primary specific query\n[ ] Skill appears in top 10 for its broad category query\n[ ] Skill appears for at least one synonym/alternative query\n[ ] Skill appears for at least one problem-oriented query" }, { "title": "Tips", "body": "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.\n\"Use when...\" phrases in descriptions are powerful because they match how users naturally frame searches: \"I need something for when X happens.\"\nInclude 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.\"\nProblem-oriented language (\"debugging why X fails\", \"troubleshooting Y\") matches a huge category of searches that purely descriptive skills miss entirely.\nTest with at least 5 different search queries before publishing. If your skill doesn't appear for its own primary topic, the description needs work.\nSlug names contribute to search matching. container-debug is better than cd-tool because the slug itself contains searchable terms.\nDon'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.\nThe registry is young. First-mover advantage is real — claim descriptive slugs and publish quality content now while competition is low.\nRe-publish with a version bump after optimizing your description. The embedding is regenerated on each publish, so description changes take effect immediately." } ], "body": "Skill Search Optimizer\n\nOptimize 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.\n\nWhen to Use\nA published skill isn't appearing in relevant searches\nWriting a skill description for maximum discoverability\nUnderstanding how ClawdHub's search indexes and ranks skills\nComparing your skill's visibility against competitors\nImproving an existing skill's search performance\nHow ClawdHub Search Works\nArchitecture\n\nClawdHub uses vector-based semantic search, not keyword matching:\n\nUser query → OpenAI embedding → Vector similarity search → Ranked results\n (text-embedding-*) (Convex vector index)\n\n\nKey implications:\n\nMeaning matters more than exact keywords — \"container debugging\" matches \"Docker troubleshooting\"\nBut keywords still help — the embedding model encodes specific terms with high signal\nDescription is the primary indexed field — content may contribute but description is dominant\nShort queries match broad descriptions — \"docker\" matches skills about containers generally\nSpecific queries match specific descriptions — \"debug crashed Docker container\" favors skills that mention debugging and crashes\nWhat Gets Indexed\nPRIMARY: description field (frontmatter)\nSECONDARY: name/slug field\nTERTIARY: skill content (body markdown) — likely summarized or truncated before embedding\n\nThe description field is your search ranking. Everything else is secondary.\n\nSearch API\n# How search is called internally\n# POST https://clawdhub.com/api/cli/search\n# Body: { \"query\": \"user search terms\", \"limit\": 10 }\n# Returns: ranked list of skills with similarity scores\n\n# CLI search\nnpx molthub@latest search \"your query\"\n\nDescription Optimization\nThe anatomy of a high-ranking description\n# Pattern:\n# [Action verb] + [specific scope]. Use when [trigger 1], [trigger 2], [trigger 3].\n# Also covers [related topic].\n\n# Example (strong):\ndescription: >-\n Schedule and manage recurring tasks with cron and systemd timers.\n Use when setting up cron jobs, writing systemd timer units,\n handling timezone-aware scheduling, monitoring failed jobs,\n implementing retry patterns, or debugging why a scheduled task didn't run.\n\n# Why it works:\n# - \"Schedule and manage recurring tasks\" → broad match for scheduling queries\n# - \"cron and systemd timers\" → exact match for specific tool queries\n# - \"Use when...\" triggers → matches natural-language questions\n# - \"debugging why a scheduled task didn't run\" → matches troubleshooting queries\n\nDescription formulas\nFormula 1: Tool-focused skill\ndescription: >-\n [Verb] with [tool/technology]. Use when [task 1], [task 2], [task 3].\n Covers [sub-topic 1], [sub-topic 2], and [sub-topic 3].\n\n\nExample:\n\ndescription: >-\n Debug Docker containers and Compose stacks. Use when inspecting\n container logs, diagnosing networking issues, troubleshooting\n build failures, or investigating resource usage. Covers exec,\n health checks, multi-stage builds, and distroless containers.\n\nFormula 2: Pattern/reference skill\ndescription: >-\n [Topic] patterns for [scope]. Use when [task 1], [task 2], [task 3].\n Also covers [related scope].\n\n\nExample:\n\ndescription: >-\n Regex patterns for validation, parsing, and text extraction across\n JavaScript, Python, Go, and grep. Use when writing regex for emails,\n URLs, IPs, dates, or custom formats. Also covers lookahead,\n lookbehind, and search-and-replace for code refactoring.\n\nFormula 3: Workflow/process skill\ndescription: >-\n [Process description] from [start] to [end]. Use when [scenario 1],\n [scenario 2], [scenario 3].\n\n\nExample:\n\ndescription: >-\n CI/CD pipeline configuration from commit to deployment. Use when\n setting up GitHub Actions, creating matrix builds, caching\n dependencies, building Docker images, or managing deployment secrets.\n\nKeyword strategy\n\nSemantic search understands synonyms, but being explicit helps:\n\n# Include both the formal term AND common synonyms\ndescription: >-\n SSH tunneling and port forwarding for remote access.\n Use when creating SSH tunnels, setting up port forwards,\n connecting through jump hosts (bastion hosts), managing\n SSH keys, or transferring files with scp and rsync.\n\n# \"tunneling\" and \"port forwarding\" are related but distinct queries\n# \"jump hosts\" and \"bastion hosts\" are synonyms — include both\n# \"scp and rsync\" catches file transfer queries\n\n\nTerms to include:\n\nPrimary tool names: docker, git, curl, make\nAction verbs: debug, test, deploy, monitor, parse\nCommon synonyms: container / Docker, CI/CD / pipeline / GitHub Actions\nProblem descriptions: debugging why X doesn't work, troubleshooting Y\nDescription length\nTOO SHORT (< 50 chars):\n \"Make things with Makefiles\"\n → Not enough semantic surface for the embedding model\n\nSWEET SPOT (80-200 chars):\n \"Write Makefiles for any project type. Use when setting up build\n automation, defining multi-target builds, or using Make for Go,\n Python, Docker, and Node.js. Also covers Just and Task.\"\n → Rich semantic content, multiple match angles\n\nTOO LONG (> 250 chars):\n [Long paragraph trying to list everything]\n → Gets truncated in search results display\n → Dilutes the embedding with low-signal words\n → Harder to read in listings\n\nContent Optimization\nHow body content affects search\n\nThe skill body (markdown content after frontmatter) likely contributes to search in two ways:\n\nSkill preview/summary: The registry may extract or summarize content for display\nSecondary embedding signal: Full content may be embedded separately or appended to description\n\nOptimization strategy:\n\nFront-load important terms in the first paragraph after the title\nUse headings that match search queries — \"## Encode and Decode\" matches better than \"## Section 2\"\nRepeat key terms naturally throughout the document (don't stuff, but don't avoid them either)\n# GOOD: Heading matches likely search query\n## Port Forwarding\n## Key Management\n## Connection Debugging\n\n# BAD: Generic headings with no search value\n## Getting Started\n## Advanced Usage\n## Miscellaneous\n\nFirst paragraph optimization\n\nThe first paragraph after the title is prime search real estate:\n\n# GOOD\n# SSH Tunnel\n\nCreate and manage SSH tunnels for secure remote access. Covers local,\nremote, and dynamic port forwarding, jump hosts, key management,\nagent forwarding, and file transfers with scp and rsync.\n\n# BAD\n# SSH Tunnel\n\nThis skill provides information about SSH.\n\nTesting Search Visibility\nManual testing\n# Test with the exact queries users would type\n\n# Broad query (should your skill appear?)\nnpx molthub@latest search \"docker\"\nnpx molthub@latest search \"testing\"\nnpx molthub@latest search \"build automation\"\n\n# Specific query (should your skill rank #1?)\nnpx molthub@latest search \"debug docker container\"\nnpx molthub@latest search \"write makefile for go project\"\nnpx molthub@latest search \"cron job not running\"\n\n# Problem-oriented query (does your skill match troubleshooting?)\nnpx molthub@latest search \"container networking not working\"\nnpx molthub@latest search \"why is my cron job not executing\"\n\n# Synonym query (does your skill match alternative terms?)\nnpx molthub@latest search \"bastion host\" # should match ssh-tunnel\nnpx molthub@latest search \"scheduled task\" # should match cron-scheduling\n\nTest matrix\n\nBuild a test matrix for your skill:\n\nSEARCH VISIBILITY MATRIX\nSkill: [your-skill-slug]\n\nQuery | Appears? | Rank | Competitor\n─────────────────────────────────────────────────────────────────\n[broad term] | Y/N | #__ | [who ranks above]\n[specific use case] | Y/N | #__ | [who ranks above]\n[problem/troubleshooting query] | Y/N | #__ | [who ranks above]\n[synonym for main topic] | Y/N | #__ | [who ranks above]\n[related but different topic] | Y/N | #__ | [expected?]\n\nTARGET: Appear in top 3 for specific queries, top 10 for broad queries\n\nIterative improvement\n# 1. Publish initial version\nnpx molthub@latest publish ./skills/my-skill \\\n --slug my-skill --name \"My Skill\" --version 1.0.0\n\n# 2. Test search visibility\nnpx molthub@latest search \"primary query\"\nnpx molthub@latest search \"secondary query\"\n\n# 3. If ranking is poor, update the description\n# Edit SKILL.md frontmatter\n\n# 4. Publish updated version\nnpx molthub@latest publish ./skills/my-skill \\\n --slug my-skill --name \"My Skill\" --version 1.0.1 \\\n --changelog \"Improve description for search visibility\"\n\n# 5. Re-test (embeddings update on publish)\nnpx molthub@latest search \"primary query\"\n\nCompetitive Positioning\nAnalyzing competing skills\n# Find skills in your category\nnpx molthub@latest search \"your topic\"\n\n# For each competing skill:\n# 1. Install it\nnpx molthub@latest install competitor-skill\n\n# 2. Read the description\nhead -10 skills/competitor-skill/SKILL.md\n\n# 3. Compare:\n# - Does their description cover queries yours doesn't?\n# - Are they using terms you should add?\n# - What's their content depth vs. yours?\n\nDifferentiation strategies\nSTRATEGY 1: Broader scope\n Competitor covers Docker. You cover Docker + Podman + containerd.\n Your description mentions all three → matches more queries.\n\nSTRATEGY 2: Deeper specificity\n Competitor covers \"git commands\". You cover \"git workflows\" with\n specific scenarios like bisect, worktree, and reflog recovery.\n Your description matches specific troubleshooting queries.\n\nSTRATEGY 3: Problem-oriented framing\n Competitor: \"Docker container management\"\n You: \"Debug Docker containers — logs, networking, crashes, resource issues\"\n Problem-oriented descriptions match how people actually search.\n\nSTRATEGY 4: Cross-tool coverage\n Competitor covers Make only. You cover Make + Just + Task.\n Your description mentions all three → broader match surface.\n\nFilling gaps vs. competing head-on\nMARKET ANALYSIS:\n\n1. Search for your intended topic\n2. Count results:\n 0 results → Blue ocean. Any reasonable skill will rank #1.\n 1-2 results → Low competition. A better skill wins easily.\n 3+ results → Competitive. Need clear differentiation.\n\nFor competitive categories, check the existing skills' quality:\n- Are their descriptions optimized? (Many aren't)\n- Are their examples working? (Test a few)\n- Do they cover the full scope? (Often they're narrow)\n\nA well-written skill with an optimized description will outrank\na mediocre skill even in a competitive category.\n\nRegistry Dynamics\nSearch behavior patterns\nCOMMON SEARCH PATTERNS:\n\n1. Tool name: \"docker\", \"git\", \"terraform\"\n → Match with explicit tool name in description\n\n2. Task description: \"deploy to production\", \"parse CSV\"\n → Match with action verbs and task phrases\n\n3. Problem statement: \"container not starting\", \"cron job failed\"\n → Match with troubleshooting language in description\n\n4. Comparison: \"jest vs vitest\", \"make vs just\"\n → Match by mentioning multiple tools in description\n\n5. How-to: \"how to set up CI/CD\", \"how to forward ports\"\n → Match with \"Use when setting up...\" pattern\n\nTiming and freshness\n- New skills get indexed immediately on publish\n- Updated skills get re-indexed on version bump\n- No known freshness bias (older skills don't rank lower)\n- The registry is young — early publishers have first-mover advantage\n- Slug ownership is permanent — claim good slugs early\n\nOptimization Checklist\nPRE-PUBLISH SEARCH OPTIMIZATION:\n\n[ ] Description follows the [Action] + [Scope] + [Use when] pattern\n[ ] Description is 80-200 characters\n[ ] Primary tool/topic names are in the description explicitly\n[ ] Common synonyms are included (jump host / bastion host)\n[ ] Troubleshooting/problem language is included\n[ ] Action verbs match how users search (debug, test, deploy, parse)\n[ ] First paragraph after title reinforces key terms\n[ ] Section headings use searchable phrases, not generic labels\n[ ] Slug is descriptive and matches the primary search term\n[ ] No competing skill has a clearly better description for the same queries\n\nPOST-PUBLISH VERIFICATION:\n\n[ ] Skill appears in top 3 for its primary specific query\n[ ] Skill appears in top 10 for its broad category query\n[ ] Skill appears for at least one synonym/alternative query\n[ ] Skill appears for at least one problem-oriented query\n\nTips\nThe 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.\n\"Use when...\" phrases in descriptions are powerful because they match how users naturally frame searches: \"I need something for when X happens.\"\nInclude 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.\"\nProblem-oriented language (\"debugging why X fails\", \"troubleshooting Y\") matches a huge category of searches that purely descriptive skills miss entirely.\nTest with at least 5 different search queries before publishing. If your skill doesn't appear for its own primary topic, the description needs work.\nSlug names contribute to search matching. container-debug is better than cd-tool because the slug itself contains searchable terms.\nDon'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.\nThe registry is young. First-mover advantage is real — claim descriptive slugs and publish quality content now while competition is low.\nRe-publish with a version bump after optimizing your description. The embedding is regenerated on each publish, so description changes take effect immediately." }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/gitgoodordietrying/skill-search-optimizer", "publisherUrl": "https://clawhub.ai/gitgoodordietrying/skill-search-optimizer", "owner": "gitgoodordietrying", "version": "1.0.0", "license": null, "verificationStatus": "Indexed source record" }, "links": { "detailUrl": "https://openagent3.xyz/skills/skill-search-optimizer", "downloadUrl": "https://openagent3.xyz/downloads/skill-search-optimizer", "agentUrl": "https://openagent3.xyz/skills/skill-search-optimizer/agent", "manifestUrl": "https://openagent3.xyz/skills/skill-search-optimizer/agent.json", "briefUrl": "https://openagent3.xyz/skills/skill-search-optimizer/agent.md" } }