Stuck — Claude Code skill: what it does, how to install
The Stuck Claude Code skill guides an agent through possible next steps before it calls a task blocked. It activates when the agent runs out of ideas or is about to ask for help.
MIT ★ 26 updated 2026-11-16
npx skills add wrg32786/aigent-os --skill stuck -a claude-codeWhat Stuck does
Stuck gives the agent a six-step process to follow before stopping or asking a question. It starts with trying another approach and listing alternatives, then moves to asking a subagent a focused question and rereading the user’s request.
The agent can ask the user after those steps when the answer depends on a product choice, credentials, or behavior that code cannot clarify. Stopping comes last. The resulting report names the problem location, attempts already made, and the specific resource or decision needed to continue. A separate skill, /envelope, provides a format for asking a question.
What it helps with
- find another way past an error
- compare alternative approaches to a task
- catch a constraint missed in the request
- separate code questions from user-only decisions
- report what is blocking further work
Example prompts for the agent
- I’m stuck on this error. Work through the next steps before asking me for help.
- The code refers to a file I can’t find. Try different ways to locate it and report what you checked.
- This request leaves a decision unclear. Work out what the code can answer and what you need to ask me.
How to install Stuck
1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill stuck -a claude-code2Manually: put the files in place
~/.claude/skills/stuck/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/stuck/
1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill stuck -a codex2Manually: put the files in place
.agents/skills/stuck/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill stuck -a cursor2Manually: put the files in place
.cursor/skills/stuck/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install wrg32786/aigent-os skills/stuck2Manually: put the files in place
.github/skills/stuck/SKILL.md1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill stuck -a gemini-cli2Platform CLI
gemini skills install https://github.com/wrg32786/aigent-os --path skills/stuckManually: put the files in place
.devin/skills/stuck/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill stuck -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 Stuck
How do I install Stuck in Claude Code?
Run npx skills add wrg32786/aigent-os --skill stuck -a claude-code. The skill file is installed at ~/.claude/skills/stuck/SKILL.md.
What does Stuck do?
It gives an agent a sequence to follow when it hits an error or cannot see how to proceed, from exploring alternatives to asking a focused question or writing a stop report.
When should the agent stop according to Stuck?
Stopping is the final step, after trying another approach, considering alternatives, consulting a subagent, and rereading the request. The report names the problem location, steps taken, and what would let work continue.
Source text
SKILL.md · MIT
---
name: Stuck
description: "Walk a six-rung escalation ladder before declaring stuck. Use when out of ideas, hitting a wall, or unsure what approach to try before asking for help."
---
# Stuck
Before posting "I'm blocked", "not sure how to proceed", or "should I…?" — walk this ladder. **Stopping is the last resort, not the first response.** Most obstacles aren't blockers; they're the next thing to try.
## When to use
- About to surface to the principal for help
- Hit an error, an obstacle, or genuine ambiguity
- Tempted to type "I'm stuck" or "this isn't working"
- Use on prompts like: "blocked", "not sure how", "can't find", "need help", "should I ask", "stuck on", "this isn't working", "hitting a wall", "give up", "ask for help"
## The ladder (climb top-to-bottom; only stop at the bottom)
### Rung 1 — Try a different approach
Most obstacles aren't blockers. Did you try plan A? Try plan B.
- API call failed → retry with different params, fallback to alternative API
- Test broken → fix the test
- Compile error → read the error and fix it
- Library doesn't do what you expected → try a different method on the same library
### Rung 2 — Try 2-3 alternatives explicitly
Brainstorm 3 ways to solve this. Note them down. Try each.
- Can the data come from a different source?
- Can the problem be solved at a different layer (UI vs API vs DB)?
- Is there a workaround that gets 80% of the value?
If you can't think of 3 alternatives, you haven't thought hard enough — keep listing.
### Rung 3 — Use a helper
Spawn an exploration subagent with a **specific question**.
- Not "help me figure this out" — that's a survey.
- "Find all callers of `generateHeadline` and report whether any pass `null` for the `archetypeId` argument" — that's a question.
### Rung 4 — Re-read the user's request
Sometimes the path is in the wording. The principal often gives the answer; you just read past it.
- Did they specify a constraint you've been violating?
- Did they reference a file or pattern you haven't checked?
- Did they say "like X" — and have you actually looked at X?
### Rung 5 — Genuinely ask
Only if rungs 1-4 have failed AND the missing information is **user-only** (a product decision, a credential, an ambiguous behavior with no code-side answer).
The ask must be:
- **One question** (not a survey)
- **Surgical** (X or Y with consequences spelled out — see [`/envelope`](../envelope/SKILL.md))
- **Stated** ("After trying A, B, and C, the remaining ambiguity is whether X means Y or Z. Y produces outcome P; Z produces outcome Q. Which?")
### Rung 6 — Stop and report
Rare. Reserved for truly nothing-else-to-try situations.
The stop report must include:
- **Where stuck** (specific file/line/system)
- **What I tried** (rungs 1-4 explicitly listed, with what each yielded)
- **What would unblock** (specific resource, decision, or access — be precise)
## Concrete examples
### Example A: API rate-limited mid-port (NOT stuck)
- **Wrong:** "I'm blocked — Replicate is rate-limiting me."
- **Right:** Wait + retry (rung 1). If sustained → switch to a fallback provider (rung 2). If no fallback → use the library's built-in throttling (rung 1). Don't surface unless 30+ minutes of throttling persist.
### Example B: Code references a file you can't find (NOT stuck)
- **Wrong:** "I can't find `lib/whatever.ts` — where is it?"
- **Right:** Grep for the symbol the file exports. Read import paths in nearby files. Check if it was renamed. Ask only if 4 different searches fail.
### Example C: Genuinely ambiguous product decision (STUCK at rung 5)
- **Right:** "After reading the spec, the codebase, and PR #341, I see two valid interpretations of 'cap at 50 minutes': hard truncate or graceful early-end. Hard truncate is 5 LOC; graceful needs a 30-line state machine. Which?" — then wait.
## The shorthand
> Most "stuck" is actually "haven't tried the next approach." Three rungs of effort beat one rung of asking.
## Output format when stuck-checking
If you're about to surface, first output (silently to yourself, then act):
```
[STUCK CHECK]
Rung 1 (alternatives tried): {list}
Rung 2 (alternative paths considered): {list}
Rung 3 (subagent helper used): {yes/no — what question}
Rung 4 (re-read request): {what new clue surfaced}
Verdict: {SHIP / ASK / STOP}
```
If verdict is SHIP — proceed with the work.
If verdict is ASK — use [`/envelope`](../envelope/SKILL.md) to format the question (Envelope B).
If verdict is STOP — write the stop report.
© wrg32786 · MIT · wrg32786/aigent-os