solution-hunt — Claude Code skill: workarounds and installation
The solution-hunt Claude Code skill finds legitimate alternatives when a task hits a blocker. It searches local notes and skills, then looks through GitHub and documentation.
MIT ★ 26 updated 2026-11-16
npx skills add wrg32786/aigent-os --skill solution-hunt -a claude-codeWhat solution-hunt does
solution-hunt examines a blocker and lays out three routes: fix its cause, take a permitted alternate path, or replace the component causing trouble. It weighs implementation speed, side-effect risk, maintainability, and cost, then presents the strongest three options with steps for each.
Searches cover the local $AIGENT_VAULT, its skill and chain records, GitHub, and documentation through mcp__tavily__tavily_search and mcp__tavily__tavily_extract. Those documentation searches depend on the corresponding MCP tools. Once a route is chosen, the skill can carry it out and record a new pattern or recurring failure in memory files.
It rules out evading access controls, authentication, paywalls, or request limits through exploits. It also forbids concealing actions from the principal and using credentials found in screenshots or logs.
What it helps with
- find an alternate route around a blocked task
- compare a root-cause fix with replacing a component
- search local notes and external sources for a workaround
- record a newly found solution pattern
Example prompts for the agent
- Find a workaround: the build fails because a dependency is incompatible.
- Analyze this authentication blocker and suggest permitted alternatives.
- /solution-hunt
How to install solution-hunt
1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill solution-hunt -a claude-code2Manually: put the files in place
~/.claude/skills/solution-hunt/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/solution-hunt/
1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill solution-hunt -a codex2Manually: put the files in place
.agents/skills/solution-hunt/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill solution-hunt -a cursor2Manually: put the files in place
.cursor/skills/solution-hunt/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install wrg32786/aigent-os skills/solution-hunt2Manually: put the files in place
.github/skills/solution-hunt/SKILL.md1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill solution-hunt -a gemini-cli2Platform CLI
gemini skills install https://github.com/wrg32786/aigent-os --path skills/solution-huntManually: put the files in place
.devin/skills/solution-hunt/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill solution-hunt -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about solution-hunt
How do I install solution-hunt in Claude Code?
Run npx skills add wrg32786/aigent-os --skill solution-hunt -a claude-code. The skill file is at ~/.claude/skills/solution-hunt/SKILL.md.
What does solution-hunt do?
It searches local memory, skills, GitHub, and documentation for legitimate ways around a blocker. It compares the options and can implement the selected route.
What does solution-hunt need to work?
Local searches use $AIGENT_VAULT. Documentation and web searches use mcp__tavily__tavily_search and mcp__tavily__tavily_extract; GitHub searches use mcp__github__search_repositories and mcp__github__search_code.
Source text
SKILL.md · MIT
---
name: solution-hunt
description: "Find creative workarounds using local memory and skills. Use when a blocker requires an alternate solution."
---
# /solution-hunt — Creative workaround engine
When blocked, systematically search for legitimate alternate routes before declaring inability.
## Trigger
`/solution-hunt <blocker description>` or `/solution-hunt` (asks for blocker)
## Flow
### 1. Define the blocker
From argument or ask: "What's blocking you?" Get a concrete description of what can't be done and why.
### 2. Search local memory
Grep the vault for related concepts, prior solutions, similar blockers:
```
Grep pattern: {blocker keywords} in $AIGENT_VAULT/
```
### 3. Search local skills
Read `$AIGENT_VAULT/memory/SKILL_LEDGER.md`. Prefix-match against taxonomy paths. Check `memory/SKILL_CHAINS.md` for prior chains that solved similar problems.
### 4. Search GitHub
```
mcp__github__search_repositories: "{blocker} workaround" OR "{blocker} alternative"
mcp__github__search_code: "{specific error or API}" language:typescript OR language:python
```
### 5. Search docs and web
```
mcp__tavily__tavily_search: "{blocker} workaround" OR "{blocker} alternative solution"
mcp__tavily__tavily_extract: {relevant doc URLs found}
```
### 6. Identify 3 routes
| Route | Description |
|-------|-------------|
| **Direct fix** | Solve the root cause — fix the bug, update the dep, change the config |
| **Workaround** | Legitimate alternate path — different API, different tool, decompose the task |
| **Replace component** | Swap the blocking tool/dependency entirely |
### 7. Rank by tradeoffs
| Factor | Weight |
|--------|--------|
| Speed to implement | High |
| Risk of side effects | High |
| Maintainability | Medium |
| Cost (tokens, API calls, money) | Medium |
### 8. Present top 3
For each route, show:
- Description (1-2 sentences)
- Tradeoffs (speed/risk/maintenance)
- Confidence (high/medium/low)
- Implementation steps (3-5 bullets)
### 9. Execute chosen path
On user selection, implement the chosen route. If it requires a new skill, route through `/skill-hunt`.
### 10. Capture learning
- If the solution involved a new pattern: log to `memory/SKILL_CHAINS.md`
- If it exposed a gap: log to `memory/SKILL_GAPS.md`
- If it fixed a recurring issue: log to `memory/FAILURE_MODES.md` via `/learn-from-failure`
## Hard Boundary
> Creative workaround means legitimate alternate route. NEVER:
> - Bypass access controls or authentication
> - Violate terms of service of any platform
> - Exploit security vulnerabilities
> - Hide behavior from the principal
> - Bypass paywalls or rate limits through exploits
> - Use credentials from screenshots or logs
Per [[Capability Expansion Doctrine]] — the authority matrix governs what the AIgent may do. Expansion does not override authority levels.
## Related
- [[concepts/Capability Expansion Doctrine]] — the doctrine this skill serves
- [[memory/SKILL_LEDGER]] — local capability index
- [[memory/SKILL_CHAINS]] — proven multi-skill sequences
- [[memory/FAILURE_MODES.md]] — where failure learnings land
- `/skill-hunt` — external search when local solutions don't exist
- `/learn-from-failure` — structured failure capture
© wrg32786 · MIT · wrg32786/aigent-os