ivangdavila_skill-finder/troubleshooting.md

Troubleshooting — Skill Finder

Reference for handling edge cases and common problems.

No Results Found

First: Try alternative search terms (see search.md for expansion strategies).

If still nothing:

1. Acknowledge honestly

   "I searched for skills related to [X] in the configured sources but didn't find any strong matches."

2. Offer direct help

   "I can help you with this directly using my general capabilities."

3. Suggest creation (for recurring needs)

   "If this is something you do often, you could create a custom skill with skill-builder."

Too Many Results

Problem: Search returns 10+ skills, hard to choose.

Solution:

1. Apply quality filters (see evaluate.md)
2. Check user's memory for preferences
3. Present only top 3 with clear differentiation
4. Ask clarifying question if still unclear

"Found several options. To narrow down:

• Need basic features or comprehensive?
• Prefer popular/stable or cutting-edge?"

Skill is Flagged as Suspicious

What it means: VirusTotal Code Insight detected potentially risky patterns (API calls, file access, etc.).

How to handle:

1. Inform user

   "This skill is flagged as suspicious by the security scanner. It may make external API calls or access files."

2. Check what triggered it

   npx clawhub inspect <slug> --files
   

3. Default to safer alternatives

   "I can recommend similar skills that are not flagged, then we pick the best match."

4. Do not skip scanner warnings

   • Never use force-install options
   • Prefer normal installation only for non-flagged options with explicit user consent

Skill Not Found (404)

Possible causes:

• Typo in slug
• Skill was deleted/hidden
• Author changed the name
• Skills.sh result points to a repo or skill path that changed

Solutions:

1. Search by description instead of exact name
2. Check for similar names: npx clawhub search "partial-name"
3. Re-run npx skills find [domain] if the missing result came from Skills.sh
4. The skill may have been replaced — search the domain

Conflicting Skills

Problem: User wants a skill that overlaps with one already installed.

Detection: Check npx clawhub list for existing skills in same domain.

Resolution:

1. Explain the overlap

   "You have git installed. The github skill adds PR/issue features on top of it — they work together."

2. Or warn about conflict

   "You have eslint-basic installed. eslint-pro covers the same but more — want to replace?"

User Changed Their Mind

After installation:

• Uninstall: npx clawhub uninstall <slug>
• Remove Skills.sh install: npx skills remove <skill>
• Don't reinstall: Add to Passed in memory.md with reason

During recommendation:

• Just move on, no need to store unless they explain why

Outdated Skill

Signs:

• Last update >6 months ago
• Low recent downloads
• References old versions of tools

How to handle:

"This skill was last updated [X months] ago. It references [old version]. Want to try anyway, or should I look for alternatives?"

Source Mismatch

Problem: A result was found in one ecosystem, but the install command shown belongs to the other.

Resolution:

1. Restate the source clearly
2. Use the install command that belongs to that source only
3. If needed, present an equivalent result from the other ecosystem instead

"This result is from Skills.sh, so the correct install path is npx skills add owner/repo@skill, not clawhub install."

Memory Issues

Memory file corrupted or malformed:

1. Backup: cp ~/skill-finder/memory.md ~/skill-finder/memory.md.bak
2. Recreate from memory-template.md
3. Ask user to re-state key preferences

Memory too large (>50 lines):

1. Archive old entries
2. Keep only recent Liked/Passed
3. Preserve all Preferences (they're stable)