When to Use
User asks how to do something, wonders whether a skill exists, wants a new capability, or asks for the best skill for a job. Use before solving manually when an installable skill could extend the agent, replace a weak skill, or offer a safer alternative.
Architecture
Memory lives in ~/skill-finder/. If ~/skill-finder/ does not exist or is empty, run setup.md.
~/skill-finder/
├── memory.md # Source mode + preferences + liked/passed skills
└── searches.md # Recent search history (optional)
Migration
If upgrading from a previous version, see migration.md for data migration steps.
The agent MUST check for legacy memory structure before proceeding.
Quick Reference
| Topic | File |
|---|---|
| Setup | setup.md |
| Memory template | memory-template.md |
| Search strategies | search.md |
| Evaluation criteria | evaluate.md |
| Skill categories | categories.md |
| Edge cases | troubleshooting.md |
Activation Signals
Activate when the user says things like:
- "How do I do X?"
- "Is there a skill for this?"
- "Can you do this better?"
- "Find a skill for X"
- "I need a safer or more maintained option"
- "What should I install for this task?"
Also activate when the user describes a missing capability, a repetitive workflow, or frustration with a current skill.
Search Sources
This skill can search two ecosystems:
| Source | Search | Install | Best for |
|---|---|---|---|
ClawHub |
npx clawhub search "query" |
npx clawhub install <slug> |
Curated registry search with built-in inspection |
Skills.sh |
npx skills find [query] |
npx skills add <owner/repo@skill> |
Broad open ecosystem from the skills CLI |
Default mode: search both sources, then compare results together.
Configurable modes:
- both — recommended default
- clawhub — only search ClawHub
- skills.sh — only search the Skills.sh ecosystem
Store the current mode in ~/skill-finder/memory.md. If the user has no saved preference yet, explain the two sources once, recommend both, and save the explicit choice.
Security Note
This skill uses npx clawhub and npx skills to discover and install skills from two different ecosystems. Review candidates before installation, keep installs opt-in, and keep the source attached to every recommendation.
Data Storage
This skill stores local preference data in ~/skill-finder/:
- Source mode, explicit preferences, liked skills, and passed skills in the local memory file inside ~/skill-finder/
- Optional recent search history in a local search log inside ~/skill-finder/
Create on first use: mkdir -p ~/skill-finder
Core Rules
1. Search Both Sources by Default
Unless the user has explicitly chosen otherwise, search ClawHub and Skills.sh for the same need, then compare the strongest results together.
Never assume a Skills.sh result can be installed with clawhub, or the reverse. Keep the source and install command attached to every recommendation.
2. Trigger on Capability Gaps, Not Just Explicit Search Requests
Do not wait only for "find a skill." Activate when the user describes missing functionality, asks how to do a task faster, or wants a better tool for a job.
3. Search by Need, Not Name
User says "help with PDFs" - think about what they actually need:
- Edit? -> npx clawhub search "pdf edit" and npx skills find pdf edit
- Create? -> npx clawhub search "pdf generate" and npx skills find pdf generate
- Extract? -> npx clawhub search "pdf parse" and npx skills find pdf parse
4. Evaluate Before Recommending
Never recommend blindly. Inspect strong candidates and check evaluate.md criteria:
- Description clarity
- Download count (popularity = maintenance)
- Last update (recent = active)
- Author or repository reputation
- Install scope and friction
For Skills.sh candidates, pay attention to the package source and install string the CLI returns.
5. Present a Decision, Not a Dump
Don't just list skills. Explain why each fits, who it is best for, and why the winner wins:
> "Best fit: pdf-editor from ClawHub — handles form filling and annotations, 2.3k downloads, updated last week. Matches your need for editing contracts better than the Skills.sh options."
When there are multiple good fits, rank the top 1-3 and call out tradeoffs clearly.
6. Learn Preferences and Source Mode
When user explicitly states what they value, confirm and update ~/skill-finder/memory.md:
- "Search both by default" -> set source mode to both
- "Only use Skills.sh for this workspace" -> set source mode to skills.sh
- "Only check ClawHub" -> set source mode to clawhub
- "I prefer minimal skills" -> add to Preferences
- "This one is great" -> add to Liked with reason
- "Too verbose" -> add to Passed with reason
Do not infer hidden preferences from behavior-only signals.
7. Check Memory First
Before recommending, read memory.md:
- Respect saved source mode unless the user overrides it
- Skip skills similar to Passed ones
- Favor qualities from Liked ones
- Apply stated Preferences
8. Respect Installation and Security Boundaries
If a candidate skill is marked risky by scanner output, or the install path is unclear:
- Explain the warning or ambiguity first
- Prefer a safer alternative
- Do not run force-install flags for the user
- Do not auto-accept install prompts with -y
- Do not choose global install scope unless the user explicitly wants it
- Install only with explicit user consent
9. Fallback Gracefully
If nothing is strong enough:
- Say what was searched
- Say which source mode was used
- Explain why the matches are weak
- Help directly or suggest creating a purpose-built skill
Search Commands
# ClawHub search and inspect
npx clawhub search "query"
npx clawhub inspect <slug>
npx clawhub install <slug>
npx clawhub list
# Skills.sh ecosystem
npx skills find [query]
npx skills add <owner/repo@skill>
npx skills list
npx skills check
npx skills update
# Example install string returned by `npx skills find`
npx skills add vercel-labs/agent-skills@vercel-react-best-practices
Workflow
- Detect - Is the user describing a capability gap or installable need?
- Load memory - Read
~/skill-finder/memory.mdfor source mode and preferences - Understand - What does user actually need?
- Search - Use
bothby default, or the saved single-source mode - Evaluate - Check quality signals (see
evaluate.md) - Compare - Rank results across both sources by fit + quality
- Recommend - Top 1-3 with clear reasoning and a winner
- Install or fallback - Install only with consent, otherwise help directly
- Learn - Store explicit feedback in memory
Recommendation Format
When presenting results, prefer this structure:
Best fit: <slug or owner/repo@skill>
Source: <ClawHub or Skills.sh>
Why it wins: <1-2 lines>
Install: <exact command>
Tradeoffs: <what it does not cover or where alternative is stronger>
Alternatives: <slug>, <slug>
Next step: Install now or continue without installing
Common Traps
- Waiting for the exact phrase "find a skill" -> misses proactive discovery moments
- Searching generic terms -> gets noise. Be specific: "react testing" not "testing"
- Searching only one ecosystem when the saved mode is
both - Recommending by name match only -> misses better alternatives with different names
- Mixing install commands between
ClawHubandSkills.sh - Ignoring download counts -> low downloads often means abandoned
- Not checking last update -> outdated skills cause problems
Security & Privacy
Data that leaves your machine:
- Search queries sent to ClawHub registry (public search)
- Search queries sent through the skills CLI / Skills.sh ecosystem
Data that stays local:
- All preferences in ~/skill-finder/memory.md
- Search history (if enabled)
This skill does NOT:
- Install skills without user consent
- Use force-install flags to skip scanner warnings
- Auto-confirm npx skills add with -y
- Switch to global install scope silently
- Collect hidden behavior data
- Access files outside ~/skill-finder/
Related Skills
Install with npx clawhub install <slug> if user confirms:
- skill-manager — manages installed skills, suggests updates
- skill-builder — creates new skills from scratch
- skill-update — updates existing skills
Feedback
- If useful:
clawhub star skill-finder - Stay updated:
clawhub sync
