Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add wrg32786/aigent-os --skill stuck -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/stuck/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/stuck/

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

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set58

The whole set →
frontend-slides The frontend-slides Claude Code skill creates animated HTML presentations and converts PowerPoint files into browser-ready slides. It activates for slide decks, talks, pitches, and PPT/PPTX web conversions. CX Codex +1 ★ 26repo stars sweep-links The sweep-links skill for Claude Code finds wikilinks that point to missing notes. Run it to scan a vault or locate dead links. CX Codex +1 ★ 26repo stars sweep-heat The sweep-heat Claude Code skill marks cold notes in the bottom 20 of HEAT_INDEX.md as dormant. Run it to inspect the heat index or change note statuses. CX Codex +1 ★ 26repo stars supersede The supersede Claude Code skill replaces outdated vault-note entries while retaining their history. The agent uses it for requests to update a note or mark a claim as no longer true. CX Codex +1 ★ 26repo stars status The status Claude Code skill reports the current operating state of aigent-OS. Ask for a snapshot of its mode, objective, next action, or blockers. CX Codex +1 ★ 26repo stars start start — a Claude Code skill that opens a home screen on first launch or when work resumes. It guides setup or gives a brief status update with an action menu. CX Codex +1 ★ 26repo stars sprite-spec This Claude Code skill turns pixel-art character ideas into sprite specifications. It activates for character or sprite-sheet design, covering palettes, proportions, and animation states. CX Codex +1 ★ 26repo stars solution-hunt 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. CX Codex +1 ★ 26repo stars

Project sponsors

Companies that keep this analytics open